Chaves de consulta
Emite e revoga chaves somente de leitura para embarcadores e outros sistemas, e gerencia as chaves do TMS.
Chaves de consulta
A tela Integrações > Chaves de consulta dá acesso somente de leitura a embarcadores e outros sistemas, sem expor mais do que o necessário. Abaixo da lista, a seção Chaves do TMS reúne as credenciais que o sistema da própria transportadora usa para enviar manifestos e ler tudo. O endereço antigo /chaves-api redireciona para esta tela.
Para que serve#
- Permitir que um embarcador consulte o andamento das cargas dele, sem login no portal.
- Permitir que um destinatário pessoa jurídica ou outro sistema consulte seus documentos.
- Emitir e revogar a chave do TMS por ambiente (Teste e Produção).
A chave de consulta só consulta, não altera nada. CPF nunca é exibido. PDF e canhoto só saem para quem paga o frete.
Quem vê e o que depende de módulo#
Só o Administrador vê esta tela. A chave de consulta (embarcador e destinatário) é um módulo habilitado na conta e cobrado por chave, proporcional aos dias em que ela fica ativa. Sem o módulo, ao criar a chave a tela mostra "As chaves de consulta não estão no plano da sua conta. Fale com o Veltra para liberar." com o link para Plano e consumo. Se o módulo for desligado depois, as chaves já emitidas ficam suspensas (não revogadas) e voltam a funcionar quando o módulo for contratado de novo. A chave do TMS não é cobrada.
Finalidades#
| Finalidade (como aparece) | O que enxerga |
|---|---|
| TMS | Todos os eventos e documentos da transportadora, manifestos, PDF, pacote de evidências, XML do evento do CT-e e posições dos veículos |
| Consulta do embarcador | Só eventos e situação dos documentos dos CNPJs liberados na chave. Sem manifestos, sem posição dos veículos e sem CPF |
| Consulta de terceiro | O mesmo alcance da consulta do embarcador, para um destinatário ou outro sistema |
A raiz do CNPJ é o início de 8 caracteres e cobre matriz e filiais. Um documento fora das raízes da chave responde 404, como se não existisse.
Como usar#
Criar uma chave de consulta#
- Clique em Criar chave.
- Preencha Nome, Finalidade (Consulta do embarcador ou Consulta de terceiro) e, se for do embarcador, escolha o Embarcador cadastrado ou Digitar os CNPJs.
- Em CNPJs liberados, informe os CNPJs (um por linha); o Veltra usa os 8 primeiros caracteres, e todas as filiais do grupo ficam liberadas.
- Escolha Expira em e o Limite de requisições por minuto.
- Clique em Criar chave. Aparece Guarde a chave agora: a chave é mostrada uma única vez. Clique em Copiar chave, guarde em cofre, marque Já guardei a chave e Concluir. Se perder, revogue e crie outra.
Campos e filtros#
| Campo | Regra |
|---|---|
| Nome | Obrigatório, até 120 caracteres. Ex.: "Consulta Akzo" |
| Finalidade | Consulta do embarcador ou Consulta de terceiro |
| Embarcador | Opcional na finalidade do embarcador; preenche os CNPJs |
| CNPJs liberados | Ao menos um; cada linha precisa ter pelo menos 8 letras ou números do CNPJ |
| Expira em | Obrigatório; a partir de amanhã e no máximo 365 dias (sugestão: 90 dias). "Chaves sem prazo não são permitidas." |
| Limite de requisições por minuto | De 1 a 600 (sugestão: 60). Acima disso, a API responde 429 e pede para esperar |
Mensagens de erro#
| Mensagem | Quando aparece |
|---|---|
| Informe um nome para saber quem usa a chave. | Nome em branco |
| Informe ao menos um CNPJ ou escolha o embarcador. | Nenhum CNPJ |
| Confira: (valores). Cada linha precisa ter pelo menos 8 letras ou números do CNPJ. | CNPJ curto demais |
| Escolha uma data a partir de amanhã. / A chave vale no máximo 365 dias. | Expiração fora da faixa |
| Use de 1 a 600. | Limite fora da faixa |
A lista#
Colunas: Nome, Finalidade, Prefixo (só o início da chave), CNPJs liberados (as duas primeiras raízes e "+N"), Expira em, Limite (por minuto), Último uso ("Nunca usada" se for o caso), Situação (Ativa, Revogada ou Expirada) e Ações. A chave que vence em 15 dias ou menos mostra "Expira em N dias". Clique na linha para ver o detalhe.
Revogar#
Clique em Revogar e confirme em Revogar chave. Quem usa a chave perde o acesso agora, e não é possível desfazer. Você pode criar outra depois.
Chaves do TMS#
Na seção Chaves do TMS, clique em Gerar chave do TMS, informe o Nome (por exemplo, "TMS produção") e o Ambiente: Teste ou Produção, e clique em Gerar chave. A chave de Teste é somente leitura para filiais e grava manifestos marcados como teste (aba "Teste" em Manifestos). A de Produção só é emitida para transportadora ativa; fora disso a tela avisa "Chave de produção só pode ser emitida para transportadora ativa. Enquanto a homologação não terminar, gere uma chave de teste." O valor completo aparece uma única vez. O sistema envia a chave no cabeçalho X-Veltra-Api-Key e uma Idempotency-Key em cada envio de manifesto. Veja Manifestos pela API.
Boas práticas#
- Use uma chave por sistema e por ambiente, com nome que diga quem a usa.
- Dê a menor abrangência possível: poucas raízes de CNPJ, expiração curta e limite baixo.
- Guarde a chave em cofre; nunca em repositório, código ou log. Se vazar, revogue na hora.
- Entregue ao integrador, junto com a chave, o contrato filtrado da finalidade (veja Documentação da API).
Perguntas frequentes#
Posso ver a chave de novo depois de criada? Não. Só o prefixo fica visível. Revogue e crie outra.
Por que o embarcador recebeu 404? O documento está fora das raízes de CNPJ da chave.
A chave do TMS conta na fatura? Não. A chave de consulta, sim, proporcional aos dias ativa.