---
title: 1.1. Primeiros Passos
url: https://docs.vehub.com.br/Emiss%C3%A3o%20de%20Ativos/API/Cr%C3%A9dito/1.%20In%C3%ADcio/1.1.%20Primeiros%20Passos/
---
# 1.1. Primeiros Passos

!!! warning "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](mailto: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](../3.%20Referências/3.1.%20Esteiras.md).

---

## 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

```bash
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

```json
{
  "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:

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

### Envelope de listagem

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

```json
{
  "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:

```json
{
  "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](1.3.%20Operações%20Assíncronas.md) |
| `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
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):

```http
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](../3.%20Referências/3.1.%20Esteiras.md) para descobrir quais
esteiras a sua credencial opera, e por
[3.2. Parâmetros da Esteira](../3.%20Referências/3.2.%20Parâmetros%20da%20Esteira.md) para conhecer
os limites da política antes de simular.

---

## 1.1.9 Fluxo Geral da Integração

```mermaid
flowchart TD
    A[Autenticar] --> B[Listar esteiras habilitadas]
    B --> C[Consultar parâmetros da esteira]
    C --> D[Simular sem criar nada]
    D --> E{Cliente aceitou?}
    E -- Não --> D
    E -- Sim --> F[Consultar tomador por documento]
    F --> G[Criar proposta com dados do tomador]
    G --> H{Desembolso ao parceiro?}
    H -- Não --> I[Informar dados bancários do tomador]
    H -- Sim --> J[Informar parceiro originador]
    I --> K[Simular a proposta]
    J --> K
    K --> L[Avalistas e garantias, opcionais]
    L --> M[Enviar documentos exigidos]
    M --> N{Esteira exige análise?}
    N -- Sim --> O[Submeter ao motor de crédito]
    O --> P{Aprovada?}
    P -- Não --> Q[Fim: proposta recusada]
    P -- Sim --> R[Enviar proposta à bancarizadora]
    N -- Não --> R
    R --> S[Formalização conduzida pela bancarizadora]
    S --> T[Contrato ativo: parcelas, cobrança e liquidaçã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](../6.%20Proposta/6.10.%20Consultar,%20Listar%20e%20Pendências.md):
a própria API informa o que falta e qual é o passo seguinte.