---
title: 1.1. Primeiros Passos
url: https://docs.vehub.com.br/API/Nota%20Comercial/1.%20In%C3%ADcio/1.1.%20Primeiros%20Passos/
---
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](mailto: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)

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

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

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

```mermaid
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]
```