> 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/apis-en/guias/status-machine.md).

# Status machine

Each proposal goes through a sequence of statuses that represent its progress in the credit flow. This guide documents all 23 possible statuses, their transitions, and meanings.

## Complete diagram

```mermaid
flowchart TD
    subgraph REGISTRATION["1. Registration and Verification"]
        CREATED["CREATED"]
        CONTACT_PENDING["CONTACT_PENDING"]
        TOKEN_SENT["TOKEN_SENT"]
        TOKEN_VALIDATED["TOKEN_VALIDATED"]
    end

    subgraph ANALYSIS["2. Credit Analysis"]
        CONSENT_RECEIVED["CONSENT_RECEIVED"]
        CREDIT_ANALYSIS_IN_PROGRESS["CREDIT_ANALYSIS_IN_PROGRESS"]
        CREDIT_ANALYSIS_FAILED["CREDIT_ANALYSIS_FAILED"]
        CREDIT_CHECK_COMPLETED["CREDIT_CHECK_COMPLETED"]
    end

    subgraph OFFER["3. Offer Selection"]
        OFFER_SELECTED["OFFER_SELECTED"]
        PRE_ACCEPTED["PRE_ACCEPTED"]
    end

    subgraph CONTRACT["4. Contracting"]
        BANK_DATA_SUBMITTED["BANK_DATA_SUBMITTED"]
        CONTRACT_GENERATION_IN_PROGRESS["CONTRACT_GENERATION_IN_PROGRESS"]
        CONTRACT_GENERATED["CONTRACT_GENERATED"]
        AWAITING_SIGNATURE["AWAITING_SIGNATURE"]
        SIGNED["SIGNED"]
    end

    subgraph FRAUD["5. Fraud Analysis"]
        PENDING_ANALYSIS["PENDING_ANALYSIS"]
        ANALYSIS_APPROVED["ANALYSIS_APPROVED"]
    end

    subgraph FINAL["6. Completion"]
        DISBURSED["DISBURSED"]
    end

    CREATED --> CONTACT_PENDING
    CONTACT_PENDING --> TOKEN_SENT
    TOKEN_SENT --> TOKEN_VALIDATED
    TOKEN_VALIDATED --> CONSENT_RECEIVED
    CONSENT_RECEIVED --> CREDIT_ANALYSIS_IN_PROGRESS
    CREDIT_ANALYSIS_IN_PROGRESS -.-> CREDIT_ANALYSIS_FAILED
    CREDIT_ANALYSIS_FAILED -.->|Retry| CREDIT_ANALYSIS_IN_PROGRESS
    CREDIT_ANALYSIS_IN_PROGRESS --> CREDIT_CHECK_COMPLETED
    CREDIT_CHECK_COMPLETED --> OFFER_SELECTED
    CREDIT_CHECK_COMPLETED -.->|Rejected| REJECTED["REJECTED"]
    OFFER_SELECTED --> PRE_ACCEPTED
    PRE_ACCEPTED --> BANK_DATA_SUBMITTED
    BANK_DATA_SUBMITTED --> CONTRACT_GENERATION_IN_PROGRESS
    CONTRACT_GENERATION_IN_PROGRESS --> CONTRACT_GENERATED
    CONTRACT_GENERATION_IN_PROGRESS -.-> CONTRACT_GENERATION_FAILED["CONTRACT_GENERATION_FAILED"]
    CONTRACT_GENERATED --> AWAITING_SIGNATURE
    AWAITING_SIGNATURE --> SIGNED
    AWAITING_SIGNATURE -.->|Timeout| EXPIRED["EXPIRED"]
    AWAITING_SIGNATURE -.->|Biometrics| SIGNATURE_FAILED["SIGNATURE_FAILED"]
    AWAITING_SIGNATURE -.->|Cancel| CANCELED["CANCELED"]
    CONTRACT_GENERATED -.->|Cancel| CANCELED
    SIGNED --> PENDING_ANALYSIS
    SIGNED -.->|No analysis| DISBURSED
    SIGNED -.->|Dataprev| ERROR["ERROR"]
    PENDING_ANALYSIS --> ANALYSIS_APPROVED
    PENDING_ANALYSIS -.-> ANALYSIS_REPROVED["ANALYSIS_REPROVED"]
    ANALYSIS_APPROVED --> DISBURSED
    ANALYSIS_APPROVED -.-> DISBURSEMENT_FAILED["DISBURSEMENT_FAILED"]
    DISBURSED -.->|Refund| CANCELLED_BY_USER["CANCELLED_BY_USER"]

    style DISBURSED fill:#c8e6c9,color:#000
    style REJECTED fill:#ffcdd2,color:#000
    style EXPIRED fill:#ffe0b2,color:#000
    style SIGNATURE_FAILED fill:#ffcdd2,color:#000
    style CONTRACT_GENERATION_FAILED fill:#ffcdd2,color:#000
    style ANALYSIS_REPROVED fill:#ffcdd2,color:#000
    style ERROR fill:#ffcdd2,color:#000
    style CANCELED fill:#e0e0e0,color:#000
    style CANCELLED_BY_USER fill:#e0e0e0,color:#000
    style DISBURSEMENT_FAILED fill:#fff9c4,color:#000
```

## Main Flow Status

