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. Credenciais da integração
  • 2. Cadastrar usuário dedicado e gerar a Chave Única do ERP
  • 3. Cadastrar o Ponto de Carga com Código de Integração
  • 4. GUID (ID da Usina)
• 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.
• A Chave Única do ERP (X-API-Key), gerada no próprio ERP pela CRTI e entregue à usina. Ela não é fornecida pela usina, nem no caso da Topcon. Ver Credenciais da integração.

Lado da usina/sistema terceiro:

• O software precisa conseguir fazer GET e POST HTTPS com JSON.
• O software precisa receber da CRTI e armazenar a Chave Única do ERP 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. Credenciais da integração

A integração usa credenciais distintas em cada direção. Elas não se substituem, e a origem de cada uma é diferente:

Atenção: nenhuma chave de acesso ao ERP é fornecida pela usina. Tanto a Chave Única do ERP quanto o Webhook Secret são definidos do lado da CRTI e repassados ao parceiro. Da Topcon vêm apenas as credenciais do endpoint dela: a chave do campo X-Api-Key do Ponto de Carga e o GUID da usina.

Duas credenciais diferentes com nome parecido. A Chave Única do ERP, gerada na tela de Usuários, viaja no header X-API-Key das chamadas que a usina faz ao ERP. O campo X-Api-Key do cadastro de Ponto de Carga é outra coisa: é a chave da Topcon, que o ERP envia ao chamar o endpoint dela. São valores distintos, de origens distintas, e um nunca deve ser preenchido com o outro.

Webhook de retorno. O retorno de produção da Topcon é um webhook exposto pelo ERP, autenticado pelo Webhook Secret no header X-Webhook-Key:

POST https://[nomedocliente].crti.com.br/vendas/usina_concreto/{codigoPontoCarga}/retorno/webhook
X-Webhook-Key: webhook_secret_cadastrado_no_ponto_de_carga
Content-Type: application/json

{codigoPontoCarga} é o Código do Cliente do Ponto de Carga. Se o header não corresponder ao Webhook Secret cadastrado, o ERP recusa a chamada.

2. Cadastrar usuário dedicado e gerar a Chave Única do ERP

Esta é a credencial que a usina usa para se autenticar no ERP. Ela é gerada pelo próprio ERP, em Configurações do Sistema > Permissões > Usuários > Credenciais B2B: não é informada pelo cliente nem pela usina. A chave aparece uma única vez no momento da criação, então copie-a e entregue-a à usina. O passo a passo completo está em Autenticação via Chave Única (X-API-Key).

Entre os softwares de usina, atualmente somente a Topcon utiliza esse método de autenticação.

Não confundir com o campo X-Api-Key do Ponto de Carga. A chave gerada aqui autentica a usina no ERP. O campo X-Api-Key do cadastro de Ponto de Carga é a chave da Topcon, que o ERP usa para chamar o endpoint dela, e vem da própria Topcon. Os dois valores não se misturam.

3. 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 e identifica o ponto de carga no payload JSON; sem ele, o retorno da usina é rejeitado.

4. GUID (ID da Usina)

O comportamento do campo depende do Tipo de utilização escolhido no Ponto de Carga:

• Tipo CRTI (integrador Java): o GUID é gerado automaticamente pelo ERP e o campo fica somente leitura. Ele é usado como identificador do canal de comunicação com o integrador local.
• Tipo TOPCON: o campo fica editável (label ID da Usina (GUID)) e deve receber o GUID fornecido pela Topcon. Ele é enviado no payload como identificador da central de concreto e é obrigatório: sem ele a transmissão falha com “ID da usina (GUID) não informado”.

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 Requisitos de Segurança da API REST). HTTP puro não é aceito.
• A Chave Única do ERP é exibida uma única vez, então guarde em local seguro (cofre/variável de ambiente); depois disso não fica mais disponível, e para recuperá-la é necessário invalidar a chave e gerar outra. Já o Webhook Secret, a chave do endpoint da Topcon e o GUID ficam gravados no cadastro do Ponto de Carga e podem ser reconsultados ou regravados a qualquer momento.
• 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).