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

O Katana é um único produto na nuvem com arquitetura multi-tenant, pelo que todos os clientes utilizam a mesma API. Trata-se de uma REST API, versão v1, disponível em https://api.katanamrp.com/v1, com uma especificação OpenAPI 3.0 em https://api.katanamrp.com/v1/openapi.json. A documentação está disponível no Katana Developer Hub.

Os endpoints necessários para programar a produção:

• Dados mestre: /products, /materials, /variants, /recipe_rows, /bom_rows, /product_operation_rows.
• Ordens: /manufacturing_orders, /manufacturing_order_operation_rows, /manufacturing_order_recipe_rows, /manufacturing_order_productions.
• Sequência: /manufacturing_order_rerank.
• Oferta e procura: /inventory, /purchase_orders, /purchase_order_rows, /sales_orders, /sales_order_rows.

Não existe um endpoint /resources. Os recursos surgem nos campos resource_id e resource_name das linhas de operações dos produtos e das ordens de fabrico.

Registe um webhook com POST /webhooks, um URL HTTPS e os eventos de que necessita. (fonte) Estes são os eventos úteis para a programação da produção:

• manufacturing_order.created, .updated, .deleted, .in_progress, .blocked, .done
• manufacturing_order_operation_row.created, .updated, .in_progress, .paused, .completed
• current_inventory.material_updated, .material_out_of_stock
• purchase_order.* e purchase_order_row.*, incluindo os eventos de receção
• product.*, product_recipe_row.* e sales_order.*

Os payloads são mínimos: o tipo de recurso, a ação e um href. O recetor obtém o objeto completo a partir do href. Cada envio inclui um cabeçalho x-sha2-signature (HMAC SHA-256) para verificação. O seu endpoint tem de responder com 20X no prazo de 10 segundos. O Katana faz três novas tentativas: aos 30 segundos, aos 2 minutos e aos 15 minutos.

1. Carregamento inicial dos dados mestre. Percorra as páginas de produtos, materiais, variantes, linhas de fórmulas e linhas de operações dos produtos, controlando o ritmo dos pedidos para respeitar o limite. Crie os centros de trabalho do SkyPlanner a partir dos recursos distintos presentes nas linhas de operações e mantenha uma correspondência de chaves 1:1. Defina os turnos, as ausências e as horas extraordinárias no SkyPlanner para cada centro de trabalho, uma vez que o Katana não dispõe de um calendário de recursos.

2. Sincronização de ordens. Subscreva os eventos de ordens de fabrico, linhas de operações, existências e encomendas de compra. A cada evento, obtenha o objeto a partir do respetivo href e atualize a tarefa. O SkyPlanner considera o material encomendado disponível na data de entrega da encomenda de compra e atualiza o stock quando esta é recebida. Uma reconciliação noturna com filtros por data de atualização deteta quaisquer eventos que tenham escapado.

3. Escrita da programação no Katana. Duas chamadas transferem o plano para o Katana:

• POST /manufacturing_order_rerank “moves one or more manufacturing orders to an exact place in the production schedule” (move uma ou mais ordens de fabrico para uma posição exata na programação da produção). Aceita até 250 ordens de fabrico em aberto por pedido, colocando-as no início, no fim, antes ou depois de uma determinada ordem de fabrico. (fonte)
• PATCH /manufacturing_orders/{id} define production_deadline_date. O Katana só aceita este valor quando o cálculo automático de prazos está desativado para essa instalação fabril. (fonte)

A reordenação tem efeitos para além da lista. No Katana, “higher-priority MOs reserve required materials and subassemblies first” (as ordens de fabrico com maior prioridade reservam primeiro os materiais e subconjuntos necessários). Assim, a sequência do SkyPlanner também determina a que ordem de fabrico é atribuído o stock no Katana.

4. Confirmações no chão de fábrica. Os operadores registam o trabalho com SkyPlanner Mobile Confirmations, Production Timer ou Quick Log Mode. O SkyPlanner escreve o estado e o tempo efetivamente gasto na linha de operação da ordem de fabrico. Se, em alternativa, a fábrica mantiver a Katana Shop Floor App, o SkyPlanner lê os eventos das linhas de operações. Escolha um único canal de registo por fábrica.

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

• O modo de definição dos prazos elimina datas. “Once automatic mode is enabled, all manual deadlines will be overwritten and cannot be restored.” (Ao ativar o modo automático, todos os prazos manuais serão substituídos e não poderão ser recuperados.) Escolha o modo uma única vez, no arranque do projeto.
• Sem calendário de recursos. Não deduza os turnos a partir do valor único de Weekly throughput. Defina-os por centro de trabalho no SkyPlanner.
• Recursos apenas nas linhas de operações. Mantenha inalterados os nomes dos recursos no Katana, pois são a chave de correspondência com os centros de trabalho do SkyPlanner.
• Unidades de tempo. O valor de planned_time_parameter é expresso em segundos: por unidade nas operações do tipo per-unit e como total nos tipos process, setup e fixed. Mapeie corretamente o tipo; caso contrário, as durações ficarão erradas por um fator igual à quantidade.
• Grupos de produção por encomenda. Numa reordenação, as MOs associadas à mesma encomenda de venda mantêm-se juntas, pelo que deve sequenciá-las como um grupo.
• O comportamento da reordenação mudou. Desde 7 de outubro de 2026, os endpoints de reordenação colocam as ordens exatamente na posição pedida. As integrações desenvolvidas para o comportamento anterior precisam de ser testadas novamente. (fonte)