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

A Oracle já definiu o caminho. A partir da versão 2026.1, novas integrações devem ser desenvolvidas com os serviços web SuiteTalk REST e OAuth 2.0. A partir da versão 2027.1, não serão permitidas novas integrações com SOAP ou Token-Based Authentication (TBA). Os endpoints SOAP serão desativados na versão 2028.2. Qualquer integração de programação iniciada hoje deve usar REST.

Autenticação

Para um sistema de programação da produção com comunicação entre servidores, use OAuth 2.0 Client Credentials (máquina a máquina). O caminho na administração é Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup. Você envia um certificado público e o associa a uma entidade, a uma função e ao registro de integração. Cada registro de integração comporta no máximo cinco certificados ativos.

Crie uma função exclusiva para a integração: permissão de visualização para itens, revisões de BOM, roteiros de produção e centros de trabalho; permissão de edição para ordens de produção, conclusões e baixas de materiais. A API REST do SkyPlanner (referência da API) usa JWT, portanto o middleware armazena as duas credenciais.

Eventos: não há webhook padrão

A documentação da Oracle não descreve nenhum webhook nativo de saída. O padrão usado é um script SuiteScript User Event em Work Order (afterSubmit) que coloca uma chamada de saída na fila por meio de N/task ou de um script Map/Reduce, usando N/https para fazer a chamada. Nunca faça chamadas de saída síncronas em afterSubmit: elas são executadas durante o salvamento feito pelo usuário, portanto um endpoint lento atrasa ou impede o salvamento.

Os eventos de usuário não cobrem todas as formas de alteração. Atualizações em massa e importações CSV podem ocorrer sem acioná-los. Combine o script de evento com consultas periódicas de reconciliação via SuiteQL usando lastmodifieddate, para que nenhuma alteração passe despercebida. No sentido inverso, os próprios webhooks do SkyPlanner acionam a gravação dos dados no NetSuite, que recebe as novas datas assim que o plano muda.

1. Carga inicial de dados mestres. Leia primeiro os centros de trabalho e, depois, os itens, as revisões de BOM e os roteiros de produção com SuiteQL. Os roteiros fazem referência aos centros de trabalho, por isso a ordem importa. Durante o teste, exporte os mesmos dados para CSV e importe-os no SkyPlanner. A programação é validada antes de qualquer código ser desenvolvido.

2. Sincronização de ordens. Importe as ordens de produção com status Released e In Process. Decida desde o início se as ordens com status Planned também serão incluídas. Se forem, trate-as como demanda provisória. Sincronize os pedidos de compra em aberto no mesmo ciclo para que a programação verifique cada operação considerando o estoque e os materiais a receber, não apenas o estoque.

3. Gravação da programação no NetSuite. Quando a programação muda, um webhook do SkyPlanner envia as novas datas das operações ao middleware. O middleware envia PATCH /services/rest/record/v1/manufacturingOperationTask/{id} (referência de registros da Oracle) com startDate e endDate para cada operação alterada. Um PATCH adicional no cabeçalho de workOrder define os campos Production Start e End Date. Grave apenas datas e, caso utilize um campo de sequência personalizado, esse campo. Nunca grave de volta quantidades ou dados de BOM. Para atualizar várias operações em uma única transação, um pequeno RESTlet salva toda a lista de operações em uma chamada. A API de registros continua sendo a opção padrão.

4. Confirmações do chão de fábrica. Os operadores registram o trabalho no SkyPlanner Mobile Confirmations. O middleware lança cada confirmação por meio das transformações de Work Order com POST /services/rest/record/v1/workOrder/{id}/!transform/workOrderCompletion, enviando startOperation, endOperation, a quantidade concluída e o tempo registrado nas linhas de operação. Já as ordens de produção sem WIP são encerradas com !transform/assemblyBuild. O uso de Work Order Completion via REST exige o recurso Manufacturing Work In Process. Os lançamentos de estoque e custos continuam no NetSuite.

5. Idempotência e novas tentativas. Cada conclusão leva o ID do registro de horas do SkyPlanner como ID externo no NetSuite. Os IDs externos são únicos por tipo de registro, portanto um webhook reenviado é rejeitado como duplicado, em vez de lançar quantidades e custos duas vezes. As gravações passam por uma fila. Quando uma chamada falha (limite de simultaneidade, registro bloqueado, certificado expirado), ela é repetida e registrada em log. Qualquer falha que persista fica visível para a equipe do SkyPlanner responsável pelo suporte à integração.

6. Regras de responsabilidade pelos dados. O NetSuite define o que é produzido: item, quantidade, BOM, roteiro de produção e local. O SkyPlanner define quando e onde: sequência de operações, centro de trabalho, início e término. As datas editadas no NetSuite são sobrescritas na próxima gravação de retorno. Por isso, bloqueie Production Start/End Date com uma personalização de formulário ou um workflow.

• Ordens de produção sem roteiro. Uma ordem de produção sem Manufacturing Routing não tem operações para programar. A Oracle faz a mesma observação sobre seu próprio sistema de programação da produção: “Work orders not associated with a NetSuite routing should not be scheduled.” (Ordens de produção não associadas a um roteiro do NetSuite não devem ser programadas.) Identifique essas ordens com SuiteQL antes da entrada em produção.
• Os centros de trabalho têm poucos dados. Um centro de trabalho do NetSuite é um Group com duas contagens, Machine Resources e Labor Resources (ambas com valor padrão 0), e um Work Calendar, geralmente “Default Work Calendar”. Carregue os centros de trabalho uma vez e depois mantenha no SkyPlanner os centros de trabalho individuais, os turnos por pessoa, as ferramentas, a matriz de tempos de preparação e os centros de trabalho alternativos.
• Qualidade dos dados de Setup Time e Run Rate. A programação com capacidade infinita do NetSuite usa esses campos, mas, como desconsidera a capacidade, os valores incorretos passam despercebidos. Uma programação da produção que respeita a capacidade real das máquinas e das equipes expõe esses erros já no primeiro dia.
• Com ou sem WIP. Com Manufacturing WIP, a produção é lançada por meio de Work Order Issue, Work Order Completion e Work Order Close. Sem WIP, usa-se um Assembly Build. A integração lança conclusões para itens com WIP e montagens para os demais, por isso o modelo de cada item faz parte do mapeamento.
• Advanced Manufacturing na mesma conta. Se a conta também usa o Advanced Manufacturing SuiteApp, seus registros Manufacturing Work Bench devem corresponder exatamente ao roteiro de produção: sequência da operação, nome da operação e centro de trabalho. Defina qual sistema determina as datas das operações. Dois sistemas de programação atuando sobre as mesmas ordens de produção significam dois planos concorrentes.
• Limites de simultaneidade. As chamadas de serviços web e RESTlet compartilham um único limite de simultaneidade da conta, definido pelo nível de serviço mais 10 por licença SuiteCloud Plus. Consultas periódicas em paralelo, registro a registro, atingem esse limite rapidamente. Use SuiteQL com paginação para leituras e coloque as gravações em fila.
• A atualização do sandbox apaga a configuração M2M. Os mapeamentos de credenciais de cliente OAuth 2.0 são apagados na atualização do sandbox e não são copiados entre contas. Um certificado expirado ou revogado interrompe a sincronização até que um novo mapeamento seja criado. Configure alertas para falhas de autenticação.