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

O Katana é um produto em nuvem com arquitetura multilocatário, por isso todos os clientes usam a mesma API. É uma REST API, na 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á no Katana Developer Hub.

Os endpoints necessários para a programação:

• Dados mestres: /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.
• Suprimento e demanda: /inventory, /purchase_orders, /purchase_order_rows, /sales_orders, /sales_order_rows.

Não existe um endpoint /resources. Os recursos aparecem como resource_id e resource_name nas linhas de operações dos produtos e das ordens de produção.

Cadastre um webhook com POST /webhooks, informando uma URL HTTPS e os eventos necessários. (fonte) Estes são os eventos úteis para a programaçã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 recebimento
• product.*, product_recipe_row.* e sales_order.*

Os payloads são enxutos: contêm o tipo de recurso, a ação e um href. O receptor busca o objeto completo pelo href. Cada entrega inclui um cabeçalho x-sha2-signature (HMAC SHA-256) para verificação. Seu endpoint deve responder com 20X em até 10 segundos. O Katana faz três novas tentativas: após 30 segundos, 2 minutos e 15 minutos.

1. Carga inicial dos dados mestres. Percorra as páginas de produtos, materiais, variantes, linhas de receitas e linhas de operações dos produtos, controlando as chamadas para não exceder o limite de requisições. Crie os centros de trabalho no SkyPlanner a partir dos recursos distintos presentes nas linhas de operações e mantenha uma correspondência de chaves 1:1. Configure turnos, afastamentos e horas extras por centro de trabalho no SkyPlanner, pois o Katana não tem calendário de recursos.

2. Sincronização das ordens. Assine os eventos de ordens de produção, linhas de operações, estoque e pedidos de compra. A cada evento, busque o objeto pelo href e atualize a operação. O SkyPlanner considera o material comprado disponível na data de entrega do pedido de compra e atualiza o estoque quando o pedido é recebido. Uma conciliação noturna com filtros por data de atualização identifica qualquer evento perdido.

3. Envio da programação de volta ao Katana. Duas chamadas transferem a programação 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 produção para uma posição exata na programação da produção). Aceita até 250 ordens de produção em aberto por requisição, posicionadas no início, no fim, antes ou depois de uma determinada ordem. (fonte)
• PATCH /manufacturing_orders/{id} define production_deadline_date. O Katana só aceita esse valor quando o cálculo automático de prazo está desativado para a unidade fabril correspondente. (fonte)

A reordenação tem efeito além da lista. No Katana, “higher-priority MOs reserve required materials and subassemblies first” (as ordens de produção com maior prioridade reservam primeiro os materiais e subconjuntos necessários). Assim, a sequência definida pelo SkyPlanner também determina qual ordem recebe o estoque no Katana.

4. Apontamentos no chão de fábrica. Os operadores registram o trabalho com SkyPlanner Mobile Confirmations, Production Timer ou Quick Log Mode. O SkyPlanner grava o status e o tempo real de execução na linha de operação da ordem de produção. Se a fábrica optar por manter o Katana Shop Floor App, o SkyPlanner lê os eventos das linhas de operações. Escolha um único canal de apontamento por fábrica.

5. Responsabilidade pelos dados e regras para conflitos. Documente essas definições antes da entrada em produção:

• O modo de definição de prazos apaga as 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 sobrescritos e não poderão ser restaurados.) Defina o modo uma única vez, na reunião de início do projeto.
• Sem calendário de recursos. Não deduza os turnos a partir do valor único de Weekly throughput. Configure os turnos de cada centro de trabalho no SkyPlanner.
• Recursos apenas nas linhas de operação. Mantenha os nomes dos recursos inalterados no Katana, pois eles são a chave de identificação dos centros de trabalho no SkyPlanner.
• Unidades de tempo. planned_time_parameter é expresso em segundos: por unidade nas operações por unidade e como tempo total nos tipos process, setup e fixed. Mapeie o tipo corretamente; caso contrário, as durações ficarão incorretas por um fator correspondente à quantidade.
• Grupos de produção sob encomenda. Em uma reordenação, as MOs vinculadas ao mesmo pedido de venda permanecem juntas. Por isso, sequencie-as como um grupo.
• O comportamento da reordenação mudou. Desde 7 de outubro de 2026, os endpoints de reordenação posicionam as ordens exatamente onde solicitado. As integrações desenvolvidas para o comportamento anterior precisam ser testadas novamente. (fonte)