Uma integração de dados veiculares não deve depender apenas de uma chave enviada em texto no header. Na autenticação de API com HMAC SHA256, a requisição carrega uma assinatura calculada a partir de seu conteúdo e de um segredo mantido fora do tráfego HTTP. Assim, uma chave de acesso vazada sem o segredo não permite produzir assinaturas válidas.
Esse modelo atende bem a operações B2B que consultam dados por placa, processam lotes, recebem eventos e precisam manter rastreabilidade entre sistemas. Mas HMAC não corrige uma implementação imprecisa. A assinatura só funciona quando cliente e servidor concordam, byte a byte, sobre o que foi assinado.
O que a assinatura HMAC-SHA256 valida
HMAC combina uma função de hash, neste caso SHA-256, com um segredo compartilhado. O cliente monta uma mensagem canônica, calcula o HMAC com o segredo e envia o resultado junto da requisição. O servidor repete o cálculo com o segredo associado à chave recebida. Se os valores coincidem, a mensagem chegou com o conteúdo esperado e foi assinada por quem detém o segredo.
Isso traz duas propriedades práticas. A primeira é integridade: uma alteração no método HTTP, no caminho, no corpo ou em outro componente assinado muda a assinatura. A segunda é autenticação do emissor no contexto da credencial: o servidor verifica que o cliente conhece o segredo correto.
HMAC não cifra a requisição. Dados no corpo continuam dependendo de HTTPS para proteção em trânsito. Também não substitui controles de autorização. Uma assinatura válida identifica a integração, mas o servidor ainda precisa decidir se aquela credencial pode chamar determinado serviço, ambiente ou recurso.
Como a autenticação de API com HMAC SHA256 é composta
O contrato de assinatura precisa definir os campos e a ordem de composição. Uma mensagem canônica comum inclui método, caminho, timestamp e hash do corpo. A especificação pode incluir ainda query string, identificador da chave ou outros headers. Não há um formato universal: a regra válida é a que a API documenta.
Um exemplo didático de string canônica seria:
```text POST /v1/veiculos/consulta 2026-09-13T14:30:00Z b5c1fb2efc6d6b0a3d20b9a1c4a2f7d8e9c0a1b2c3d4e5f60718293a4b5c6d7 ```
O último valor representa o hash SHA-256 do corpo JSON exatamente como será transmitido. Com essa string, o cliente calcula o HMAC-SHA256 usando o segredo. A saída pode ser codificada em hexadecimal ou Base64, conforme o contrato. O servidor não precisa receber o segredo, apenas a chave de identificação, o timestamp e a assinatura.
Uma requisição ilustrativa pode ter esta forma:
```http POST /v1/veiculos/consulta HTTP/1.1 Content-Type: application/json X-Api-Key: lnt_test_exemplo X-Timestamp: 2026-09-13T14:30:00Z X-Idempotency-Key: 6dc4d83b-14ed-4b5d-a9d4-7f7e2e9d0192 X-Signature: assinatura_calculada
{"placa":"ABC1D23"} ```
Os nomes dos headers acima são apenas ilustrativos. Uma equipe integradora deve usar os nomes, algoritmos de codificação, formato de data e componentes definidos na documentação do endpoint. Trocar um campo aparentemente secundário pode invalidar a assinatura.
O corpo precisa ser o mesmo que foi assinado
Esse é um ponto recorrente em integrações. Um aplicativo serializa o JSON para calcular o hash e uma camada posterior o serializa novamente antes do envio. Mudanças de espaços, ordem de propriedades, quebra de linha ou codificação de caracteres geram bytes diferentes. Se o corpo faz parte da assinatura, o hash também muda.
A abordagem mais segura é gerar o payload uma vez, armazená-lo como string ou bytes, calcular o hash desse mesmo material e enviar exatamente o mesmo conteúdo. Para requisições sem corpo, a documentação deve determinar se entra um hash de conteúdo vazio ou outro valor convencionado.
Query strings exigem o mesmo cuidado. Parâmetros repetidos, caracteres codificados e ordenação devem seguir uma regra única. Assinar uma URL e enviar outra, ainda que semanticamente equivalente para parte dos servidores HTTP, resulta em divergência na validação.
Carimbo de tempo reduz o risco de replay
Uma assinatura HMAC válida pode ser capturada e reenviada por um agente que consiga observar o tráfego ou logs mal protegidos. HTTPS reduz muito esse cenário, mas não elimina o dever de limitar a validade da mensagem. Por isso, APIs assinadas costumam exigir um carimbo de tempo e aceitar apenas uma janela curta de tolerância.
Ao receber a chamada, o servidor valida se o timestamp segue o formato esperado e se está suficientemente próximo do horário atual. Uma requisição antiga é recusada mesmo que sua assinatura esteja correta. O cliente, por sua vez, precisa manter relógios sincronizados e tratar erros de horário como falha de integração, não como uma simples indisponibilidade transitória.
O timestamp também deve integrar a string canônica. Se estiver apenas em um header não assinado, alguém poderia alterar seu valor sem quebrar o HMAC. A mesma lógica vale para qualquer campo que altere o significado operacional da chamada.
POST exige idempotência além da assinatura
Assinatura e idempotência resolvem problemas diferentes. HMAC comprova a integridade e a autoria da requisição. A chave de idempotência impede que uma mesma intenção de negócio seja processada mais de uma vez quando o cliente reenviar um POST após timeout, falha de rede ou resposta perdida.
Em uma API de dados, a regra pode ser obrigatória mesmo quando o efeito parece apenas consultivo. Ela permite correlacionar tentativas, registrar o processamento e evitar ambiguidades de cobrança ou auditoria. A chave deve ser única por operação lógica, persistida pelo cliente e reutilizada somente nas retentativas daquela mesma operação.
Não gere uma nova chave a cada retry. Isso transforma uma repetição legítima em uma nova solicitação. Também não use identificadores previsíveis ou derivados diretamente de dados sensíveis. Um UUID ou outro valor aleatório com entropia adequada atende melhor a esse papel.
Onde as implementações costumam falhar
O primeiro erro é colocar o segredo no aplicativo cliente, em uma página web ou em um repositório. Segredos de assinatura pertencem ao ambiente controlado do servidor. Quando uma integração precisa atender um frontend, o frontend chama o backend da própria empresa, e esse backend assina a chamada para a API externa.
O segundo é registrar headers completos em logs de observabilidade. Uma assinatura tem validade limitada quando há timestamp, mas ainda pode expor metadados operacionais. O segredo nunca deve aparecer. Chaves de acesso, assinaturas e payloads precisam de mascaramento compatível com a política de logs e retenção da empresa.
O terceiro é usar comparação comum de strings no servidor. A validação da assinatura deve usar comparação em tempo constante, quando disponível na linguagem ou biblioteca adotada. Esse cuidado reduz sinais de tempo que podem ajudar tentativas de inferência da assinatura.
Por fim, há o problema de normalização. Diferenciar `POST` de `post`, assinar o caminho com um prefixo e enviar outro, ou calcular o hash antes de uma transformação automática de charset são falhas de contrato. Testes com vetores fixos ajudam: para uma entrada definida, método, payload, timestamp, segredo e assinatura esperada devem ser conhecidos pela equipe.
Rotação de credenciais sem interromper a operação
Segredos não devem ser permanentes. Rotação limita o impacto de uma exposição e é parte da governança da integração. O processo precisa aceitar uma fase de sobreposição: a nova credencial é criada, o cliente passa a assinar com ela, a telemetria confirma o uso e só então a credencial anterior é revogada.
A Lanet concentra credenciais com rotação no portal do cliente. Para a operação, isso permite separar ambientes e reduzir a dependência de troca manual por canais informais. Chaves de teste com prefixo `lnt_test_` devem ficar isoladas de produção, inclusive em variáveis de ambiente, pipelines e logs.
Rotação não é só criar outra chave. É inventariar onde ela está armazenada, atualizar serviços consumidores, verificar falhas de autenticação após a mudança e definir um responsável pela revogação. Em equipes com vários produtos, credenciais por integração ou contexto operacional facilitam esse diagnóstico.
Webhooks também precisam de validação própria
Quando a API envia um webhook, a direção da comunicação se inverte. Agora é o seu endpoint que precisa verificar se o evento foi emitido pela plataforma. A prática é assinar o corpo do evento com um segredo de webhook e incluir timestamp e assinatura nos headers.
A validação deve ocorrer antes de processar o JSON. Primeiro, obtenha o corpo bruto. Depois, reconstrua a mensagem prevista, valide timestamp e assinatura, e somente então desserialize e aplique regras de negócio. Se o framework consumir ou alterar o corpo antes dessa etapa, a assinatura pode falhar.
Respostas HTTP bem definidas também fazem parte do desenho. Seu endpoint deve retornar sucesso somente após aceitar o evento para processamento. Em caso de erro temporário, a plataforma pode retentar segundo seu cronograma. Como eventos podem chegar mais de uma vez, o consumidor precisa manter deduplicação por identificador de evento ou outra chave documentada.
Uma assinatura bem implementada não é um detalhe criptográfico isolado. Ela conecta credenciais, horário, idempotência, logs, rotação e tratamento de falhas em uma mesma disciplina operacional. Quando esses componentes seguem um contrato verificável, a equipe ganha mais previsibilidade para integrar dados veiculares em processos que não podem depender de suposições.
