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

A Oracle já definiu o rumo. A partir da versão 2026.1, as novas integrações devem ser desenvolvidas com os serviços web SuiteTalk REST e OAuth 2.0. A partir da versão 2027.1, deixam de ser 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 que comunica entre servidores, utilize OAuth 2.0 Client Credentials (máquina a máquina). O caminho de administração é Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup. Carregue um certificado público e associe-o a uma entidade, a uma função e ao registo de integração. Cada registo de integração admite, no máximo, cinco certificados ativos.

Crie uma função dedicada à integração: permissão de consulta para artigos, revisões de BOM, gamas operatórias e centros de trabalho; permissão de edição para ordens de fabrico, conclusões e saídas de materiais. A API REST do SkyPlanner (referência da API) utiliza JWT, pelo que o middleware guarda ambas as credenciais.

Eventos: não existe um webhook padrão

A documentação da Oracle não descreve qualquer webhook nativo de saída. A solução consiste num script SuiteScript User Event no registo Work Order (afterSubmit), que coloca uma chamada de saída em fila através de N/task ou de um script Map/Reduce. A chamada é feita com N/https. Nunca faça chamadas síncronas em afterSubmit: a chamada é executada durante a gravação feita pelo utilizador, pelo que um endpoint lento atrasa ou faz falhar essa gravação.

Os eventos de utilizador não abrangem todas as formas de alteração. As atualizações em massa e as importações CSV podem não os acionar. Combine o script de eventos com consultas periódicas de reconciliação em SuiteQL sobre lastmodifieddate, para que nenhuma alteração fique por detetar. No sentido inverso, os webhooks do próprio SkyPlanner desencadeiam a escrita no NetSuite, que recebe assim as novas datas logo que o plano é alterado.

1. Carregamento inicial dos dados mestre. Leia primeiro os centros de trabalho e depois os artigos, as revisões de BOM e as gamas operatórias com SuiteQL. As gamas operatórias fazem referência aos centros de trabalho, pelo que a ordem é importante. Durante o teste, exporte os mesmos dados para CSV e importe-os para o SkyPlanner. A programação é validada antes de se escrever qualquer código.

2. Sincronização de ordens. Obtenha as ordens de fabrico nos estados Released e In Process. Decida logo no início se pretende incluir as ordens de fabrico no estado Planned. Se as incluir, trate-as como procura provisória. Sincronize as encomendas a fornecedores em aberto no mesmo ciclo, para que a programação verifique cada tarefa face às existências e aos materiais a receber, e não apenas às existências.

3. Escrita da programação no NetSuite. Quando a programação muda, um webhook do SkyPlanner envia as novas datas das operações para o middleware. O middleware envia PATCH /services/rest/record/v1/manufacturingOperationTask/{id} (referência de registos 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. Escreva apenas as datas e, caso o utilize, um campo personalizado de sequência. Nunca escreva quantidades nem dados da BOM no NetSuite. Para atualizar várias operações numa única transação, um pequeno RESTlet guarda toda a lista de operações numa só chamada. A API de registos continua a ser a opção predefinida.

4. Confirmações do chão de fábrica. Os operadores registam o trabalho no SkyPlanner Mobile Confirmations. O middleware envia cada confirmação através das transformações de Work Order, com POST /services/rest/record/v1/workOrder/{id}/!transform/workOrderCompletion, incluindo startOperation, endOperation, a quantidade concluída e o tempo registado nas linhas das operações. As ordens de fabrico sem WIP são encerradas com !transform/assemblyBuild. A utilização de Work Order Completion via REST requer a funcionalidade Manufacturing Work In Process. Os movimentos de existências e os lançamentos de custos mantêm-se no NetSuite.

5. Idempotência e novas tentativas. Cada registo de conclusão usa o ID do registo de tempos do SkyPlanner como ID externo no NetSuite. Os IDs externos são únicos por tipo de registo, pelo que um webhook reenviado é rejeitado como duplicado, em vez de lançar quantidades e custos duas vezes. As operações de escrita passam por uma fila. Quando uma chamada falha (limite de simultaneidade, registo bloqueado, certificado expirado), é repetida e fica registada. As falhas que persistirem ficam visíveis para a equipa SkyPlanner que presta suporte à integração.

6. Regras de responsabilidade pelos dados. O NetSuite define o que é fabricado: artigo, quantidade, BOM, gama operatória e localização. O SkyPlanner define quando e onde: sequência de operações, centro de trabalho, início e fim. As datas alteradas no NetSuite são substituídas no envio seguinte dos dados de programação. Por isso, bloqueie os campos Production Start/End Date através de uma personalização do formulário ou de um fluxo de trabalho.

• Ordens de fabrico sem gama operatória. Uma ordem de fabrico sem Manufacturing Routing não tem operações para programar. A Oracle diz o mesmo sobre o seu próprio sistema de programação da produção, que respeita a capacidade disponível: “Work orders not associated with a NetSuite routing should not be scheduled.” (As ordens de fabrico sem uma gama operatória NetSuite associada não devem ser programadas.) Identifique-as com SuiteQL antes da entrada em produção.
• Os centros de trabalho têm poucos dados. No NetSuite, um centro de trabalho é um Group com duas contagens, Machine Resources e Labor Resources (ambas com o valor predefinido de 0), e um Work Calendar, normalmente “Default Work Calendar”. Carregue os centros de trabalho uma vez e depois mantenha no SkyPlanner os centros de trabalho individuais, turnos por pessoa, ferramentas, matriz de tempos de preparação e centros de trabalho alternativos.
• Qualidade dos valores de Setup Time e Run Rate. A programação com capacidade infinita do NetSuite utiliza estes campos, mas, como ignora a capacidade, os valores incorretos passam despercebidos. Uma programação da produção que respeite a capacidade real revela-os logo no primeiro dia.
• Com ou sem WIP. Com Manufacturing WIP, a produção é registada através de Work Order Issue, Work Order Completion e Work Order Close. Sem WIP, utiliza-se um Assembly Build. A integração lança conclusões para os artigos com WIP e registos Assembly Build para os restantes, pelo que o modelo de cada artigo faz parte do mapeamento.
• Advanced Manufacturing na mesma conta. Se a conta também utilizar a Advanced Manufacturing SuiteApp, os respetivos registos Manufacturing Work Bench têm de corresponder exatamente à gama operatória: sequência de operações, nome da operação e centro de trabalho. Defina qual dos sistemas determina as datas das operações. Dois sistemas a programar as mesmas ordens de fabrico significam dois planos em conflito.
• Limites de simultaneidade. As chamadas a serviços web e RESTlets partilham um único limite de simultaneidade da conta, definido pelo nível de serviço, acrescido de 10 por licença SuiteCloud Plus. As consultas periódicas em paralelo, registo a registo, atingem rapidamente esse limite. Utilize SuiteQL com paginação para as leituras e coloque as operações de escrita numa fila.
• A atualização do ambiente de testes apaga a configuração M2M. As associações de credenciais de cliente OAuth 2.0 são eliminadas quando o ambiente de testes é atualizado e não são copiadas entre contas. Um certificado expirado ou revogado interrompe a sincronização até ser criada uma nova associação. Configure alertas para falhas de autenticação.