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

O Xero é um único produto na nuvem com arquitetura multi-inquilino, e todas as organizações utilizam 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 programar a produção:

• Dados mestre: /Contacts (clientes e fornecedores), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Procura: /Quotes (Status ACCEPTED, LineItems) e, para oficinas que faturam primeiro, /Invoices com Type ACCREC.
• Aprovisionamento: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems com ItemCode).
• Escrita no Xero: /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, pelo que cada sincronização lê apenas o que foi alterado. As criações e atualizações são enviadas em lote. Não existe nenhum endpoint para listas de materiais, gamas operatórias ou ordens de produção.

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

Como funcionam:

• Um webhook por aplicação abrange todas as organizações ligadas.
• Cada envio contém um array de eventos com o ID do recurso e o tipo de evento. O recetor lê o recurso em seguida.
• Cada envio é assinado com um cabeçalho x-xero-signature, gerado a partir da chave do webhook da aplicação. Antes de iniciar os envios, o Xero faz uma verificação “Intent to receive” (intenção de receber).
• O Xero repete os envios que falham e desativa um webhook que falhe continuamente. Por isso, o recetor responde rapidamente e processa os dados depois.

Os orçamentos, os artigos e as encomendas a fornecedores não têm eventos de webhook. O SkyPlanner consulta-os a intervalos curtos com If-Modified-Since, o que consome uma chamada por entidade quando nada foi alterado.

1. Carregamento inicial dos dados mestre. Percorra as páginas de contactos e artigos e, depois, as de encomendas a fornecedores em aberto e orçamentos aceites. Crie os clientes no SkyPlanner com o ContactID do Xero como external_identifier, e os produtos e materiais com o código do artigo como chave. Em seguida, crie o que não existe no Xero: centros de trabalho, etapas do processo por produto, turnos, férias e tempos de preparação. A importação por CSV ou Excel é a forma mais rápida de carregar as etapas do processo.

2. Sincronização de encomendas. Consulte periodicamente os orçamentos com If-Modified-Since. Quando um orçamento passa a ACCEPTED, o SkyPlanner cria uma encomenda com o número do orçamento como external_order_number. O valor de delivery_date provém do campo que a sua oficina utiliza para a data acordada, mapeado durante a implementação. Cada linha de artigo dá origem a tarefas de acordo com as etapas do processo do produto. As linhas das encomendas a fornecedores dão origem a material a receber na data de chegada prevista, pelo que as tarefas aguardam a entrega. Uma leitura integral, todas as noites, dos orçamentos e das encomendas a fornecedores em aberto deteta tudo o que tenha escapado.

3. Atualização do Xero com a programação e a conclusão das encomendas. Três chamadas registam os resultados no Xero:

• PUT /Quotes/{QuoteID}/History adiciona uma nota com a data de conclusão prevista. Um orçamento aceite só permite alterar o contacto e as notas, pelo que a data fica registada na nota do histórico. (fonte)
• Quando a encomenda é concluída, POST /Invoices cria uma fatura de venda com Type ACCREC, Status DRAFT, o contacto e as linhas do orçamento e o número do orçamento como Reference. O responsável pela contabilidade aprova-a e envia-a no Xero.
• POST /Quotes com o QuoteID e Status INVOICED fecha o orçamento. A passagem de Accepted para Invoiced é uma alteração de estado válida na Accounting API.

4. Confirmações na fábrica e tempo de projeto. Os operadores registam o trabalho com SkyPlanner Mobile Confirmations, Production Timer ou Quick Log Mode. O progresso atualiza imediatamente a programação, e o Autopilot reprograma o restante trabalho. No caso de trabalhos de projeto, o SkyPlanner envia as horas como registos de tempo na tarefa do projeto, com o utilizador Xero, a data e a duração. (fonte)

5. Responsabilidade pelos dados e regras de conflito. Documente-as antes da entrada em produção:

• O Xero não tem objetos de produção. Mantenha as operações de cada produto no SkyPlanner, associadas ao código do artigo no Xero. Não altere os códigos dos artigos.
• As propostas não têm webhook. Consulte-as a intervalos curtos com If-Modified-Since, respeitando os limites por minuto e por dia.
• As propostas aceites ficam bloqueadas. Após a aceitação, só é possível alterar os dados de contacto e as notas. Por isso, a data prometida é lida uma única vez, no momento da aceitação, e a data planeada é registada numa nota do histórico.
• As existências acompanham as faturas de venda e de compra. O Xero atualiza as quantidades em stock através das faturas de venda, faturas de compra e notas de crédito dos artigos com controlo de existências. Defina com o responsável pela contabilidade como serão contabilizados os produtos acabados e os materiais consumidos.
• As horas de projeto exigem utilizadores do Xero. Os registos de horas pertencem a um utilizador do Xero. Decida que operadores registam horas no Xero Projects e mantenha os restantes registos no SkyPlanner.
• Âmbitos de autorização granulares. Solicite âmbitos granulares desde o início, pois os âmbitos mais abrangentes estão a ser descontinuados.
• Escalão da aplicação. O escalão de parceiro define quantas organizações uma aplicação pode ligar e quantas chamadas pode efetuar por dia. Escolha o escalão em função do número de fábricas.