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

• Visma Net ERP API. Interface REST com uma especificação OpenAPI ainda intitulada “Visma.net ERP API v1”, com caminhos v1 e v2. A URL base é https://api.finance.visma.net. O domínio antigo, integration.visma.net, tem o tráfego limitado desde 1 de fevereiro de 2026 e está sendo desativado (aviso).
• SalesOrder service v3 em https://salesorder.visma.net. Os endpoints v1 e v2 de pedidos de venda chegaram ao fim de sua vida útil.
• Webhooks pelo Visma Developer Portal.
• Background API. O cabeçalho erp-api-background coloca chamadas demoradas em uma fila, retorna 202 com um ID de tarefa e notifica quando o resultado está pronto.
• Cenários de importação e exportação no Visma Net, com provedores de dados CSV, Excel ou SQL, para cargas pontuais de dados mestres.

A API não tem endpoints para ordens de produção, roteiros de produção ou centros de trabalho, pois esses objetos não existem no Visma Net. Os dados para a programação vêm de itens, kits, pedidos e estoque:

• GET /v1/inventory: itens de estoque e itens sem controle de estoque, incluindo o indicador de kit e a classe do item
• GET /v1/KitSpecifications/{kitInventoryID}/{revisionID}: linhas de componentes por revisão
• GET /v1/kitassembly: montagens existentes, com filtros por tipo e status
• SalesOrder service v3: demanda com datas solicitadas e linhas de pedido
• GET /v1/inventorysummary/{inventoryNumber}: quantidades em estoque e disponíveis por depósito
• GET /v1/purchaseorder e GET /v2/PurchaseReceipt: materiais a receber e recebimentos

Todos os endpoints de listagem aceitam lastModifiedDateTime com lastModifiedDateTimeCondition, além de pageNumber e pageSize. Assim, cada sincronização pode ser incremental.

Os webhooks do Visma Developer Portal abrangem os eventos relevantes para a programação:

• Eventos Inventory Item Created, Updated e Changed
• Eventos Purchase Order Changed e Status Changed
• Eventos Sales Order Changed e Status Changed, em migração para o publicador SalesOrderService

Não há eventos para Kit assembly nem Kit specifications. O SkyPlanner consulta esses objetos periodicamente com filtros lastModifiedDateTime. Os saldos de estoque são consultados a cada execução da programação. No sentido inverso, o SkyPlanner envia webhooks quando há mudanças de estado ou na programação.

1. Carga inicial de dados mestres. Leia os itens de estoque, as classes de itens e a revisão mais recente de Kit specification de cada kit. Mapeie cada linha de componente para um material no SkyPlanner. Em seguida, cadastre o que o Visma Net não armazena: centros de trabalho, turnos, etapas do processo com tempos de preparação e execução, a matriz de tempos de preparação e os requisitos de ferramentas. Importe esses dados em CSV ou Excel. Essa é a maior parte do projeto.

2. Sincronização de pedidos. Escolha um modelo de demanda:

• Por pedido de venda. As linhas em aberto de pedidos de venda de itens de kit se tornam pedidos no SkyPlanner, com a data solicitada como prazo de entrega.
• Por montagem. Os registros de Kit assembly criados no Visma Net com status On hold se tornam operações no SkyPlanner.

Os pedidos de compra em aberto são importados com suas datas. O SkyPlanner considera o material comprado disponível na data de entrega do pedido de compra e atualiza o estoque quando o pedido é marcado como Delivered. Com esses dados e o resumo do estoque, a programação verifica tanto os materiais em estoque quanto as compras a receber.

3. Gravação da programação no ERP. Na configuração por pedido de venda, o SkyPlanner cria um registro de Kit assembly do tipo Production para cada operação programada. Ele define o item de kit, a revisão, o depósito, a quantidade e os componentes, e vincula a montagem à linha do pedido de venda. A data da montagem é a data de conclusão planejada. Quando o Autopilot move a operação, uma chamada PUT atualiza a data antes da liberação.

O objeto Kit assembly tem um único campo Date. Por isso, os horários de cada operação ficam no SkyPlanner, e o Visma Net recebe a data relevante para vendas e estoque.

4. Apontamentos no chão de fábrica. Os operadores registram o trabalho com Mobile Confirmations ou Production Timer, e os apontamentos de tempo mantêm a programação atualizada. Quando a última etapa é concluída, o SkyPlanner chama a ação de liberação do Kit assembly. A liberação lança a produção e o consumo de componentes, e o lote contábil é gerado na sequência. As horas são consolidadas em registros semanais de Employee time card ou em transações de projeto, quando o trabalho é orientado por projetos.

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

Uma alteração em uma Kit specification cria uma nova revisão. Leia novamente a revisão mais recente e refaça o mapeamento, pois apenas a última revisão pode ser usada na montagem. As alterações manuais nos componentes de um Kit assembly continuam válidas no Visma Net. Por isso, o SkyPlanner consulta novamente esse registro antes da liberação.

• Não há roteiros de produção para importar. Todas as etapas do processo e os tempos de preparação e execução são definidos inicialmente no SkyPlanner. Preveja o esforço necessário e defina o responsável.
• Advanced logistics. O Kit assembly exige o grupo Advanced logistics. No Standard logistics, registre a produção com Inventory receipt e Inventory issue.
• Revisões bloqueadas. Uma revisão de Kit specification já utilizada não pode ser editada, e somente a revisão mais recente pode ser usada na montagem.
• Unidades de medida. O Kit assembly tem sua própria unidade de medida. Na importação, alinhe essa unidade às quantidades do SkyPlanner.
• Consultas periódicas sem eventos. Os kits não têm webhooks. Consulte apenas as alterações com base em lastModifiedDateTime, em vez de recarregar todos os dados, para respeitar o limite de requisições por hora.
• Endpoints atuais. Desenvolva a integração usando apenas api.finance.visma.net e SalesOrder service v3.
• Aprovação do tenant. A autenticação pelo fluxo client credentials falha enquanto o administrador do tenant não aprovar o aplicativo. Agende essa etapa com antecedência.
• Folhas de horas semanais. As folhas de horas exigem Advanced financials e são semanais. Consolide as horas dos operadores por semana ou registre-as como transações de projeto.