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

Esta área documenta a **API Pública de Bureau**, que hoje oferece a **consulta ao SCR** — o Sistema
de Informações de Crédito do Banco Central do Brasil.

Nesta seção apresentamos as **APIs** que permitem consultar o SCR de um titular — pessoa física ou
jurídica — direto do seu sistema, via VeTrust, com o resultado devolvido **mês a mês**.

A integração tem poucas etapas: conferir se o SCR está habilitado para o seu grupo econômico,
solicitar a consulta com o aceite do titular, aguardar o processamento e ler o resultado.

!!! danger "Cada consulta pode gerar custo e o resultado é sigiloso"
    Cada solicitação aceita é uma consulta nova e pode gerar custo, conforme os meses consultados com
    sucesso — **inclusive em homologação**. Uma consulta encerrada como `NAO_DESPACHADA` não gera
    custo. O resultado é dado pessoal sob sigilo bancário. Leia [1.2. Conceitos](1.2.%20Conceitos.md)
    antes de integrar: o aceite do titular, a cobrança por mês consultado e quem pode ver cada
    consulta estão descritos lá.

---

## 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 é feita em duas partes:

1. **A credencial de integração** (`clientId` e `clientSecret`), vinculada ao seu **grupo
   econômico**. Uma credencial só opera os grupos aos quais está vinculada.
2. **A habilitação do SCR no grupo econômico**, feita pelo time comercial, porque cada consulta gera
   cobrança. Não há autoatendimento para habilitar o SCR.

> **A habilitação vale para o grupo inteiro.** Com o SCR habilitado, **todas** as credenciais
> vinculadas ao grupo podem solicitar consultas. Se o seu grupo usa mais de uma credencial, combine
> internamente quais sistemas podem consultar.

Para conferir o que está liberado para a sua credencial, use
[3.1. Bureaus Habilitados](../3.%20Consulta%20SCR/3.1.%20Bureaus%20Habilitados.md).

Se a habilitação do SCR for retirada do grupo, todas as rotas `/bureaus/scr` passam a responder
`403` — inclusive a leitura de consultas já feitas e já cobradas. Antes de encerrar o uso, combine
com o nosso time para que as consultas em andamento terminem e os resultados sejam lidos.

---

## 1.1.2 Autenticação

Todas as requisições exigem os seguintes headers:

| Header | Tipo | Descrição |
|--------|------|-----------|
| `Authorization` | Bearer Token | Token obtido no endpoint de login |
| `GrupoEconomico` | string | Nome do grupo econômico. **Obrigatório em todas as rotas** |
| `Idempotency-Key` | string | **Obrigatório** na solicitação de consulta (`POST /bureaus/scr/consultas`). Ver 1.1.7 |

### Obtenção do Token

```bash
curl -X POST "https://api.vehub.com.br/public/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "seu-client-id",
    "clientSecret": "seu-client-secret"
  }'
```

#### Resposta

A resposta vem em **snake_case**, no formato do provedor de identidade:

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer"
}
```

O token expira em `expires_in` segundos. Renove-o antes do vencimento e **reaproveite o token entre
chamadas** — não solicite um token por requisição. Outros campos que venham na resposta podem ser
ignorados.

---

## 1.1.3 Ambientes

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

Nas tabelas de endpoint mostramos apenas o **caminho** (ex.: `/bureaus/scr/consultas`), que deve ser
concatenado à URL base do ambiente. Os exemplos de cURL trazem a URL completa.

!!! danger "Homologação consulta o SCR real e tem custo"
    Não existe SCR simulado. Uma consulta aceita em homologação vai ao provedor do SCR como em
    produção e **é cobrada nas mesmas condições**. Use em homologação apenas os documentos
    combinados com o nosso time e não automatize testes que solicitem consultas em laço.

    **Ler o resultado não custa:** as consultas por `GET` podem ser repetidas à vontade.

---

## 1.1.4 Padrões de Resposta

| Padrão | Formato | Exemplo |
|--------|---------|---------|
| Mês (período do SCR) | `yyyy-MM` | `2026-04` |
| Data e hora devolvida pela API | ISO 8601 em UTC, com `Z` | `2026-10-23T13:00:41.512345Z` |
| Data e hora informada por você | ISO 8601 **com fuso** (`Z` ou `±hh:mm`) | `2026-10-23T09:58:00-03:00` |
| Valores monetários | `number` sem separador de milhar | `15234.56` |
| Percentuais | `number` — `98.5` significa 98,5% | `98.5` |
| Status e enumerados | objeto `{ id, nome }` | `{ "id": 3, "nome": "Concluída" }` |
| Documento | só dígitos e letras, sem pontuação | `12345678900` |
| Atributos | `camelCase` em português | `mesInicial`, `dataAceiteTitular` |

As datas e horas devolvidas podem ter frações de segundo, de até 6 casas
(`2026-10-23T13:00:41.512345Z`), ou nenhuma (`2026-10-23T12:58:00Z`). Leia-as com um *parser*
ISO 8601, não com um formato fixo.

### Respostas de sucesso

As respostas de sucesso trazem o **próprio recurso**, sem envelope: a solicitação devolve os dados da
consulta criada, a leitura devolve a consulta e a listagem devolve o envelope de listagem abaixo.

### Envelope de listagem

Toda listagem é paginada e aceita `pagina` (a partir de `1`) e `quantidade` (de `1` a **100**,
padrão `10`):

```json
{
  "registros": [ ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 3,
    "paginaQuantidadeRegistro": 10,
    "quantidadeRegistros": 27,
    "temPaginaAnterior": false,
    "temProximaPagina": true
  },
  "mensagem": null
}
```

| Campo | Descrição |
|-------|-----------|
| paginacao.paginaAtual | Página devolvida |
| paginacao.paginaTotal | Total de páginas com a `quantidade` pedida |
| paginacao.paginaQuantidadeRegistro | Registros por página (a `quantidade` pedida) |
| paginacao.quantidadeRegistros | Total de registros que atendem aos filtros |
| paginacao.temPaginaAnterior / temProximaPagina | Se há página antes e depois desta |

Uma página além da última responde `200` com `registros` vazio.

---

## 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": "mesFinal", "mensagem": "O mês final não pode ser posterior ao mês corrente (2026-10)." }
  ]
}
```

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

