Guia de integração do Xero para planejamento da produção com SkyPlanner APS

O Xero é um único produto em nuvem com arquitetura multilocatária, e todas as organizações usam a mesma API. A Accounting API é uma REST API disponível em https://api.xero.com/api.xro/2.0/, com JSON ou XML. Cada chamada identifica a organização no cabeçalho Xero-tenant-id. (fonte)

Os endpoints necessários para a programação da produção:

• Dados mestres: /Contacts (clientes e fornecedores), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Demanda: /Quotes (Status ACCEPTED, LineItems) e, para oficinas que faturam antes de produzir, /Invoices com Type ACCREC.
• Suprimentos: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems com ItemCode).
• Envio de dados de volta: /Quotes/{QuoteID}/History, /Invoices, /Quotes e a Projects API em https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Todos os endpoints de listagem aceitam o cabeçalho If-Modified-Since, de modo que cada sincronização lê apenas o que mudou. As criações e atualizações são enviadas em lotes. Não há endpoints para listas de materiais, roteiros de produção ou ordens de produção.

“Webhooks allow you to subscribe to certain events that happen in Xero.” (Os webhooks permitem assinar notificações de determinados eventos que ocorrem no Xero.) (fonte) Os eventos relevantes para a programação da produção são Contact e Invoice, cada um com CREATE e UPDATE.

Como funcionam:

• Um webhook por aplicativo abrange todas as organizações conectadas.
• Cada envio contém um array de eventos com o ID do recurso e o tipo de evento. O receptor consulta o recurso em seguida.
• Cada envio é assinado por meio de um cabeçalho x-xero-signature, gerado a partir da chave de webhook do aplicativo. O Xero envia uma verificação “Intent to receive” antes de iniciar os envios.
• O Xero tenta reenviar notificações que falharam e desativa webhooks com falhas persistentes. Por isso, o receptor responde rapidamente e faz o processamento depois.

Orçamentos, itens e pedidos de compra não têm eventos de webhook. O SkyPlanner os consulta em intervalos curtos com If-Modified-Since, o que consome uma chamada por entidade quando nada mudou.

1. Carga inicial de dados mestres. Consulte todas as páginas de contatos e itens e, depois, de pedidos de compra em aberto e orçamentos aceitos. Crie clientes no SkyPlanner usando o ContactID do Xero como external_identifier, e produtos e materiais usando o código do item como chave. Em seguida, cadastre o que o Xero não armazena: centros de trabalho, etapas de processo por produto, turnos, afastamentos e tempos de preparação. A importação por CSV ou Excel é a forma mais rápida de cadastrar as etapas de processo.

2. Sincronização de pedidos. Consulte os orçamentos periodicamente com If-Modified-Since. Quando um orçamento passa para ACCEPTED, o SkyPlanner cria um pedido com o número do orçamento em external_order_number. O valor de delivery_date vem do campo que sua oficina usa para a data prometida, mapeado durante a implantação. Cada item gera operações conforme as etapas de processo do produto. Os itens dos pedidos de compra tornam-se materiais a receber na data prevista de chegada, de modo que as operações aguardam a entrega. Uma leitura completa, todas as noites, dos orçamentos e pedidos de compra em aberto captura o que tiver ficado de fora.

3. Envio da programação e dos dados de conclusão de volta ao Xero. Três chamadas registram os resultados no Xero:

• PUT /Quotes/{QuoteID}/History adiciona uma nota com a data de conclusão planejada. Um orçamento aceito só permite alterações no contato e nas notas; por isso, a data fica na nota do histórico. (fonte)
• Quando o pedido é concluído, POST /Invoices cria uma fatura de venda com Type ACCREC, Status DRAFT, o contato e os itens do orçamento, além do número do orçamento como Reference. O responsável pela contabilidade aprova e envia a fatura no Xero.
• POST /Quotes com QuoteID e Status INVOICED encerra o orçamento. A passagem de Accepted para Invoiced é uma mudança de status válida na Accounting API.

4. Apontamentos no chão de fábrica e horas de projeto. Os operadores apontam o trabalho com SkyPlanner Mobile Confirmations, Production Timer ou Quick Log Mode. O avanço atualiza a programação imediatamente, e o Autopilot replaneja o restante. Para trabalhos de projeto, o SkyPlanner envia as horas como registros na tarefa do projeto, com o usuário do Xero, a data e a duração. (fonte)

5. Responsabilidade pelos dados e regras de conflito. Documente essas definições antes da entrada em operação:

• O Xero não tem objetos de produção. Mantenha as etapas de processo de cada produto no SkyPlanner, vinculadas ao código do item no Xero. Mantenha os códigos dos itens estáveis.
• Orçamentos não têm webhook. Consulte-os em intervalos curtos com If-Modified-Since, respeitando os limites por minuto e por dia.
• Orçamentos aceitos ficam bloqueados. Após a aceitação, só é possível alterar os dados de contato e as notas. Por isso, a data prometida é lida uma única vez, no momento da aceitação, e a data planejada é gravada como nota no histórico.
• O estoque acompanha as faturas de venda e de compra. O Xero movimenta o saldo em estoque dos itens controlados por meio de faturas de venda, faturas de compra e notas de crédito. Combine com o responsável pela contabilidade como contabilizar os produtos acabados e os materiais consumidos.
• As horas de projeto exigem usuários do Xero. Os apontamentos de horas pertencem a um usuário do Xero. Defina quais operadores terão suas horas lançadas no Xero Projects e mantenha as dos demais no SkyPlanner.
• Escopos granulares. Solicite escopos granulares desde o início, pois os escopos amplos estão sendo descontinuados.
• Nível do aplicativo. O nível de parceria determina quantas organizações um aplicativo pode conectar e quantas chamadas pode fazer por dia. Escolha o nível de acordo com o número de fábricas.