> For the complete documentation index, see [llms.txt](https://docs.bullcredtech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bullcredtech.com/api-reference/readme.md).

# Introdução à API Bull

Tudo que você precisa para integrar sua plataforma com a Bull e originar propostas de crédito consignado privado, da validação de identidade ao contrato assinado digitalmente.

{% hint style="info" %}
Pressione <kbd>⌘K</kbd> (macOS) ou <kbd>Ctrl+K</kbd> (Windows) para buscar qualquer endpoint ou conceito nesta documentação.
{% endhint %}

## <mark style="color:$primary;">Primeiros passos</mark>

Siga essa sequência para fazer sua primeira originação:<br>

1. **Obtenha credenciais**: solicite `client_id` e `client_secret` à equipe de integração da Bull
2. **Autentique-se**: gere um token JWT via OAuth2 Client Credentials ([ver Autenticação](/api-reference/guias/authentication.md))
3. **Crie uma proposta**: siga o [Fluxo da Proposta](/api-reference/guias/proposal-flow.md) para originar sua primeira proposta
4. **Configure webhooks**: receba notificações de mudança de status em tempo real ([ver Webhooks](/api-reference/guias/webhooks.md))

## <mark style="color:$primary;">Ambientes e URLs base</mark>

| AMBIENTE     | URL BASE                                  | USO                      |
| ------------ | ----------------------------------------- | ------------------------ |
| **Produção** | `https://api.bullcredtech.com/v1`         | Operações reais          |
| **Staging**  | `https://api.staging.bullcredtech.com/v1` | Desenvolvimento e testes |

## <mark style="color:$primary;">Formato de dados</mark>

* **Content-Type**: `application/json`
* **Charset**: UTF-8
* **Formato de Data**: ISO 8601 (`YYYY-MM-DD` ou `YYYY-MM-DDTHH:mm:ss.sssZ`)

### <mark style="color:$primary;">Headers obrigatórios</mark>

Inclua esses headers em todas as requisições:

```http
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}
```

## <mark style="color:$primary;">Fluxo de originação: 7 etapas</mark>

O processo segue uma sequência obrigatória. Etapas marcadas como opcionais podem ser puladas.

<table><thead><tr><th width="105">E</th><th>ETAPA</th><th>ENDPOINT</th><th>DESCRIÇÃO</th></tr></thead><tbody><tr><td><mark style="color:$primary;"><strong>1</strong></mark></td><td><strong>Iniciar proposta</strong></td><td><code>POST /proposals/start</code></td><td>Criar proposta com CPF, nome e data de nascimento</td></tr><tr><td><mark style="color:$primary;"><strong>2</strong></mark></td><td><strong>Enviar contato</strong></td><td><code>POST /proposals/{id}/contact</code></td><td>Enviar email e telefone (dispara o token, por SMS)</td></tr><tr><td><mark style="color:$primary;"><strong>3</strong></mark></td><td><strong>Validar token</strong></td><td><code>POST /proposals/{id}/contact/validate-token</code></td><td>Validar código SMS</td></tr><tr><td><mark style="color:$info;"><strong>3.1</strong> (opcional)</mark></td><td><strong>Reenvio de token</strong></td><td><code>POST /proposals/{id}/contact/resend-token/whatsapp</code></td><td>Reenviar código via WhatsApp</td></tr><tr><td><mark style="color:$info;"><strong>3.2</strong> (opcional)</mark></td><td><strong>Reenvio de token</strong></td><td><code>POST /proposals/{id}/contact/resend-token</code></td><td>Reenviar código via SMS</td></tr><tr><td><mark style="color:$primary;"><strong>4</strong></mark></td><td><strong>Análise de crédito</strong></td><td><code>POST /proposals/{id}/credit-analysis</code></td><td>Solicitar análise de crédito</td></tr><tr><td>4<mark style="color:$info;"><strong>.1</strong> (opcional)</mark></td><td><strong>Ajustar oferta</strong></td><td><code>POST /proposals/{id}/simulate</code></td><td>Ajustar valor e/ou prazo</td></tr><tr><td><mark style="color:$primary;"><strong>5</strong></mark></td><td><strong>Pré-aceite</strong></td><td><code>POST /proposals/{id}/pre-accept</code></td><td>Aceitar oferta selecionada</td></tr><tr><td><mark style="color:$primary;"><strong>6</strong></mark></td><td><strong>Dados bancários</strong></td><td><code>POST /proposals/{id}/banking-data</code></td><td>Informar dados bancários para desembolso</td></tr><tr><td><mark style="color:$primary;"><strong>7</strong></mark></td><td><strong>Gerar contrato</strong></td><td><code>POST /proposals/{id}/contract</code></td><td>Gerar contrato e iniciar assinatura digital</td></tr></tbody></table>

## <mark style="color:$primary;">Endpoints de consulta</mark>

| ENDPOINT                               | DESCRIÇÃO                               |
| -------------------------------------- | --------------------------------------- |
| `GET /proposals`                       | Listar propostas com filtros            |
| `GET /proposals/{id}`                  | Detalhes completos de uma proposta      |
| `GET /proposals/statistics`            | Estatísticas das propostas              |
| `GET /proposals/{id}/contract`         | Status do contrato e link de assinatura |
| `GET /proposals/{id}/analysis-data`    | Dados e resultado da análise de crédito |
| `GET /proposals/{id}/message-timeline` | Histórico de envios de SMS/email        |

## <mark style="color:$primary;">Processamento assíncrono</mark>

Os endpoints de análise de crédito (`/credit-analysis`) e geração de contrato (`/contract`) podem levar alguns segundos. Por padrão, funcionam em modo **híbrido**: se o processamento terminar em até \~28 segundos, o resultado vem na própria resposta (`201 Created`); se passar disso, a API responde `202 Accepted` e continua em segundo plano.<br>

* `201 Created` → Processamento concluído, resultado na resposta
* `202 Accepted` → Processamento em andamento, resultado ainda não disponível. Consulte `GET /proposals/{id}/credit-analysis` ou `GET /proposals/{id}/contract`
* `409 Conflict` → Chamada durante um processamento já em andamento, aguarde o resultado
* Webhook → Receba a mudança de status assim que acontecer

Também existem as rotas `/credit-analysis/async` e `/contract/async`, que sempre respondem `202`.

{% hint style="warning" %}
**Janela de manutenção**

Sistemas de consulta de margem (Dataprev) ficam indisponíveis entre os dias **20 (22h)** e **23 (6h)** de cada mês. Evite gerar contratos neste período ou implemente tratamento de erro para este caso.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bullcredtech.com/api-reference/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.