As mensagens de erro **nunca repetem o documento do titular** — um documento recusado aparece como
"CPF inválido", sem o CPF.

### Códigos utilizados

| Código | Quando ocorre |
|--------|---------------|
| `200` | Sucesso nas consultas (`GET`) — inclusive quando a consulta ao SCR terminou em falha |
| `202` | Consulta aceita e em processamento — ver [1.3. Operações Assíncronas](1.3.%20Operações%20Assíncronas.md) |
| `400` | Corpo, parâmetro ou header inválido; regra de validação de campo |
| `401` | Token ausente, expirado ou inválido; header `GrupoEconomico` ausente |
| `403` | Credencial sem vínculo com o grupo, SCR não habilitado no grupo ou solicitação temporariamente suspensa |
| `404` | Consulta não encontrada para a sua credencial |
| `409` | A primeira execução com a mesma `Idempotency-Key` ainda está em processamento (ver 1.1.7) |
| `415` | `Content-Type` diferente de `application/json` no corpo |
| `422` | `Idempotency-Key` reutilizada com um corpo diferente (ver 1.1.7) |
| `500` | Erro interno. Ver 1.1.7 para saber se a consulta foi registrada |

### Os `403` desta área

| Situação | Mensagem em `errors[0].mensagem` |
|---|---|
| A credencial não está vinculada ao grupo informado em `GrupoEconomico` | `A credencial {clientId} não está habilitada para o grupo econômico {grupoEconomico}.` |
| O SCR não está habilitado para o grupo econômico | `O Bureau/Consulta SCR não está habilitado para este grupo econômico.` |
| A solicitação de novas consultas está temporariamente suspensa (só no `POST`) | `A solicitação de novas consultas SCR está temporariamente indisponível. As consultas já solicitadas continuam disponíveis para leitura.` |

Para separar os três casos, chame [3.1. Bureaus Habilitados](../3.%20Consulta%20SCR/3.1.%20Bureaus%20Habilitados.md):

- se ela também responder `403`, o problema é o **vínculo da credencial**;
- se responder `200` sem o SCR na lista, falta a **habilitação do grupo**;
- se responder `200` com o SCR na lista e só o `POST` responder `403`, é a **suspensão temporária**.

Nos dois primeiros casos, fale com o nosso time. Na suspensão temporária, as leituras (`GET`)
continuam funcionando: os resultados já obtidos seguem disponíveis. Aguarde e tente de novo mais
tarde.

### Os `401` desta área

| Situação | Mensagem em `errors[0].mensagem` |
|---|---|
| Requisição sem o header `Authorization` | `Token JWT não foi informado. Por favor, forneça um token válido.` |
| Requisição sem o header `GrupoEconomico` | `Header GrupoEconomico não informado. Por favor, forneça um Grupo Econômico válido.` |

