1.1. Primeiros Passos

Nesta seção, apresentamos o conjunto de APIs que viabilizam o processo de emissão e gestão de Notas Comerciais, por meio da plataforma VHub.

A integração contempla todo o ciclo de vida de uma Nota Comercial: cadastro de emitentes, simulação financeira, criação da operação, gestão de garantias, envio para aprovação, acompanhamento e liquidação de 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.

1.1.2 Autenticação¶

Todas as requisições exigem os seguintes headers de autenticação:

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 (OAuth2)¶

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

Resposta¶

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

1.1.3 Tipo de Integração¶

A chave de acesso pode ser gerada para dois perfis distintos:

Perfil	Comportamento
Parceiro	Visualiza apenas os financiadores e emitentes vinculados ao parceiro
Estruturador	Acesso completo a todos os recursos da plataforma

Importante: Não é possível cadastrar um novo financiador via API. O cadastro de escrituradores também não é suportado via API.

1.1.4 Ambientes¶

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

1.1.5 Padrões de Resposta¶

Padrão	Formato	Exemplo
Datas	`YYYY-MM-DD`	`2025-10-15`
Valores monetários	`number` sem separador de milhar	`15000.00`
Percentuais	`number`	`1.25`
Atributos	`camelCase` em português (exceto `id`)	`dataEmissao`, `valorLiquido`

1.1.6 Estrutura de Erros¶

Todas as respostas de erro seguem o padrão:

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'idEmitente' é obrigatório.",
    "Campo 'dataEmissao' deve ser uma data válida no formato YYYY-MM-DD."
  ]
}

Campo	Descrição
`tipo`	URI do tipo de problema (RFC 9110)
`titulo`	Título resumido do erro
`status`	Código HTTP do erro
`erros`	Lista de mensagens de validação detalhadas

1.1.7 Fluxo Geral da Integração¶

flowchart TD
    A[Autenticar] --> B[Consultar Enumerações]
    B --> C[Consultar Financiadores e Escrituradores]
    C --> D{Emitente já cadastrado?}
    D -- Não --> E[Cadastrar Emitente]
    E --> E1[Adicionar Assinantes]
    E1 --> E2[Enviar Documentos]
    E2 --> E3[Vincular ao Financiador]
    E3 --> E4[Habilitar no Escriturador]
    E4 --> F{Emitente aprovado?}
    D -- Sim --> F
    F -- Sim --> G[Simular Nota Comercial]
    G --> H[Criar Nota Comercial]
    H --> I[Adicionar Garantias]
    I --> J[Selecionar Minutas]
    J --> K[Enviar para Aprovação]
    K --> L[Acompanhar Status]
    L --> M[Marcar Parcelas como Pagas]