Manual da API · contrato 0.15.0
Manual da API
A API do Veltra fala JSON. O sistema da transportadora (o TMS) envia filiais e manifestos e lê o que aconteceu: baixas, ocorrências e comprovantes. Este manual é gerado direto do contrato OpenAPI, então sempre mostra as rotas e os campos como o contrato os define. Para o texto explicado de cada rota, veja também API por rota e o Guia do TMS.
Endereços base
| Ambiente | Endereço base | Para que serve |
|---|---|---|
| Produção | https://api.veltrasolution.com | Uso real, com clientes de verdade. |
| Teste | https://api-teste.veltrasolution.com | Homologar a integração. Tem o mesmo comportamento da produção e roda sempre no ambiente PRODUCAO. |
A versão da API está no caminho (/integracao/v1/... e /v1/...). Mudanças dentro de uma versão são só aditivas: seu código deve ignorar campos que não conhece.
Autenticação
O TMS se autentica com uma chave de API no cabeçalho X-Veltra-Api-Key. A chave é emitida pelo administrador na tela Chaves de API do portal e o valor completo aparece uma única vez. Guarde em um cofre de segredos, nunca em código, log ou e-mail.
- Não envie
Authorizationjunto com a chave: o Veltra recusa com401(uma credencial por chamada). - Chave ausente, desconhecida, revogada ou expirada devolve
401. - As rotas marcadas como rota de administrador (webhooks e emissão de chaves) usam a sessão do portal em
Authorization: Bearer.
curl -X GET 'https://api.veltrasolution.com/v1/api-keys/atual' \
-H 'X-Veltra-Api-Key: SUA_CHAVE_AQUI'const resposta = await fetch("https://api.veltrasolution.com/v1/api-keys/atual", {
method: "GET",
headers: {
"X-Veltra-Api-Key": "SUA_CHAVE_AQUI",
},
});
console.log(resposta.status);
console.log(await resposta.text());import requests
resposta = requests.request(
"GET",
"https://api.veltrasolution.com/v1/api-keys/atual",
headers={
"X-Veltra-Api-Key": "SUA_CHAVE_AQUI",
},
timeout=30,
)
print(resposta.status_code)
print(resposta.text)<?php
$ch = curl_init('https://api.veltrasolution.com/v1/api-keys/atual');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Veltra-Api-Key: SUA_CHAVE_AQUI',
],
]);
$resposta = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
echo $resposta;
curl_close($ch);import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Exemplo {
public static void main(String[] args) throws Exception {
HttpRequest requisicao = HttpRequest.newBuilder(URI.create("https://api.veltrasolution.com/v1/api-keys/atual"))
.header("X-Veltra-Api-Key", "SUA_CHAVE_AQUI")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> resposta = HttpClient.newHttpClient()
.send(requisicao, HttpResponse.BodyHandlers.ofString());
System.out.println(resposta.statusCode());
System.out.println(resposta.body());
}
}using System.Net.Http;
using System.Text;
using var cliente = new HttpClient();
var requisicao = new HttpRequestMessage(new HttpMethod("GET"), "https://api.veltrasolution.com/v1/api-keys/atual");
requisicao.Headers.Add("X-Veltra-Api-Key", "SUA_CHAVE_AQUI");
var resposta = await cliente.SendAsync(requisicao);
Console.WriteLine((int)resposta.StatusCode);
Console.WriteLine(await resposta.Content.ReadAsStringAsync());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requisicao, err := http.NewRequest("GET", "https://api.veltrasolution.com/v1/api-keys/atual", nil)
if err != nil {
panic(err)
}
requisicao.Header.Set("X-Veltra-Api-Key", "SUA_CHAVE_AQUI")
resposta, err := http.DefaultClient.Do(requisicao)
if err != nil {
panic(err)
}
defer resposta.Body.Close()
texto, _ := io.ReadAll(resposta.Body)
fmt.Println(resposta.StatusCode)
fmt.Println(string(texto))
}Idempotency-Key
Nas rotas que gravam manifesto (POST e PUT), envie o cabeçalho Idempotency-Key (recomendado: um UUID por tentativa lógica de envio). Repetir a mesma chave com o mesmo corpo devolve a resposta original, sem duplicar nada; a mesma chave com corpo diferente devolve 409. A chave é guardada por pelo menos 72 horas.
Erros (RFC 9457)
Os erros vêm em application/problem+json, no padrão RFC 9457. Use status para decidir o que fazer e detail para mostrar a causa. Alguns erros trazem também codigo (por exemplo CHAVE_SUSPENSA) e uma lista erros com o motivo de cada documento recusado.
{
"type": "https://veltra.com.br/problemas/idempotencia",
"title": "Idempotency-Key já usada com outro corpo",
"status": 409,
"detail": "A Idempotency-Key informada já foi usada numa requisição com conteúdo diferente."
}Rotas por grupo
Entrada do TMS
Enviar, consultar, alterar e cancelar manifestos (entrega, coleta e transferência).
- POST
/integracao/v1/manifestosEnvia um manifesto novo (entrega, coleta ou transferência) - GET
/integracao/v1/manifestos/{numeroExterno}Consulta um manifesto enviado pelo próprio TMS (versão atual e status por documento) - PUT
/integracao/v1/manifestos/{numeroExterno}Altera um manifesto reenviando-o inteiro (nova versão) - POST
/integracao/v1/manifestos/{numeroExterno}/cancelarCancela o que ainda falta de um manifesto (cancelamento parcial)
Leitura e consulta
Ler eventos, manifestos, documentos e comprovantes; baixar PDF, pacote e XML; configurar o prazo.
- GET
/v1/saida/eventosLista eventos de saída alterados desde o cursor - GET
/v1/saida/manifestosLista manifestos visíveis para a chave - GET
/v1/saida/manifestos/{id}Obtém um manifesto da leitura de saída - GET
/v1/saida/documentos/{id}Obtém um documento fiscal da leitura de saída - GET
/v1/saida/comprovantes/{id}/pdfBaixa o PDF do comprovante quando o escopo autorizar - GET
/v1/saida/comprovantes/{id}/pacoteBaixa o pacote de evidências quando o escopo autorizar - GET
/v1/saida/eventos-cte/{id}/xmlBaixa o XML assinado do evento 110180 com o protocolo - GET
/v1/saida/openapi/{finalidade}Devolve o OpenAPI filtrado da finalidade - GET
/v1/saida/configuracao-prazoLê a configuração de prazo pela chave do TMS - PUT
/v1/saida/configuracao-prazoGrava cidades e prazos pela chave do TMS
Webhooks
Cadastrar os endereços que recebem os eventos, girar o segredo e reenviar entregas.
- GET
/v1/integracoes/webhooksLista os assinantes de webhook (só ADMIN) - POST
/v1/integracoes/webhooksCria um assinante de webhook e devolve o segredo uma vez (só ADMIN) - GET
/v1/integracoes/webhooks/{id}Obtém um assinante de webhook (só ADMIN) - PUT
/v1/integracoes/webhooks/{id}Atualiza um assinante de webhook (só ADMIN) - DELETE
/v1/integracoes/webhooks/{id}Exclui um assinante de webhook (só ADMIN) - POST
/v1/integracoes/webhooks/{id}/pausaPausa um assinante de webhook (só ADMIN) - POST
/v1/integracoes/webhooks/{id}/retomadaRetoma um assinante de webhook (só ADMIN) - POST
/v1/integracoes/webhooks/{id}/rotacao-segredoGira o segredo do webhook e devolve o novo uma vez (só ADMIN) - GET
/v1/integracoes/webhooks/{id}/entregasLista as entregas de um assinante de webhook (só ADMIN) - POST
/v1/integracoes/webhooks/{id}/entregas/{entregaId}/reenvioReenvia uma entrega de webhook (só ADMIN) - POST
/v1/integracoes/webhooks/{id}/testeEnvia um evento de teste ao assinante (só ADMIN)
Filiais
Cadastrar e manter as filiais do TMS no Veltra.
Chaves
Verificar a chave em uso e administrar chaves de API e de consulta.
- GET
/v1/api-keysLista as API keys da transportadora autenticada (só prefixo, nunca o valor) - POST
/v1/api-keysEmite uma nova API key para a transportadora autenticada - GET
/v1/api-keys/atualDados da API key que autenticou a chamada (tenant e ambiente) - DELETE
/v1/api-keys/{id}Revoga uma API key - GET
/v1/integracoes/chavesLista as chaves de consulta (só ADMIN) - POST
/v1/integracoes/chavesEmite uma chave de consulta e devolve o valor uma vez (só ADMIN) - POST
/v1/integracoes/chaves/{id}/revogacaoRevoga uma chave de consulta (só ADMIN)
Prefere testar no navegador? Use o Swagger.