Token expirado ou inválido também responde `401`: obtenha um token novo em
[1.1.2 Autenticação](#112-autenticacao). No `GrupoEconomico`, informe o nome do grupo exatamente
como foi entregue pelo nosso time.

---

## 1.1.6 Limites de Uso

Hoje a API **não aplica limite diário de consultas por credencial**. Cada consulta aceita pode gerar
custo: controle no seu sistema quantas solicitações são feitas e não as automatize em laço.

As leituras (`GET`) não têm custo, mas não faça *polling* agressivo: siga o ritmo sugerido em
[1.3. Operações Assíncronas](1.3.%20Operações%20Assíncronas.md).

---

## 1.1.7 Idempotência

Na solicitação de consulta (`POST /bureaus/scr/consultas`) o header `Idempotency-Key` é
**obrigatório**, com um identificador único gerado por você (recomendamos UUID v4):

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

Como cada consulta pode gerar custo, a chave é o que impede que um *timeout* de rede seguido de
*retry* gere **uma segunda consulta e um segundo custo**. A regra é simples:

- **uma chave por consulta**, gerada **antes** da primeira tentativa;
- em toda repetição daquela consulta, **a mesma chave e o mesmo corpo**.

### Desfechos de uma chamada com `Idempotency-Key`

A chave vale **por credencial e por grupo econômico**: a mesma chave usada por outra credencial do seu
grupo, ou pela mesma credencial em outro grupo, é uma operação diferente.

| Situação | Resposta | O que fazer |
|---|---|---|
| Requisição sem o header | `400`, antes de qualquer execução | Envie a chave |
| Chave com mais de **200 caracteres** | `400`, antes de qualquer execução | Corrija a chave (recomendamos UUID v4) |
| Primeira chamada com a chave | A consulta é registrada: `202` | Guarde o `idConsulta` |
| Mesma chave e mesmo corpo, primeira execução **concluída com sucesso** | A resposta da primeira execução, sem consultar de novo, com o header `Idempotent-Replay: true` | Use o `idConsulta` devolvido |
| Mesma chave depois de **24 horas** | Tratada como chave nova: a consulta é registrada de novo (`202`), com custo novo | Procure antes a consulta pela `referenciaExterna` em [3.4. Listar Consultas](../3.%20Consulta%20SCR/3.4.%20Listar%20Consultas.md) |
| Mesma chave e mesmo corpo, primeira execução **ainda em processamento** | `409` | Aguarde e repita **com a mesma chave**. Se o `409` persistir por mais de **10 minutos**, procure antes a consulta pela `referenciaExterna` em [3.4. Listar Consultas](../3.%20Consulta%20SCR/3.4.%20Listar%20Consultas.md) |
| Mesma chave com um **corpo diferente** | `422` | Não repita: a chave pertence a outra consulta. Use uma chave nova |
| A API não conseguiu registrar a chave | `500`: **nada foi executado** | Repita com a mesma chave |

Nos erros `400`, `409` e `422` de chave, o primeiro item de `errors` traz `campo` igual a
`Idempotency-Key`:

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.21",
  "status": 422,
  "errors": [
    { "campo": "Idempotency-Key", "mensagem": "Esta chave de idempotência já foi usada nesta rota com um corpo diferente. Use uma chave nova para uma operação nova." }
  ]
}
```

A resposta de uma execução concluída fica memorizada por **24 horas**. **A repetição devolve a
resposta original** — com o status `Pendente` do momento da criação. Para saber o status atual, use o
`GET` da consulta. Depois das 24 horas, a mesma chave é tratada como uma chave nova: a repetição
cria uma consulta nova, com custo novo.

Só respostas de sucesso são memorizadas: uma chamada que falhou libera a chave, e a repetição com a
mesma chave executa de novo. Enquanto a primeira execução corre, a chave fica reservada por até
**10 minutos**. Passado esse prazo, a reserva vence e uma repetição pode executar de novo — por isso
um `409` que persiste por mais de 10 minutos deve ser conferido pela `referenciaExterna` antes de
repetir.

!!! warning "Chave nova depois de um *timeout* = consulta nova e custo novo"
    Se você perdeu a resposta e não guardou a chave, **não gere uma chave nova de imediato**.
    Procure antes a consulta pela sua `referenciaExterna` em
    [3.4. Listar Consultas](../3.%20Consulta%20SCR/3.4.%20Listar%20Consultas.md). Só crie uma consulta
    nova se ela não estiver lá.

    Um `500` depois de a consulta ser registrada pode deixar uma consulta que nunca foi enviada ao
    provedor do SCR. Ela termina sozinha em `Falha`, com o motivo `NAO_DESPACHADA` e **sem custo** —
    ver [1.3. Operações Assíncronas](1.3.%20Operações%20Assíncronas.md).

---

## 1.1.8 Fluxo Geral da Integração

```mermaid
flowchart TD
    A[Autenticar] --> B[Conferir bureaus habilitados]
    B --> C{SCR na lista?}
    C -- Não --> Z[Falar com o nosso time]
    C -- Sim --> D[Coletar o aceite do titular]
    D --> E[Solicitar a consulta<br/>com Idempotency-Key]
    E --> F[202: guardar idConsulta]
    F --> G{Webhook recebido?}
    G -- Sim --> H[Ler a consulta]
    G -- Não --> I[Polling na consulta]
    I --> H
    H --> J{Status}
    J -- Pendente ou Processando --> I
    J -- Concluída --> K[Ler os períodos<br/>e tratar meses em Falha]
    J -- Falha --> L[Ler motivoFalha<br/>e decidir se refaz]
```

O passo a passo com os comandos está em
[5.1. Roteiro - Consulta SCR ponta a ponta](../5.%20Roteiros/5.1.%20Roteiro%20-%20Consulta%20SCR%20ponta%20a%20ponta.md).