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

O QuickBooks Online é um único produto em nuvem com arquitetura multilocatária, e todas as empresas usam a mesma Accounting API. Trata-se de uma REST API na versão v3. Cada chamada é direcionada a uma empresa pelo seu realm ID: https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}, com um host de sandbox separado para testes. As requisições e respostas usam JSON, e o parâmetro minorversion seleciona a versão do esquema. (fonte)

As entidades necessárias para quem programa a produção:

• Dados mestres: Customer, Item (Inventory, NonInventory, Service), Employee, Vendor.
• Demanda: Estimate (TxnStatus Accepted, linhas, ShipDate) e, para fábricas que faturam antecipadamente, Invoice ou SalesReceipt.
• Suprimentos: PurchaseOrder (POStatus Open, linhas com itens e quantidades), Bill.
• Gravação no QuickBooks: Estimate, Invoice, TimeActivity, InventoryAdjustment.

As leituras usam o endpoint de consulta, por exemplo: select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'. As atualizações podem ser parciais, por isso o SkyPlanner envia apenas os campos que altera. A Accounting API não tem entidades de pedido de venda, roteiro de produção, centro de trabalho ou ordem de produção.

Os webhooks do QuickBooks notificam o aplicativo quando há alterações nos dados de uma empresa conectada. “Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.” (Os webhooks notificam você automaticamente sempre que há alterações nos dados da empresa do usuário final no QuickBooks Online.) (fonte) As entidades relevantes para a programação da produção são:

• Customer, Item, Employee
• Estimate, Invoice, SalesReceipt
• PurchaseOrder, Bill
• TimeActivity

As operações incluem Create, Update, Delete, Merge e Void. A notificação contém o nome da entidade, o ID, a operação e a data e hora da última atualização, não o registro completo. O sistema que recebe a notificação consulta o registro em seguida.

A captura de alterações de dados (GET /cdc?entities=...&changedSince=...) retorna tudo o que mudou desde uma data e hora, dentro de uma janela recente de consulta retroativa. O SkyPlanner usa esse recurso para uma reconciliação noturna, de modo que um webhook perdido nunca deixe um pedido desatualizado. TimeActivity não é coberto pela captura de alterações de dados, por isso sua reconciliação é feita por consulta. (fonte)

1. Carga inicial de dados mestres. Consulte clientes, itens, funcionários e pedidos de compra em aberto com paginação pelo endpoint de consulta. Crie os clientes no SkyPlanner usando o ID do QuickBooks como external_identifier, e os produtos e materiais usando o ID do item como chave. Depois, cadastre o que o QuickBooks não armazena: centros de trabalho, etapas do 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 do processo.

2. Sincronização de pedidos. Assine os webhooks de Estimate, Invoice, Item e PurchaseOrder. Quando um orçamento passa para Accepted, o SkyPlanner o lê e cria um pedido com o número do orçamento em external_order_number e a data de envio em delivery_date. Cada linha gera operações conforme as etapas do processo do produto. As linhas dos pedidos de compra em aberto geram materiais a receber, fazendo com que as operações aguardem a entrega. A captura noturna de alterações de dados recupera qualquer evento perdido.

3. Envio da programação e dos dados de conclusão ao QuickBooks. Quatro chamadas gravam os resultados no QuickBooks:

• Uma atualização parcial de Estimate grava ShipDate, para que a data prometida no QuickBooks acompanhe o plano.
• Quando o pedido é concluído, POST /invoice cria a fatura com as linhas do orçamento e um LinkedTxn para esse orçamento. A Intuit permite vincular uma fatura por orçamento, por isso o tratamento das entregas parciais é acordado na definição de escopo.
• POST /timeactivity grava as horas apontadas por cada operador, vinculando-as ao funcionário, ao cliente e a um item de serviço. As horas faturáveis podem então ser adicionadas à fatura no QuickBooks.
• POST /inventoryadjustment aumenta o estoque de produtos acabados e baixa os materiais consumidos. A Intuit disponibiliza essa entidade no QuickBooks Online Plus e Advanced nos EUA. (fonte)

4. Apontamentos no chão de fábrica. Os operadores registram o trabalho com SkyPlanner Mobile Confirmations, Production Timer ou Quick Log Mode. O avanço atualiza a programação imediatamente, e o Autopilot reprograma o restante. As horas são enviadas ao QuickBooks como registros de horas. Se a fábrica mantiver o QuickBooks Time para a folha de pagamento, escolha um único canal para as horas das operações durante a definição de escopo.

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

• Os pedidos de venda ficam nas telas do QuickBooks. Os planos Plus e Advanced oferecem pedidos de venda no aplicativo, mas a integração lê orçamentos aceitos ou faturas, no caso de fábricas que faturam antes de produzir. Defina um único gatilho para que todos os pedidos entrem da mesma forma.
• O QuickBooks não tem roteiros de produção. Mantenha as etapas do processo de cada produto no SkyPlanner, vinculadas à chave do item no QuickBooks.
• Cada orçamento pode ser vinculado a uma única fatura. Entregas parciais exigem uma regra, como um orçamento por entrega.
• Ajustes de estoque conforme o plano e a região. Os planos Plus e Advanced nos EUA oferecem esse recurso. Nas demais regiões, defina com seu contador como os produtos acabados serão registrados no QuickBooks.
• Ordens de produção do Intuit Enterprise Suite. Se você as utiliza, defina qual sistema será responsável pela fabricação e pelas reservas de componentes.
• Os pacotes são somente leitura pela API. Itens do tipo Group não podem ser criados pela API, portanto mantenha os pacotes no QuickBooks.
• Rotação do refresh token. Armazene o refresh token mais recente após cada renovação; caso contrário, a conexão será interrompida.