# 7.1. Consultar status do contrato (polling)

Verifica o status atual do contrato e da assinatura digital de uma proposta. Também é o **endpoint de polling** após disparar o [`POST /contract`](/api-reference/fluxo-da-proposta/post-proposals-contract.md) (modos híbrido ou async).

Duas rotas equivalentes (mesmo shape de resposta):

| Endpoint                                      | Notas                                             |
| --------------------------------------------- | ------------------------------------------------- |
| **`GET /proposals/{proposalId}/contract`**    | Preferida (simétrico com `GET /credit-analysis`). |
| `GET /proposals/{proposalId}/contract/status` | Alias mantido por compatibilidade.                |

A resposta tem três comportamentos possíveis:

* **`200 OK`** — contrato gerado; payload contém status atual, dados da proposta, mutuário, oferta selecionada, etc. Mesmo shape do retorno do `POST /contract` síncrono.
* **`202 Accepted`** — contrato ainda em geração (proposta em `CONTRACT_GENERATION_IN_PROGRESS`). Cliente deve fazer polling.
* **`409 Conflict`** — proposta em status terminal (`EXPIRED`, `CANCELED`, `REJECTED`, `ERROR`, `CANCELLED_BY_USER`). Cliente deve abrir nova proposta.

{% hint style="info" %}
**Quando usar polling**

Use este endpoint sempre que disparou um `POST /contract` em modo assíncrono (explícito, legado ou híbrido com timeout). Intervalo recomendado: 2 segundos; abandonar após \~3 minutos.
{% endhint %}

## Parâmetros de URL

| Parâmetro    | Tipo          | Descrição      |
| ------------ | ------------- | -------------- |
| `proposalId` | string (UUID) | ID da proposta |

## Resposta — Geração em andamento (202 Accepted)

Retornado quando a proposta ainda está em `CONTRACT_GENERATION_IN_PROGRESS` (típico após receber `202` do `POST /contract`).

```json
{
  "async_processing": true,
  "message": "Geração de contrato em andamento — tente novamente em alguns segundos.",
  "proposal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "CONTRACT_GENERATION_IN_PROGRESS",
  "processing_started_at": "2026-05-11T19:00:00.000Z",
  "status_url": "/proposals/a1b2c3d4-e5f6-7890-abcd-ef1234567890/contract/status"
}
```

## Resposta — Proposta em status terminal (409 Conflict)

```json
{
  "code": "TERMINAL_PROPOSAL_STATUS",
  "message": "Não é possível consultar contrato de proposta em status EXPIRED. Inicie uma nova proposta.",
  "details": { "current_status": "EXPIRED" }
}
```

## Resposta de Sucesso (200 OK)

Retorna informações atualizadas sobre:

* Status da proposta
* Status da assinatura digital
* Status do contrato
* Informações de desembolso (se concluído)

```json
{
  "proposal_id": "99afc6ce-4720-4746-9cf6-0a23e85cdf75",
  "proposal_status": "AWAITING_SIGNATURE",
  "contract_id": "9f195264-b1f5-415f-97ea-8e7a51e04238",
  "contract_status": "CONTRACT_GENERATED",
  "digital_signature": {
    "signature_id": "ba0ded34-daf1-4433-8320-4e7e9fd19503",
    "status": "PENDING",
    "user_redirect_url": "https://cadastro.unico.app/process/1b8fc7d3-4012-4fb4-84cd-c0025d9b13d0",
    "expires_at": "2025-10-15T21:00:00.000Z"
  }
}
```

### Campos da Resposta

| Campo                                 | Tipo          | Descrição                   |
| ------------------------------------- | ------------- | --------------------------- |
| `proposal_id`                         | string (UUID) | ID da proposta              |
| `proposal_status`                     | string        | Status atual da proposta    |
| `contract_id`                         | string (UUID) | ID do contrato              |
| `contract_status`                     | string        | Status do contrato          |
| `digital_signature`                   | object        | Dados da assinatura digital |
| `digital_signature.status`            | string        | Status da assinatura        |
| `digital_signature.user_redirect_url` | string        | URL para assinatura         |
| `digital_signature.expires_at`        | string        | Prazo de expiração          |

### Status Possíveis da Assinatura

| Status        | Descrição                                            |
| ------------- | ---------------------------------------------------- |
| `PENDING`     | Aguardando assinatura do cliente                     |
| `IN_PROGRESS` | Cliente iniciou o processo na UNICO                  |
| `SIGNED`      | Contrato assinado com sucesso                        |
| `EXPIRED`     | Prazo de assinatura expirado                         |
| `REJECTED`    | Assinatura reprovada (falha na validação biométrica) |

## Erros Possíveis

| Código | Mensagem                            |
| ------ | ----------------------------------- |
| 404    | Proposta ou contrato não encontrado |

## Observações

* Use este endpoint para verificar se o cliente já assinou o contrato
* A `user_redirect_url` pode ser usada para redirecionar o cliente novamente caso ele não tenha concluído a assinatura
* Após `SIGNED`, o desembolso ocorre automaticamente
* Recomendamos usar [webhooks](/api-reference/guias/webhooks.md) para acompanhar mudanças de status em tempo real


---

# Agent Instructions: 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:

```
GET https://docs.bullcredtech.com/api-reference/fluxo-da-proposta/get-proposals-contract-status.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.