1.1. Primeiros Passos¶

Especificação — em construção

Esta área documenta a API Pública de Crédito do VeTrust, que cobre as jornadas de Empréstimo Pessoal (EP) e Crédito Direto ao Consumidor (CDC). O contrato descrito aqui está acordado, mas os serviços ainda não estão disponíveis.

Nesta seção apresentamos o conjunto de APIs que viabilizam a originação e a gestão de operações de crédito — do primeiro cálculo até a cobrança das parcelas.

A integração contempla todo o ciclo de vida da operação: consulta das esteiras habilitadas, simulação, cadastro do tomador, dados de desembolso, coleta de documentos, análise de crédito, registro da proposta na bancarizadora, formalização e acompanhamento das parcelas.

1.1.1 Acesso aos Serviços¶

Para obter acesso aos serviços, entre em contato com nosso time pelo e-mail:

📧 contato@vertrau.capital

A liberação será realizada tanto para o ambiente de Homologação (Sandbox) quanto para o ambiente Produtivo.

A credencial é emitida por grupo econômico. Uma mesma credencial opera todas as esteiras de crédito habilitadas para aquele grupo — ver 3.1. Esteiras.

1.1.2 Autenticação¶

Todas as requisições exigem os seguintes headers:

Header	Tipo	Descrição
`Authorization`	Bearer Token	Token OAuth2 obtido via endpoint de login
`GrupoEconomico`	string	Identificador do grupo econômico

Obtenção do Token¶

curl --location "https://api.vehub.com.br/auth/login" \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "seu-client-id",
    "client_secret": "seu-client-secret"
  }'

Resposta¶

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

O token expira em expiresIn segundos. Renove-o antes do vencimento e reaproveite o token entre chamadas — não solicite um token por requisição.

1.1.3 Ambientes¶

Ambiente	URL Base
Homologação (Sandbox)	`https://dev.api.vehub.com.br/public/v1`
Produção	`https://api.vehub.com.br/public/v1`

Nas tabelas de endpoint mostramos apenas o caminho (ex.: /credito/esteiras), que deve ser concatenado à URL base do ambiente.

Homologação usa integração real com a bancarizadora. As simulações e as propostas criadas em sandbox trafegam para o ambiente de homologação e os callbacks são reais. Isso permite exercitar a jornada ponta a ponta, mas significa que cada simulação consome cota do convênio — ver o limite de requisições abaixo.

1.1.4 Padrões de Resposta¶

Padrão	Formato	Exemplo
Datas	`YYYY-MM-DD`	`2026-10-15`
Data e hora	ISO 8601 em UTC	`2026-10-15T13:22:40Z`
Valores monetários	`number` sem separador de milhar	`18000.00`
Percentuais	`number` — `1.99` significa 1,99%	`1.99`
Atributos	`camelCase` em português (exceto `id`)	`dataPrimeiroVencimento`, `valorSolicitado`

Envelope de sucesso¶

Operações de escrita e consultas de item único:

{
  "sucesso": true,
  "mensagem": null,
  "dados": { }
}

Envelope de listagem¶

Toda listagem é paginada e aceita pagina, quantidade (máximo 100), ordem e direcaoOrdem:

{
  "registros": [ ],
  "paginacao": { "pagina": 1, "quantidade": 50, "total": 137 },
  "mensagem": null
}

1.1.5 Estrutura de Erros¶

Todas as respostas de erro seguem o padrão abaixo. Quando o erro é de validação de campo, cada item de errors identifica qual campo foi recusado:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "status": 400,
  "errors": [
    { "campo": "quantidadeParcelas", "mensagem": "Deve ser maior ou igual a 1." },
    { "campo": "taxa", "mensagem": "Deve estar entre 1,50 e 3,50." }
  ]
}

Campo	Descrição
`type`	URI do tipo de problema (RFC 9110)
`status`	Código HTTP do erro
`errors`	Lista de erros; `campo` é nulo quando o erro não se refere a um campo específico

Códigos utilizados¶

Código	Quando ocorre
`200`	Sucesso
`201`	Recurso criado
`202`	Requisição aceita e em processamento — ver 1.3. Operações Assíncronas
`204`	Consulta sem resultado (ex.: tomador não cadastrado)
`400`	Payload inválido ou regra de validação de campo
`401`	Token ausente, expirado ou inválido; header `GrupoEconomico` ausente
`403`	Credencial sem acesso ao recurso
`404`	Recurso não encontrado no grupo econômico da credencial
`409`	O estado atual do recurso não permite a operação
`422`	Regra de negócio violada
`429`	Limite de requisições excedido

1.1.6 Limite de Requisições¶

O limite é de 100 requisições por minuto por credencial. Ao exceder, a API responde 429 com o header Retry-After indicando quantos segundos aguardar:

HTTP/1.1 429 Too Many Requests
Retry-After: 23

Trate o 429 como condição temporária, respeitando o Retry-After. Não faça retry imediato em laço.

1.1.7 Idempotência¶

Toda requisição que cria ou avança o estado de uma operação aceita o header Idempotency-Key, com um identificador único gerado por você (recomendamos UUID v4):

Idempotency-Key: 8f14e45f-ea4f-4e2c-9c3e-9b1a72d0c5f1

Reenviar a mesma chave devolve o resultado da primeira execução em vez de criar uma segunda operação. Use-a sempre em:

criação de proposta
simulação da proposta
submissão à análise de crédito
envio da proposta à bancarizadora
liquidação de parcela e geração de cobrança

Sem a chave, uma falha de rede seguida de retry pode gerar proposta ou cobrança duplicada.

1.1.8 A esteira é o ponto de partida¶

Toda operação de crédito pertence a uma esteira — a configuração que define o produto (EP ou CDC), as faixas de valor, prazo e taxa, os custos, se há análise de crédito e para quem vai o desembolso.

Por isso o identificador da esteira (idEsteira) aparece na rota dos serviços que iniciam algo:

POST /credito/esteiras/{idEsteira}/simulacao
POST /credito/esteiras/{idEsteira}/propostas

Depois que a proposta existe, ela já sabe a que esteira pertence, e as rotas passam a endereçar o recurso diretamente:

GET  /credito/propostas/{idProposta}
POST /credito/propostas/{idProposta}/envio

Comece sempre por 3.1. Esteiras para descobrir quais esteiras a sua credencial opera, e por 3.2. Parâmetros da Esteira para conhecer os limites da política antes de simular.

1.1.9 Fluxo Geral da Integração¶

A ordem das etapas pode variar por esteira. Em vez de fixar essa sequência no seu código, consulte proximaEtapa e pendencias em 6.10. Consultar, Listar e Pendências: a própria API informa o que falta e qual é o passo seguinte.