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

O ProShop disponibiliza duas vias para um sistema externo de programação da produção, descritas na documentação da API do ProShop para programadores:

1. ProShop GraphQL API. “ProShop provides a GraphQL API, available via HTTP(S).” (O ProShop disponibiliza uma API GraphQL através de HTTP(S).) Existe um único endpoint: cada chamada é um pedido HTTP POST para <proshop root>/api/graphql, com query, variables e operationName num corpo JSON. Cada módulo tem uma consulta no singular para obter um registo e uma consulta no plural para obter listas. As listas são paginadas com pageSize (20 por predefinição) e pageStart, devolvem records e totalRecords e aceitam os argumentos filter e query, que correspondem à funcionalidade Advanced Search de cada módulo. O esquema permite introspeção. (Introdução à API do ProShop)
2. Recently Updated Records API. “A simple REST interface allows external integrations to request information between arbitrary points in time.” (Uma interface REST simples permite às integrações externas pedir informações entre dois momentos quaisquer.) Faça uma chamada a <proshop root>/recentlyupdatedrecords com start (ISO 8601) e, opcionalmente, end e filterby, por exemplo workorders,workcells,purchaseorders,timetracking,deletions. A equipa ProShop tem de ativar primeiro o índice. (Recently Updated Records API)

A escrita é feita através de mutações GraphQL. Time Tracking Login é o exemplo documentado, e o acesso de escrita é concedido por módulo através de âmbitos.

A documentação do ProShop para programadores não descreve webhooks de saída nem subscrições GraphQL. Os dados do ProShop são consultados periodicamente, e a Recently Updated Records API reduz o custo dessas consultas: peça tudo o que foi criado, alterado ou eliminado desde a última execução, filtrando pelos tipos de registo necessários à programação. Depois, obtenha as ordens de fabrico alteradas pelo respetivo número através de GraphQL. Segundo o ProShop, esta abordagem é mais rápida do que consultar por lastModifiedTime.

Uma opção habitual é consultar as ordens de fabrico e os registos de tempos a cada cinco minutos, e as peças e encomendas de compra a cada hora. O SkyPlanner envia webhooks quando o estado ou a programação muda, pelo que o envio de dados de volta ao ProShop é acionado por eventos.

1. Carga inicial de dados mestre. Percorra as páginas de Parts, Work Cells, Users, Tools e Fixtures com consultas GraphQL no plural. Defina um valor elevado de pageSize para a primeira carga e use totalRecords para controlar o ciclo de leitura. Decida como mapear as células de trabalho: as que representam máquinas passam a centros de trabalho e as que representam pessoas passam a pessoal. Assim, a mesma operação pode reservar uma máquina e o respetivo operador em conjunto.

2. Sincronização de ordens de fabrico. Leia as ordens de fabrico ativas com as respetivas operações, tempos previstos e registos de BOM, bem como as encomendas de compra em aberto. O SkyPlanner considera o material encomendado disponível na data de entrega da encomenda de compra e atualiza o stock quando esta é marcada como Delivered. A deteção de alterações é feita através de Recently Updated Records com filterby=workorders,purchaseorders,deletions.

3. Envio da programação de volta ao ProShop. Quando o motor agenda ou desloca uma tarefa, um webhook do SkyPlanner aciona uma mutação GraphQL que define as datas planeadas da ordem de fabrico, ao abrigo de uma Authorization com workorders:w. A previsão de cumprimento de prazos do ProShop e as datas em que os materiais comprados são necessários passam então a basear-se nas datas do SkyPlanner.

4. Confirmações na produção. Os operadores registam o trabalho com SkyPlanner Mobile Confirmations ou Production Timer, e os registos de tempos mantêm a programação atualizada. Pode optar por enviar os tempos reais de volta para o ProShop Time Tracking, associados à operação da ordem de fabrico. Caso contrário, os operadores continuam a registar os tempos no ProShop como antes, e o SkyPlanner lê-os através de timetracking.

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

Escolha um único sistema para escrever as datas das ordens de fabrico. Quando o SkyPlanner passa a programar uma célula de trabalho, os responsáveis pelo planeamento deixam de reordenar a lista dessa célula no ProShop, para que os dois planos nunca entrem em conflito.

• Os tempos previstos são decisivos. O ProShop calcula a duração a partir dos tempos estimados de preparação e de ciclo. Obtenha os tempos previstos atuais, não a estimativa original, e separe a preparação da execução para que a matriz de tempos de preparação possa substituir o valor único de preparação.
• Células de trabalho que representam pessoas. Uma célula de trabalho pode ser uma pessoa. Faça a correspondência com o pessoal no SkyPlanner, não com máquinas. Caso contrário, cada operador passa a ser tratado como uma máquina em paralelo.
• O Time Tracking precisa de um utilizador. Desde abril de 2026, a mutação Time Tracking Login “requires user context” (requer o contexto de um utilizador) e não é autorizada com Client Credentials. Envie os tempos dos operadores através do OAuth 2.0 Authorization Flow ou mantenha o registo de tempos no ProShop e leia esses dados.
• Ative o índice de alterações. O Recently Updated Records só funciona depois de a equipa do ProShop o ativar. Peça a ativação na primeira semana.
• Registos ITAR. O ProShop filtra os registos sujeitos a restrições ITAR por ligação. Uma opção em Developer System Config determina se são devolvidos como valores nulos ou omitidos. Acorde quais as ordens de fabrico a que a integração terá acesso e trate os valores nulos em todas as leituras.
• Operações subcontratadas. As operações realizadas nos fornecedores representam tempo decorrido, não capacidade interna. Modele-as como etapas apenas com duração.