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.

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

A liberação é feita em duas partes:

A credencial de integração (clientId e clientSecret), vinculada ao seu grupo econômico. Uma credencial só opera os grupos aos quais está vinculada.
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.

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¶

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:

{
  "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.

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

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

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

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. 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.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):

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

{
  "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.

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. 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.1.8 Fluxo Geral da Integração¶

O passo a passo com os comandos está em 5.1. Roteiro - Consulta SCR ponta a ponta.