Identificação do Software Integrador (User-Agent)
Requisito obrigatório para operação em ambiente de Produção.
Visão geral
A infraestrutura da NDD aplica uma política de controle de acesso que bloqueia automaticamente requisições sem identificação de origem válida. Essa medida garante que apenas sistemas TMS/ERP devidamente homologados operem no ambiente de Produção.
O mecanismo de identificação utilizado é o header HTTP User-Agent, que deve ser enviado em todas as requisições feitas ao ambiente de Produção.
Este requisito se aplica somente ao ambiente de Produção.
Em Homologação (HML), o envio do User-Agent não é obrigatório.
Ao migrar para Produção, o header User-Agent deve estar presente em todas as requisições.
Como identificar o bloqueio
Quando uma requisição é bloqueada, a API retorna HTTP 403 com o seguinte corpo:
{
"code": "403",
"message": "Forbidden",
"RequestId": "a3f92c10bd874e1f95d06a3c2b871d40"
}O campo RequestId é o identificador único da requisição bloqueada. Ele é obrigatório para solicitar a liberação de acesso junto ao time de Implantação.
O RequestId está no corpo (body) da resposta, não no header.
Cada requisição bloqueada gera um RequestId diferente. Utilize o mais recente ao acionar o time de Implantação.
O que é o User-Agent?
O User-Agent é um cabeçalho HTTP enviado em toda requisição que identifica o sistema responsável pela chamada. Na integração com o NDD Cargo, ele é utilizado para validar que a requisição parte de um software legítimo e não de uma ferramenta de teste.
Formato esperado:
User-Agent: <NomeDoSistema>
Exemplos:
User-Agent: MeuSistemaTMS
User-Agent: ERPTransportes
User-Agent: SistemaLogistica
Utilize um nome que identifique claramente o seu sistema.
Evite valores genéricos como: app, client ou sistema.
Defina o valor uma vez e mantenha sem alterações. Ele representa a identidade do seu sistema perante a infraestrutura NDD.
Dados necessários para liberação
Para que o time de Implantação abra o chamado com a infraestrutura NDD, o integrador deve fornecer os três dados abaixo:
| Dado | Onde encontrar | Exemplo |
|---|---|---|
| RequestId | Campo RequestId no corpo JSON da resposta 403 retornada pela API. | a3f92c10bd874e1f95d06a3c2b871d40 |
| Endpoint executado | Caminho do endpoint chamado no momento do bloqueio. | /consulta/consultaRoteirizador/enterpriseID |
| User-Agent | Nome do sistema integrador, conforme será enviado no header das requisições. | MeuSistemaTMS |
O valor informado na solicitação deve ser exatamente igual ao enviado nas requisições.
Qualquer diferença de capitalização ou conteúdo fará com que o bloqueio persista.
Como solicitar a liberação
Com os três dados em mãos, acione o time de Implantação responsável por apoiar a sua integração. Eles abrirão o chamado com a infraestrutura NDD para registrar o User-Agent do seu sistema.
A liberação ocorre em até 1 dia útil a partir da abertura do chamado com a infraestrutura NDD.
Como implementar o User-Agent
O header deve estar presente em todas as requisições enviadas à API NDD Cargo (métodos GET e POST).
O nome do header (User-Agent) é case-insensitive conforme o protocolo HTTP/1.1. O valor, no entanto, deve ser idêntico ao informado na solicitação de liberação.
Boas práticas
Defina o User-Agent uma única vez em uma configuração centralizada do cliente HTTP.
Use um identificador claro que represente o nome do seu sistema.
Evite nomes genéricos como app, client ou sistema.
Exemplo em Java (HttpClient)
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.nddcargo.com.br/consulta/consultaRoteirizador/enterpriseID"))
.header("User-Agent", "MeuSistemaTMS")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
Fluxo de Ativação em Produção
1. Desenvolva e valide a integração em HML normalmente. O User-Agent não é exigido nesse ambiente.
2. Implemente o header User-Agent no seu sistema com o valor escolhido (ex.: MeuSistemaTMS). Mantenha esse valor sem alterações.
3. Realize uma chamada em Produção. Ela será bloqueada com HTTP 403. Esse comportamento é esperado nessa etapa.
4. Colete o RequestId do campo RequestId no corpo da resposta 403.
5. Acione o time de Implantação informando: RequestId, endpoint executado e User-Agent.
6. Aguarde a liberação. O chamado será aberto com a infraestrutura NDD e a liberação ocorre em até 1 dia útil.
7. Após a liberação, todas as requisições com o User-Agent cadastrado serão aceitas em Produção.
Perguntas Frequentes
Posso usar Postman ou Insomnia em Produção? Não. Ferramentas de teste são bloqueadas no ambiente de Produção. As chamadas devem partir exclusivamente do sistema TMS/ERP com o User-Agent liberado.
O ambiente de Homologação também bloqueia? Não. O envio do User-Agent é obrigatório somente em Produção. Em HML, as requisições são aceitas independentemente do header.
Posso alterar o valor do User-Agent após a liberação? Recomendamos manter o mesmo valor definido no momento da solicitação. O User-Agent representa a identidade do seu sistema e deve permanecer estável.
E se eu receber 403 mesmo após a liberação? Verifique se o valor do User-Agent enviado na requisição é idêntico ao informado na solicitação. Diferenças de capitalização ou conteúdo causam bloqueio. Em caso de dúvida, acione o time de Implantação.
Referências
MDN Web Docs - User-Agent Header: https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Reference/Headers/User-Agent