Integração ERP e MES

Esta página é para o engenheiro de integração que conecta o Scalarcut a um ERP, MES ou controlador de mesa de corte.

O documento Factory MBOM chega aos seus sistemas de duas formas:

• Exportação do planejador — um usuário Enterprise planeja no planejador e clica no botão Factory MBOM para baixar o JSON e o CSV.
• API HTTP — seu middleware obtém o mesmo documento pelo endpoint com chave.

Ambos produzem o mesmo esquema scalarcut.factory_bom.v1.1; o mapeamento abaixo se aplica a ambos.

Escolha JSON ou CSV

• JSON é o documento completo: cabeçalho, peças, receitas, consumíveis, totais e geometry opcional. Use-o quando seu middleware puder consumir JSON estruturado.
• CSV é apenas a lista de peças — as colunas planas que você pode colocar direto em uma mesa de corte ou importar em uma planilha. Embalagem, ids, taxas e totais não estão no CSV.

Ambos descrevem a mesma lista de cortes; o CSV é uma projeção com perdas das peças do JSON.

Mapeamento de campos

Campo Factory MBOM	Destino típico ERP / MES
schema	Trava de versão de contrato (fixar em scalarcut.factory_bom.v1.1)
scene_id / project_id	Chave de ordem de produção / ordem de serviço
surface_id	Zona ou linha (wall-a…wall-d, floor)
group_id	Chave de roteamento estável para um grupo de corte
letter	Legenda legível da lista de cortes para o chão de fábrica
sku	Cadastro de material / número de artigo
w_mm / h_mm	Dimensões de corte para a mesa de corte
cut_type	Estratégia de corte / centro de trabalho
qty	Quantidade do pedido para o grupo
fragile	Bloqueio de qualidade / flag de manuseio manual
cre_recycled / cre_parent	Rastreabilidade de reciclagem até a placa de origem
is_l_cut	Roteamento de corte em L
rates	Constantes de fórmula de consumíveis
totals.cut_qty	Auditoria contra o cabeçalho da lista de cortes da planta
totals.boxes_to_order	Caixas a comprar

Obtenções idempotentes

O endpoint é um GET com ETag. Faça polling com If-None-Match para que uma nova solicitação sem alterações retorne 304 em vez de reprocessar o documento. Trate a combinação de scene_id/project_id + ETag como sua chave de idempotência ao ingerir em uma fila.

Obter, não enviar

Há dois caminhos de entrega. Um usuário pode exportar o documento pelo botão do cabeçalho do planejador (baixa JSON + CSV). Para automação, seu middleware pode obter o documento pela API HTTP sob demanda — não há push por webhook nesta versão. Agende seu polling no seu próprio ritmo e apoie-se no ETag.

Cortes frágeis

Um corte abaixo do limite de fragilidade de 50 mm é marcado como fragile: true. Encaminhe-os para manuseio manual em vez de enviá-los a uma máquina que os quebraria. O Sliver Guard já tenta reancorar os layouts para evitá-los; o flag é a rede de segurança final.

Consumíveis

Cola, rejunte e primer estão sempre presentes nos rates e totals do Factory MBOM — o oposto do carrinho do Online Store Widget, onde os consumíveis são uma linha opcional do carrinho. Mapeie rates uma vez para suas constantes de fórmula; o documento carrega os kg/L calculados, então você não precisa recalculá-los.

Auditoria

totals.cut_qty deve ser igual à soma dos qty das peças. Ao ingerir um documento, reconcilie totals.cut_qty com o cabeçalho da lista de cortes da planta da mesma cena. Qualquer desvio significa que o layout mudou entre a exportação e a ingestão — obtenha novamente antes de liberar para produção.

Recuperando um projeto por id

Seu middleware obtém um projeto pelo seu scene_id (ou project_id) junto com sua Enterprise Key. A solicitação é limitada à sua empresa, então você recupera apenas seus próprios projetos. O fixture da garagem é uma amostra pública para testes de integradores e o painel Try MBOM API, não o único documento que o endpoint serve.