Integração da Prensa Inteligente

Visão geral

A IHM PlacaID disponibiliza uma API local para registrar blanks e consultar itens recebidos ou processados. Esta referência apresenta somente o contrato necessário para a integração.

Há também um fluxo opcional chamado Validação Externa, no qual a prensa consulta o sistema de gestão após a leitura do QR Code e só libera a prensagem quando a validação retorna sucesso.

Requisitos

• IHM Inovare PlacaID com versão 0.5.2 ou superior.
• Conectividade de rede entre o sistema integrador e a IHM.
• Endereço da IHM, disponível na tela de diagnóstico do equipamento.

A API utiliza a porta 8000. A interface Swagger local fica disponível emhttp://<ENDERECO_DA_IHM>:8000/docs.

Autenticação

API local da IHM

Os endpoints da IHM validam um token enviado no header X-token. Nunca inclua a credencial real em código-fonte, documentação pública, logs ou repositórios.

X-token: <ACCESS_TOKEN>
Content-Type: application/json

Validação Externa

Nesse fluxo, a IHM pode autenticar-se na API do sistema de gestão usando os parâmetros configurados no equipamento e usar o token retornado nas chamadas seguintes.

Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

Endpoints da IHM

Payloads

Registrar um blank

{
  "nomePlaca": "<PLACA>",
  "tipo": "C",
  "subTipo": "D",
  "corDaPlaca": "4",
  "codigoBlank": "<QR_CODE_DO_BLANK>",
  "descricao": "<DESCRICAO>"
}

• nomePlaca: código alfanumérico da placa.
• tipo: C para carro ou M para moto.
• subTipo: D dianteira, T traseira ou S segunda traseira.
• corDaPlaca: código de cor definido pelo contrato da API.
• codigoBlank: conteúdo do QR Code do blank.
• descricao: descrição textual do item.

O cadastro unitário retorna o objeto inserido com seu identificador. No retorno de/processed-blanks, o campo EXTERNALID pode ser usado para correlacionar o item interno da IHM com o registro criado pela API.

Validação Externa

Quando o recurso está habilitado no equipamento, a IHM envia uma requisição de validação após ler o QR Code. O sistema externo decide se o blank pode ser associado ao código alfanumérico em processamento.

1. A IHM obtém um token na API de autenticação configurada.
2. A leitura do QR Code dispara a chamada de validação.
3. Com retorno positivo, a prensagem é liberada.
4. Se o processo for invalidado, a IHM pode chamar a rota configurada para desvincular o blank.

Exemplo ilustrativo de validação

{
  "placa": "<PLACA>",
  "tipo": "<TIPO_PLACA>",
  "hash": "<HASH>"
}

Resposta esperada para sucesso

{
  "Serial": "<SERIAL>",
  "Status": 0
}

O manual informa que a validação é considerada bem-sucedida quando a resposta HTTP é200, Serial não é nulo e Status é igual a0.

Respostas e erros

A referência pública não inclui uma tabela completa de códigos de erro. Integrações devem tratar como falha respostas fora do contrato esperado, indisponibilidade de rede, timeout e payload inválido, sem registrar tokens ou credenciais nos logs.

Antes de colocar uma integração em produção, valide timeouts, política de repetição, idempotência e tratamento de cancelamento com a equipe técnica responsável pelo sistema.

Segurança

• Armazene tokens e segredos fora do código-fonte.
• Restrinja o acesso à rede da IHM aos sistemas que realmente precisam integrar.
• Não exponha a porta da API local diretamente à internet.
• Masque headers de autenticação e QR Codes em logs e ferramentas de observabilidade.
• Use HTTPS nos endpoints externos de autenticação, validação e cancelamento.
• Rotacione credenciais sempre que houver suspeita de exposição.