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

A integração utiliza duas interfaces já incluídas no Business Central:

1. API v2.0 para dados comerciais e de inventário. Disponibiliza items, itemVariants, itemLedgerEntries, locations, unitsOfMeasure, salesOrders, salesOrderLines, purchaseOrders, purchaseOrderLines, vendors, customers e employees. Não inclui entidades de fabrico, pelo que os dados de produção são obtidos através da segunda interface.
2. Serviços Web OData v4 para o fabrico. Qualquer página do Business Central pode ser publicada como serviço Web OData v4 na página Web Services. Escolha o tipo de objeto Page, o ID da página e um nome para o serviço e, em seguida, selecione Published. O endpoint fica disponível, sem código AL nem extensões para implementar. A integração publica as páginas padrão de ordens de produção lançadas, Prod. Order Routing Lines, centros de trabalho, centros de máquina e gamas operatórias, disponíveis em /ODataV4/Company('{name}')/{ServiceName}.

As páginas publicadas permitem leitura e escrita. Segundo a Microsoft: “If an editable page is exposed as a web service, the data in the underlying table can be accessed and modified by an OData call,” (Se uma página editável for exposta como serviço Web, é possível aceder aos dados da tabela subjacente e modificá-los através de uma chamada OData), utilizando PATCH para as atualizações. É assim que as datas programadas são devolvidas ao Business Central, através da mesma página e com a mesma validação que um planeador utiliza.

Não utilize SOAP. A Microsoft classificou os serviços Web SOAP como obsoletos, e a possibilidade de publicar páginas da interface da Microsoft como serviços SOAP é removida na vaga 2 de lançamentos de 2026 (v29).

O Business Central permite subscrições de webhooks através de POST /api/v2.0/subscriptions em entidades da API v2.0 como items e salesOrders. Aplicam-se as seguintes regras:

• A criação de uma subscrição exige um handshake: o seu endpoint tem de devolver o validationToken com 200 OK.
• As subscrições expiram ao fim de três dias. Renove-as com PATCH; o processo de handshake volta a ser executado.
• As notificações contêm o caminho do recurso, changeType e o seu clientState, não o registo completo. O registo é lido posteriormente.
• As notificações não são imediatas: o Business Central online espera 30 segundos após a primeira alteração. Se forem alterados mais de 1.000 registos nesse intervalo, as alterações chegam numa única notificação collection.
• Máximo de 200 subscrições de webhooks por ambiente online.

As ordens de produção, as linhas de gama operatória e as encomendas de compra são consultadas a cada poucos minutos nas páginas publicadas e em purchaseOrders. A filtragem por ordens e encomendas em aberto, juntamente com a paginação, mantém o número de pedidos bem abaixo dos limites do Business Central.

O SkyPlanner envia webhooks quando o estado ou a programação mudam, pelo que a gravação dos dados no Business Central é acionada por eventos.

1. Carregamento inicial de dados mestre. Obtenha as gamas operatórias e as BOM de produção no estado Certified, bem como os centros de trabalho e de máquina, a partir das páginas publicadas. Obtenha os artigos e as unidades de medida através da API v2.0. Defina cuidadosamente a correspondência entre cada centro de trabalho ou de máquina e um centro de trabalho do SkyPlanner: decida se um centro de trabalho com três centros de máquina passa a ser um grupo de centros de trabalho ou três centros de trabalho.

2. Sincronização de ordens e encomendas. Leia nas páginas publicadas as ordens de produção no estado Released (e Firm Planned, se as programar), com as respetivas linhas de gama operatória e componentes. Leia também as linhas de encomendas de compra em aberto através da API v2.0. O SkyPlanner considera o material encomendado disponível na data de entrega da encomenda de compra e atualiza as existências quando esta é marcada como Delivered. Assim, a programação verifica tanto as existências como as compras por receber.

Nunca programe ordens de produção no estado Planned: segundo a Microsoft, o Business Central “deletes them the next time you run planning.” (elimina-as da próxima vez que executar o planeamento). A Planning Worksheet continua a propor aprovisionamento e o SkyPlanner programa as ordens firmes com base na capacidade real.