| #  | Status                            | Description                                                          |
| -- | --------------------------------- | -------------------------------------------------------------------- |
| 1  | `CREATED`                         | Proposal created with CPF, name, and date of birth                   |
| 2  | `CONTACT_PENDING`                 | Awaiting contact details (email and phone)                           |
| 3  | `TOKEN_SENT`                      | SMS token sent to the provided phone number                          |
| 4  | `TOKEN_VALIDATED`                 | SMS token successfully validated                                     |
| 5  | `CONSENT_RECEIVED`                | Consent for credit check received                                    |
| 6  | `CREDIT_ANALYSIS_IN_PROGRESS`     | Credit analysis being processed (asynchronous)                       |
| 7  | `CREDIT_ANALYSIS_FAILED`          | Technical failure in credit analysis, can be retried when applicable |
| 8  | `CREDIT_CHECK_COMPLETED`          | Analysis completed, offers generated                                 |
| 9  | `OFFER_SELECTED`                  | Customer selected an offer                                           |
| 10 | `PRE_ACCEPTED`                    | Pre-acceptance confirmed by the customer                             |
| 11 | `BANK_DATA_SUBMITTED`             | Bank details for disbursement sent                                   |
| 12 | `CONTRACT_GENERATION_IN_PROGRESS` | Contract being generated (asynchronous)                              |
| 13 | `CONTRACT_GENERATED`              | Contract successfully generated                                      |
| 14 | `AWAITING_SIGNATURE`              | Awaiting customer's digital signature                                |
| 15 | `SIGNED`                          | Contract digitally signed                                            |
| 16 | `PENDING_ANALYSIS`                | Awaiting fraud analysis (when applicable)                            |
| 17 | `ANALYSIS_APPROVED`               | Fraud analysis approved                                              |
| 18 | `DISBURSEMENT_FAILED`             | Disbursement failed (invalid bank details)                           |
| 19 | `DISBURSED`                       | Credit disbursed to the customer's account                           |

## Completion / Error Status

| Status                       | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| `REJECTED`                   | Rejected in credit analysis                              |
| `EXPIRED`                    | Contract expired without signature (D+1 until 9 PM)      |
| `CANCELED`                   | Canceled via API before disbursement                     |
| `CANCELLED_BY_USER`          | Canceled by the customer after disbursement (PIX refund) |
| `CONTRACT_GENERATION_FAILED` | Contract generation error                                |
| `SIGNATURE_FAILED`           | Digital signature failure (biometrics)                   |
| `ANALYSIS_REPROVED`          | Rejected in fraud analysis                               |
| `CREDIT_ANALYSIS_FAILED`     | Technical failure in credit analysis                     |
| `ERROR`                      | Dataprev recording failure (post-signature)              |

## Special Statuses

### DISBURSEMENT\_FAILED

Indicates that the disbursement attempt failed, usually due to a problem with the bank details or the destination account.

**Common reasons:** invalid account, blocked account, incorrect details (branch/account), or rejection on the receiving account/key.

{% hint style="warning" %}
In the current implementation, `POST /proposals/{id}/banking-data` does not allow resending data when the proposal is already in `DISBURSEMENT_FAILED`.
{% endhint %}

### CANCELED vs CANCELLED\_BY\_USER

|                      | CANCELED                                   | CANCELLED\_BY\_USER              |
| -------------------- | ------------------------------------------ | -------------------------------- |
| **When**             | Before disbursement                        | After disbursement               |
| **Who**              | Originator via API                         | Customer (PIX refund or support) |
| **Allowed statuses** | `CONTRACT_GENERATED`, `AWAITING_SIGNATURE` | `DISBURSED`                      |

For API cancellation, see [POST /proposals/{proposalId}/cancel](/api-reference/apis-en/proposal-flow/post-proposals-cancel.md).

### ERROR (Post-signature)

Occurs exclusively after signature when recording with Dataprev fails:

* Contract was successfully signed
* Recording in the government system failed
* Common during the maintenance window (days 20-23)
* Requires analysis and reprocessing

### CREDIT\_ANALYSIS\_FAILED

Indicates a technical failure during credit analysis.

This status may appear in cases such as:

* Dataprev unavailability
* credit engine failure
* instability in partners involved in the analysis

When this status is received:

* the partner must persist the proposal with this state
* the partner must decide when to call `POST /proposals/{proposalId}/credit-analysis/retry`
* the result must be tracked via webhook or proposal lookup

### EXPIRED (Signature Deadline)

| Event                               | Deadline                         |
| ----------------------------------- | -------------------------------- |
| Contract generated on 10/24 at 1 PM | Expires on 10/25 at 9 PM (\~32h) |
| Contract generated on 10/24 at 8 PM | Expires on 10/25 at 9 PM (\~25h) |

Rule: always **D+1 until 9 PM** (Brasília time).

## Fraud Analysis

After signature, some proposals go through fraud analysis before disbursement:

* High-value contracts
* Employer on the watchlist
* Cases flagged for manual review

Most proposals go straight from `SIGNED` to `DISBURSED` without fraud analysis.

## Status Classification

| Type              | Status                                                                                                                          | Color      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| **Success**       | `DISBURSED`, `ANALYSIS_APPROVED`                                                                                                | **Green**  |
| **Processing**    | `CREDIT_ANALYSIS_IN_PROGRESS`, `CONTRACT_GENERATION_IN_PROGRESS`, `PENDING_ANALYSIS`                                            | **Blue**   |
| **Attention**     | `DISBURSEMENT_FAILED`                                                                                                           | **Yellow** |
| **Final (error)** | `REJECTED`, `EXPIRED`, `SIGNATURE_FAILED`, `CONTRACT_GENERATION_FAILED`, `ANALYSIS_REPROVED`, `CREDIT_ANALYSIS_FAILED`, `ERROR` | **Red**    |
| **Canceled**      | `CANCELED`, `CANCELLED_BY_USER`                                                                                                 | **Gray**   |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bullcredtech.com/api-reference/apis-en/guias/status-machine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.