> 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/fluxo-da-proposta/post-proposals-start.md). # 1. Iniciar proposta **POST** `/proposals/start` Cria uma nova proposta de crédito consignado com os dados básicos do cliente. Este é o primeiro passo do fluxo de originação. ## Request Body | Campo | Tipo | Obrigatório | Descrição | Exemplo | | -------------------- | ------ | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | `cpf` | string | Sim | CPF do cliente (apenas números, 11 dígitos) | `"67593082121"` | | `full_name` | string | Não | Nome completo do cliente | `"Lucas Teste Proposta"` | | `birth_date` | string | Não | Data de nascimento (formato `YYYY-MM-DD`) | `"1980-01-22"` | | `utm_source` | string | Não | Origem da campanha de marketing | `"google"` | | `utm_medium` | string | Não | Meio/canal de marketing | `"cpc"` | | `utm_campaign` | string | Não | Nome da campanha de marketing | `"consignado_clt_2026"` | | `utm_term` | string | Não | Termo de busca da campanha | `"credito_clt"` | | `utm_content` | string | Não | Variação do conteúdo do anúncio | `"anuncio_variacao_a"` | | `device_fingerprint` | string | Não | Identificador opaco do dispositivo/navegador do cliente (máx. 256 caracteres). Usado apenas para correlação antifraude; não dispensa a validação do token neste passo | `"a3f1c9e2-5b4d-4e8a-9c17-2f6b8d0e1a45"` | | `tags` | object | Não | Tags livres da proposta, no formato `{ "nome": "valor" }` (ex.: id do lead no seu sistema). Gravadas apenas quando a proposta é **criada**; para adicionar a uma proposta existente use `POST /proposals/{id}/tags` | `{ "id_lead": "ABC123" }` | ## Exemplo de Requisição ```json { "cpf": "67593082121", "full_name": "Lucas Teste Proposta", "birth_date": "1980-01-22", "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "consignado_clt_2026", "tags": { "id_lead": "ABC123" } } ``` ## Resposta de Sucesso (201 Created) ```json { "message": "Proposta criada com sucesso", "proposal_id": "99afc6ce-4720-4746-9cf6-0a23e85cdf75", "cpf": "67593082121", "full_name": "LUCAS TESTE PROPOSTA", "product_id": "d82b9334-0cdf-494c-b414-d12b356e54e6", "status": "CREATED", "has_previous_contract": false } ``` ### Campos da Resposta | Campo | Tipo | Descrição | | ----------------------- | ------------- | --------------------------------------------------------------------------------------------- | | `message` | string | Mensagem de confirmação | | `proposal_id` | string (UUID) | **Identificador único da proposta** - usar em todas as próximas chamadas | | `cpf` | string | CPF do cliente (normalizado) | | `full_name` | string | Nome completo em maiúsculas | | `product_id` | string (UUID) | ID do produto de crédito associado | | `status` | string | Status atual: `CREATED` | | `has_previous_contract` | boolean | `true` quando o CPF já possui algum contrato na Bull (em qualquer canal e em qualquer status) | ## Proposta existente (reaproveitamento) Se o CPF já tiver uma proposta no seu canal em um dos status abaixo, a API **não cria uma nova proposta**: retorna a proposta existente, e você deve continuar o fluxo a partir do `status` retornado. `CREATED`, `CONTACT_PENDING`, `TOKEN_SENT`, `TOKEN_VALIDATED`, `CONSENT_RECEIVED`, `DATAPREV_FAILED_AWAITING_RETRY`, `CREDIT_ANALYSIS_FAILED`, `CREDIT_ANALYSIS_QUEUED`, `CREDIT_CHECK_COMPLETED`, `OFFER_SELECTED`, `PRE_ACCEPTED` e `BANK_DATA_SUBMITTED`. ```json { "message": "Proposta existente encontrada", "proposal_id": "99afc6ce-4720-4746-9cf6-0a23e85cdf75", "cpf": "67593082121", "full_name": "LUCAS TESTE PROPOSTA", "product_id": "d82b9334-0cdf-494c-b414-d12b356e54e6", "status": "TOKEN_SENT", "updated": false, "ownership_transferred": false, "has_previous_contract": false } ``` | Campo | Tipo | Descrição | | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | `message` | string | `Proposta existente encontrada` | | `status` | string | Status atual da proposta existente | | `updated` | boolean | `true` quando algum dado da proposta foi atualizado com os valores enviados | | `updated_fields` | array | Campos atualizados (`full_name`, `birth_date`, `utm_*`). Presente apenas quando `updated` é `true` | | `ownership_transferred` | boolean | Indica se a titularidade da proposta foi transferida para outro promotor (fluxo assistido). Para integrações via API, é `false` | Ao reaproveitar a proposta, `full_name` e `birth_date` enviados que forem diferentes dos já gravados são atualizados. ## Erros Possíveis | Código | Error Code | Mensagem | | ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | 400 | - | CPF inválido | | 409 | `PROPOSAL_PENDING_SIGNATURE` | Já existe uma proposta aguardando assinatura para este CPF (no seu canal) | | 409 | `PROPOSAL_BLOCKED_BY_POLICY` | Não é possível iniciar uma nova proposta no momento por políticas internas (há proposta aguardando assinatura em outro canal) | | 409 | `PROPOSAL_FINALIZED` | Já existe uma proposta finalizada para este CPF (quando a recontratação está desabilitada para o canal) | | 409 | `DELINQUENT_CONTRACT` | Contratação indisponível no momento; o corpo traz `longest_overdue_days` | | 409 | `KYC_DENIAL_COOLDOWN` | Início de proposta bloqueado temporariamente após negativa na verificação cadastral (KYC) | | 409 | `CREDIT_COOLDOWN_BLOCK` | Início de proposta bloqueado temporariamente após reprovação recente na análise de crédito | | 409 | `MARGIN_EXCEEDED_COOLDOWN` | Início de proposta bloqueado temporariamente por margem consignável excedida na averbação | | 409 | `CONTRACT_ACTIVE` | Já existe um contrato ativo com assinatura digital válida para este CPF | | 409 | `CONTRACT_EXISTS` | Já existe um contrato gerado para este CPF | | 409 | `PROPOSAL_PENDING_FRAUD_ANALYSIS` | Já existe uma proposta em análise de fraude para este CPF | | 409 | `PROPOSAL_PROCESSING_IN_PROGRESS` | Já existe uma proposta em processamento para este CPF | | 409 | `PROPOSAL_AWAITING_DISBURSEMENT` | Já existe uma proposta aprovada aguardando desembolso para este CPF | ### Erros 409 com bloqueio temporário Os códigos `KYC_DENIAL_COOLDOWN`, `CREDIT_COOLDOWN_BLOCK` e `MARGIN_EXCEEDED_COOLDOWN` retornam, além de `message` e `error_code`, os campos `blocked_until` (ISO 8601), `retry_after_seconds` e `friendly_message` (`title` e `description`, textos prontos para exibir ao cliente). O `KYC_DENIAL_COOLDOWN` traz também `reason_code`. Nenhuma proposta é criada enquanto o bloqueio estiver ativo. ```json { "statusCode": 409, "error": "Conflict", "message": "Não é possível iniciar uma nova proposta no momento.", "error_code": "CREDIT_COOLDOWN_BLOCK", "blocked_until": "2026-10-20T14:30:00.000Z", "retry_after_seconds": 345600, "friendly_message": { "title": "...", "description": "..." } } ``` ## Observações * O `proposal_id` retornado deve ser armazenado e utilizado em todas as próximas chamadas do fluxo * O nome é automaticamente convertido para maiúsculas * O CPF é validado quanto ao formato e dígitos verificadores * Se já existir uma proposta nos status listados em "Proposta existente (reaproveitamento)" para o CPF, a API retorna essa proposta em vez de criar outra * Os parâmetros UTM são opcionais e utilizados para atribuição de marketing. Ao reaproveitar uma proposta existente, os UTM enviados só são gravados se a proposta ainda não tiver nenhum UTM preenchido; se já tiver, os valores existentes são preservados * `tags` é opcional: até 50 pares `nome → valor` (strings de até 255 caracteres). Reenviar um nome já existente sobrescreve o valor. No reaproveitamento de proposta existente, as tags do body são ignoradas; use `POST /proposals/{id}/tags`. Parceiros que originam pela landing page conseguem o mesmo efeito pela URL, ver [Tags pela landing page](/api-reference/guias/landing-page-tags.md) {% hint style="success" %} **Próximo Passo** Após criar a proposta, envie os dados de contato: [POST /proposals/{id}/contact](/api-reference/fluxo-da-proposta/post-proposals-contact.md) {% 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/fluxo-da-proposta/post-proposals-start.md?ask=&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.