3. Escrita da programação no Business Central. A página padrão Prod. Order Routing é publicada como serviço Web OData v4. Para cada operação que o motor tenha programado ou reagendado, o SkyPlanner envia um PATCH para a respetiva linha de gama operatória com o ETag If-Match. Define Starting Date-Time e Ending Date-Time, bem como Type e No. quando a operação é transferida para uma máquina alternativa.

O PATCH executa os triggers da página e da tabela, pelo que o Business Central valida os campos com a sua própria lógica, exatamente como quando um planeador edita a página Prod. Order Routing. Os campos Starting e Ending Date-Time da linha da ordem de produção são atualizados em conformidade. As quantidades, o estado e os custos continuam sob o controlo do Business Central.

4. Confirmações na fábrica. Os operadores registam o trabalho com SkyPlanner Mobile Confirmations ou Production Timer, e os registos de tempos mantêm a programação atualizada. A produção realizada pode continuar a ser registada no Business Central como antes, através do Production Journal ou do Output Journal.

Se pretender registar a produção realizada e os consumos de forma totalmente automática, é adicionada uma página API padrão do Business Central para efetuar lançamentos no diário de produção realizada. O SkyPlanner passa então a registar o tempo de preparação, o tempo de execução e a quantidade produzida por operação. Os lançamentos atualizam os Capacity Ledger Entries, e o registo da produção realizada na última operação da gama operatória adiciona o artigo às existências.

Escolha um único canal para registar a produção realizada. Os lançamentos ficam duplicados se forem efetuados tanto pelo SkyPlanner como pelo Production Journal do Business Central.

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

A principal fonte de conflitos são as ações Refresh e Replan nas ordens de produção. Segundo a Microsoft: “If you use the Refresh action to recalculate production order lines, Business Central deletes the existing production order lines and calculates new lines.” (Se utilizar a ação Refresh para recalcular as linhas da ordem de produção, o Business Central elimina as linhas existentes e calcula novas linhas.) A ação Replan também pode alterar as necessidades de capacidade, e o recálculo dos componentes “deletes previous changes in the components.” (elimina as alterações anteriores aos componentes).

Trate uma ordem atualizada com Refresh como uma nova versão, volte a sincronizá-la e deixe o SkyPlanner reprogramá-la. Com Autopilot, o SkyPlanner reprograma automaticamente quando há alterações na produção.

• Unidades nas gamas operatórias. Setup Time aplica-se por ordem de produção e Run Time por artigo produzido, cada um com o seu próprio Unit of Measure Code. Wait Time e Move Time não consomem capacidade do centro de trabalho. Se a unidade do centro de trabalho for Days, um dia corresponde a 24 horas, não a um turno de oito horas. Faça a conversão na importação; caso contrário, todas as durações estarão erradas.
• Calendários desatualizados. Só existe capacidade depois de executar Calculate Work Center Calendar para o horizonte em causa. Verifique o campo Calendar Entries Available Until antes do carregamento inicial.
• Capacidade dos centros de máquina oculta. Com Consolidated Calendar desativado, só é planeada a capacidade do próprio centro de trabalho: “The machine center capacity is excluded.” (A capacidade do centro de máquina é excluída.) Leia diretamente a capacidade dos centros de máquina em vez de confiar nos totais dos centros de trabalho.
• Capacity e Efficiency. O Business Central calcula a duração como Run Time / Efficiency / Capacity, e os movimentos de calendário calculados já incluem ambos os fatores. Aplique Efficiency à eficiência do centro de trabalho do SkyPlanner uma única vez, não duas.
• Alternate Work Center é apenas informativo. Segundo a Microsoft, “isn’t automatically included in planning processes.” (não é incluído automaticamente nos processos de planeamento). Modele explicitamente as alternativas como centros de trabalho alternativos no SkyPlanner.
• Limitação de pedidos. Os limites online aplicam-se por utilizador, e uma entidade de serviço conta como um utilizador: 6.000 pedidos OData numa janela deslizante de 5 minutos e 5 pedidos em simultâneo. O tamanho de página está limitado a 20.000 registos, um $batch a 100 operações e o tempo limite de uma operação é de 8 minutos. Se a taxa de pedidos for excedida, é devolvido o código 429. Agrupe os pedidos em lotes, use paginação e consulte apenas as alterações, em vez de recarregar todos os dados.
• Licenciamento. O módulo Manufacturing só está disponível na experiência Premium. Os utilizadores com Essentials não podem iniciar sessão numa empresa configurada como Premium.