Usina de Concreto via API REST

Integração direta via API REST entre sistemas de automação de usina (Topcon, Kartrak e similares) e o CRTI ERP, sem o integrador local em Java.

• Softwares Pretendidos (Homologação)
• Diferença: Integrador Local (Java) vs. API REST
• Pré-requisitos
• Configuração no ERP
  • 1. Cadastrar usuário dedicado e gerar chave de API
  • 2. Cadastrar o Ponto de Carga com Código de Integração
  • 3. GUID
• Fluxo de Comunicação (Resumo)
• Observações Importantes

Este documento descreve a integração direta via API REST entre sistemas de automação de usinas de concreto (Topcon, Kartrak e similares) e o CRTI ERP, sem a necessidade do integrador local em Java.

A intenção é permitir que o software da usina converse diretamente com o ERP via HTTPS/JSON, trocando lotes de ordem de carga, retornos de carregamento e confirmações de processamento em tempo real.

Hoje o caminho homologado é o Integrador Local em Java. Esta documentação cobre o novo modelo, que está em desenvolvimento/validação. O endpoint e o formato do payload já estão definidos.

Softwares Pretendidos (Homologação)

A integração via API REST foi desenhada para conversar com sistemas de automação de usinas que já falam REST/JSON. A curto prazo a intenção é homologar:

• TOPCON
• KARTRAK
• COMMAND ALKON (em paralelo com o integrador Java)
• (Demais vendors a definir conforme demanda comercial)

Caso o software da usina não exponha uma API REST própria, mantenha-se o uso do Integrador Local em Java, que faz a ponte lendo layouts legados (INSTAL, SAUC, SAI, SHM, COMMAND ALKON) e convertendo para o mesmo payload JSON usado pela API.

Diferença: Integrador Local (Java) vs. API REST

Ambos entregam o mesmo resultado no ERP (lançamento de ordem de carga, retorno de carregamento e confirmação), mas o “como” é bem diferente:

Em resumo: o Integrador Local é um tradutor de arquivos que roda do lado da máquina do usuário/usina; a API REST é conversa direta, moderna, sem serviço intermediário.

Pré-requisitos

Lado do ERP:

• CRTI ERP com módulo de Usina de Concreto ativo e a filial configurada.
• Pelo menos um Ponto de Carga cadastrado e com o campo Código de Integração preenchido (esse código é a chave que amarra o payload ao ponto de carga da usina).
• Um usuário dedicado para a integração, com permissão de escrita no módulo de vendas/ordem de carga.
• Chave de API (X-API-Key). No caso da Topcon, é fornecida pela própria Topcon.

Lado da usina/sistema terceiro:

• O software precisa conseguir fazer GET e POST HTTPS com JSON.
• O software precisa armazenar a X-API-Key de forma segura (variável de ambiente / cofre).

Não é necessário: instalar Java na máquina da usina, criar pasta de remessa/retorno, ou liberar Windows Service / instalar_servico.bat.

Configuração no ERP

1. Cadastrar usuário dedicado e gerar chave de API

Veja Autenticação via Chave Única (X-API-Key). Essa chave é fornecida pela usina; atualmente somente a Topcon utiliza esse sistema de autenticação.

2. Cadastrar o Ponto de Carga com Código de Integração

1. Acesse o cadastro de Ponto de Carga (Vendas > Cadastros > Ponto de Carga Concreto).
2. No campo Código de Integração, informe o código acordado com a usina (ex.: PC-CURITIBA-01).

Cada Ponto de Carga deve ter um código único. O código é case-sensitive — ele identifica o ponto de carga no payload JSON; sem ele, o retorno da usina é rejeitado.

3. GUID

Gerado automaticamente pelo ERP para comunicação com o integrador Java. A exclusividade é da Topcon, que pode ter esse GUID alterado para a comunicação via REST.

Fluxo de Comunicação (Resumo)

[Usina]                       [CRTI ERP]
  |                                 |
  |--- GET /ordemDeCarga/remessa -->|  (1) pede ordens pendentes
  |<-- lista de ordens JSON --------|
  |                                 |
  |   (usina carrega o concreto)    |
  |                                 |
  |--- POST /ordemDeCarga/retorno ->|  (2) envia o carregamento (quando retorno implementado)
  |<-- 200 OK com payload -----------|
  |                                 |
  |<-- POST /confirmar --------------|  (3) ERP confirma processamento
  |--- 200 OK ---------------------->|
  |                                 |

Observações Importantes

• A comunicação é feita por HTTPS obrigatório (ver API REST — Requisitos de Segurança). HTTP puro não é aceito.
• A X-API-Key é exibida uma única vez — guarde em local seguro (cofre/variável de ambiente); depois disso não fica mais disponível.
• Se a usina perder a conexão no meio do POST /retorno, ela deve reenviar — o ERP usa o codigoEvento como idempotência (retornos duplicados são ignorados).