> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md).

# Consultar Contrato

Consulta o **status atual** e os **marcos de formalização** de um contrato. Use para fazer polling do andamento (`requestId` aqui é o próprio `contractNumber`), como alternativa ao [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).

## Request

`GET /api/v1/fgts/contracts/{contractNumber}`

Autenticado: `Authorization: Bearer {originatorToken}` (perfil `ROLE_ORIGINATOR`).

### Parâmetros

| Parâmetro        | Local | Tipo                    | Obrigatório | Descrição                               |
| ---------------- | ----- | ----------------------- | ----------- | --------------------------------------- |
| `contractNumber` | path  | `string` (`^\d{1,20}$`) | Sim         | Número do contrato gerado na submissão. |

## Response

| Campo             | Tipo                | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractNumber`  | `string`            | Número do contrato.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `clientReference` | `string` (nullable) | Eco do `clientReference` informado na submissão, ou `null`.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `status`          | `string` (enum)     | Estado atual do contrato no ciclo de vida (ver tabela abaixo).                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `milestones`      | `object` (nullable) | Mapa de marco → timestamp ISO-8601 UTC. Cada marco é preenchido conforme ocorre (ex.: `receivedAt`, `endorsedAt`, `cancelledAt`); ainda não atingido aparece ausente ou `null`. `paidAt` é a **data** do pagamento à meia-noite de Brasília, ou seja `T03:00:00Z` (ex.: `2026-10-05T03:00:00Z` para 05/10/2026), e não o instante do desembolso.                                                                                                                                         |
| `error`           | `object` (nullable) | Hoje vem **sempre `null`**, inclusive em contrato com falha. O motivo de uma falha chega no `data.error` do webhook correspondente (`CONTRACT_ENDORSEMENT_REJECTED`, `CONTRACT_FORMALIZATION_FAILED`, `CONTRACT_DOCUMENT_GENERATION_FAILED`, `CONTRACT_PAYMENT_FAILED`) e, para a averbação, no [`GET` da operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md).                                   |
| `retry`           | `object` (nullable) | Presente em `PENDING_ENDORSEMENT` enquanto a averbação está em [retentativa automática](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#retrying): `providerAttempt`, `nextAttemptAt`, `windowExpiresAt` e `eligible`. Não traz o código da Caixa que motivou a espera — ele está em `retry.lastProviderError` no `GET` da operação.                                                                                                                                    |
| `revision`        | `object` (nullable) | Presente enquanto há uma revisão de conta de desembolso — o mesmo estado do webhook `CONTRACT_PAYMENT_REVISION`. Some quando a emenda é aceita; depois do prazo continua presente com `expired: true`. Campos: `expired` (`true` quando o prazo passou sem nova conta), `dueDate` (**último dia** em que a emenda é aceita, fuso de São Paulo — quando `dueAt` cai à meia-noite, é o dia anterior), `dueAt` (instante exato do prazo) e `availableActions` (`NEW_ACCOUNT` e/ou `RETRY`). |

\| `disbursement` | `object` (nullable) | Presente só em `PENDING_DISBURSEMENT`. `phase` diz em que ponto do desembolso o contrato está (tabela abaixo), `phaseSince` desde quando e `overdue` se a etapa passou do tempo esperado sem retorno do provedor. | | `cancellation` | `object` (nullable) | Presente quando há pedido de cancelamento — mesmo formato de [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md#response). | | `paymentReceiptUrl` | `string` (`uri`, máx. 512, nullable) | Link do comprovante do desembolso emitido pelo banco liquidante — o mesmo do webhook [`CONTRACT_PAID`](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md). Aparece depois do pagamento, inclusive quando o desembolso chega após um cancelamento; ausente enquanto não houver comprovante. **É uma credencial:** quem tem o link abre o comprovante sem autenticação. |

* **200 OK** — status do contrato retornado.

### Fases do desembolso (`disbursement.phase`)

| Fase                                    | Significado                                                                                | Cancelamento                  |
| --------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------- |
| `AWAITING_DISBURSEMENT`                 | CCB confirmada, aguardando o pagamento (normalmente minutos).                              | registrado e executado depois |
| `AWAITING_ACCOUNT_AMENDMENT`            | Revisão de conta aberta: o provedor precisa de uma nova conta.                             | imediato                      |
| `ACCOUNT_AMENDMENT_IN_FLIGHT`           | Nova conta enviada, aguardando o provedor aceitar.                                         | registrado e executado depois |
| `AWAITING_DISBURSEMENT_AFTER_AMENDMENT` | Conta aceita, aguardando o pagamento.                                                      | registrado e executado depois |
| `ACCOUNT_AMENDMENT_EXPIRED`             | Prazo da revisão passou sem nova conta. A Giro cancela o contrato 1 dia após o vencimento. | imediato                      |
| `DISBURSEMENT_FAILED`                   | O provedor informou falha no pagamento e ainda não abriu nova revisão.                     | registrado e executado depois |

### Estados (`status`)

| Estado                       | Significado                                                                                                                                                                                                                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RECEIVED`                   | Contrato recebido.                                                                                                                                                                                                                                                                                            |
| `AWAITING_SIGNED_DOCUMENT`   | Aguardando o PDF assinado (Modo B). Anexado o documento, segue direto para `PENDING_ENDORSEMENT`.                                                                                                                                                                                                             |
| `DOCUMENT_GENERATION_FAILED` | A geração da CCB falhou (Modo B). Acione o suporte. **Não é terminal**: se a geração for concluída depois — resultado atrasado ou geração refeita pelo suporte —, o contrato volta a `AWAITING_SIGNED_DOCUMENT` e chega o webhook `CONTRACT_DOCUMENT_GENERATED`. Não há nova tentativa automática além disso. |
| `PENDING_ENDORSEMENT`        | Aguardando averbação da garantia na Caixa.                                                                                                                                                                                                                                                                    |
| `ENDORSED`                   | Garantia averbada na Caixa.                                                                                                                                                                                                                                                                                   |
| `ENDORSEMENT_REJECTED`       | Averbação negada pela Caixa. O motivo **não** vem nesta consulta — ver o campo `error` acima. Admite [retentativa](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md).                                                                                          |
| `PENDING_PAYMENT_APPROVAL`   | Aguardando a sua [aprovação de pagamento](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/aprovar-pagamento.md) antes de seguir para a formalização.                                                                                                                                |
| `PENDING_FORMALIZATION`      | Aguardando formalização junto ao provedor.                                                                                                                                                                                                                                                                    |
| `PENDING_CCB_CONFIRMATION`   | Contrato enviado ao provedor bancário.                                                                                                                                                                                                                                                                        |
| `PENDING_DISBURSEMENT`       | Contrato formalizado pelo provedor; o bloco `disbursement` diz a fase.                                                                                                                                                                                                                                        |
| `DISBURSED`                  | Valor desembolsado ao tomador.                                                                                                                                                                                                                                                                                |
| `REVERSING_ENDORSEMENT`      | Desfazendo a averbação — após falha na formalização ou durante um cancelamento.                                                                                                                                                                                                                               |
| `FORMALIZATION_FAILED`       | Falha na formalização junto ao provedor.                                                                                                                                                                                                                                                                      |
| `REVERSAL_FAILED`            | Falha ao desfazer a averbação.                                                                                                                                                                                                                                                                                |
| `CANCELLED`                  | Contrato cancelado.                                                                                                                                                                                                                                                                                           |

## Exemplo

```http
GET /api/v1/fgts/contracts/00012345 HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
```

### Resposta — contrato averbado (`ENDORSED`)

```json
{
  "contractNumber": "00012345",
  "clientReference": "CLI-2024-00042",
  "status": "ENDORSED",
  "milestones": {
    "receivedAt": "2026-06-24T13:10:05Z",
    "endorsedAt": "2026-06-24T13:12:41Z"
  },
  "error": null
}
```

### Resposta — revisão de desembolso aberta (`PENDING_DISBURSEMENT`)

```json
{
  "contractNumber": "00012348",
  "clientReference": "CLI-2024-00045",
  "status": "PENDING_DISBURSEMENT",
  "milestones": {
    "receivedAt": "2026-06-20T12:00:00Z",
    "endorsedAt": "2026-06-20T12:05:00Z",
    "formalizedAt": "2026-06-21T09:00:00Z"
  },
  "error": null,
  "disbursement": {
    "phase": "AWAITING_ACCOUNT_AMENDMENT",
    "phaseSince": "2026-06-21T09:04:00Z",
    "overdue": false
  },
  "revision": {
    "dueDate": "2026-06-29",
    "dueAt": "2026-06-30T03:00:00Z",
    "availableActions": ["NEW_ACCOUNT", "RETRY"],
    "expired": false
  }
}
```

Use esta consulta para reconciliar quando o webhook `CONTRACT_PAYMENT_REVISION` se perdeu. O `ticket` interno do provedor nunca é exposto — a emenda é feita por [Revisar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md), que o resolve internamente.

### Resposta — averbação negada (`ENDORSEMENT_REJECTED`)

```json
{
  "contractNumber": "00012345",
  "clientReference": "CLI-2024-00042",
  "status": "ENDORSEMENT_REJECTED",
  "milestones": {
    "receivedAt": "2026-06-24T13:10:05Z"
  },
  "error": null
}
```

## Erros

| Código | Situação                                                                                                          |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| 400    | `contractNumber` fora do padrão — `errorCode = VALIDATION_ERROR`                                                  |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                  |
| 404    | Contrato inexistente ou fora do escopo do token — `errorCode = CONTRACT_NOT_FOUND`                                |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                            |
| 503    | Serviço temporariamente indisponível — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`) |

{% hint style="info" %}
Um contrato de outro originador retorna `404` (não `403`): o escopo do token não vê contratos fora dele.
{% endhint %}

Os erros seguem o formato `ProblemDetail` (RFC 7807), com o campo `errorCode`. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

O motivo de um contrato com falha não vem nesta resposta: o campo `error` sai `null`. Ver [Estados de contrato que indicam falha](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-contrato-estados).

## Consulta o status de um contrato por contractNumber

> Retorna o status atual e os marcos de um contrato identificado pelo \`contractNumber\`. Espelha o proxy do formalizer; os campos são repassados sem reescrita. A reserva/protocolo Caixa e o \`s3Key\` permanecem internos ao formalizer.\
> \*\*\`disbursement\`:\*\* presente apenas com \`status = PENDING\_DISBURSEMENT\`, descreve a fase do desembolso — inclusive quando aguarda ou está em curso uma emenda de conta.\
> \*\*\`cancellation\`:\*\* presente apenas quando há (ou houve) um pedido de cancelamento — ver \`DELETE\` neste mesmo recurso. O campo \`waitingFor\` só é devolvido na resposta do próprio \`DELETE\`; este \`GET\` não o traz.\
> \*\*\`revision.expired\`:\*\* a revisão de conta de desembolso passa a ser devolvida mesmo depois do ticket vencer, com \`expired: true\`, em vez de simplesmente sumir do payload.\
> \*\*Escopo por originador:\*\* apenas o originador dono do contrato pode consultá-lo; um \`contractNumber\` fora do escopo do token resolve para \`404\`.

```json
{"openapi":"3.0.3","info":{"title":"gtfgts-ingress Public API","version":"0.0.1"},"tags":[{"name":"fgts-contracts","description":"Submissão e acompanhamento de contratos (formalização) FGTS."}],"servers":[{"url":"https://ingress.gtfgts.staging.giro.tech","description":"Homologação (testes e validação da integração)"},{"url":"https://gtfgts.giro.tech","description":"Produção (operações reais)"},{"url":"http://localhost:8080","description":"Local (bootRun -Pprofiles=local)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT de originator fornecido pela GTLab no cadastro do originator. Identifica e autoriza o originator em todos os endpoints `/api/v1/**`.\nInclua no header: `Authorization: Bearer <token>`."}}},"paths":{"/api/v1/fgts/contracts/{contractNumber}":{"get":{"operationId":"getContract","tags":["fgts-contracts"],"summary":"Consulta o status de um contrato por contractNumber","description":"Retorna o status atual e os marcos de um contrato identificado pelo `contractNumber`. Espelha o proxy do formalizer; os campos são repassados sem reescrita. A reserva/protocolo Caixa e o `s3Key` permanecem internos ao formalizer.\n**`disbursement`:** presente apenas com `status = PENDING_DISBURSEMENT`, descreve a fase do desembolso — inclusive quando aguarda ou está em curso uma emenda de conta.\n**`cancellation`:** presente apenas quando há (ou houve) um pedido de cancelamento — ver `DELETE` neste mesmo recurso. O campo `waitingFor` só é devolvido na resposta do próprio `DELETE`; este `GET` não o traz.\n**`revision.expired`:** a revisão de conta de desembolso passa a ser devolvida mesmo depois do ticket vencer, com `expired: true`, em vez de simplesmente sumir do payload.\n**Escopo por originador:** apenas o originador dono do contrato pode consultá-lo; um `contractNumber` fora do escopo do token resolve para `404`.","responses":{"200":{"description":"Status atual do contrato.","content":{"application/json":{"schema":{"type":"object","description":"Resposta de `GET`/`DELETE` `/api/v1/fgts/contracts/{contractNumber}`. Espelha o proxy do formalizer; os campos são repassados sem reescrita. A reserva/protocolo Caixa e o `s3Key` permanecem internos ao formalizer e nunca são expostos; não há `contractId` (D16).","required":["contractNumber","status"],"properties":{"contractNumber":{"type":"string","description":"Número do contrato gerado pelo formalizer."},"clientReference":{"type":"string","nullable":true,"description":"Identificador do cliente no originador, ecoado."},"status":{"type":"string","enum":["RECEIVED","AWAITING_SIGNED_DOCUMENT","PENDING_ENDORSEMENT","ENDORSED","PENDING_PAYMENT_APPROVAL","PENDING_FORMALIZATION","PENDING_CCB_CONFIRMATION","PENDING_DISBURSEMENT","DISBURSED","DOCUMENT_GENERATION_FAILED","ENDORSEMENT_REJECTED","REVERSING_ENDORSEMENT","FORMALIZATION_FAILED","REVERSAL_FAILED","CANCELLED"],"description":"Status completo do ciclo de vida do contrato no formalizer."},"milestones":{"type":"object","nullable":true,"additionalProperties":{"type":"string","format":"date-time"},"description":"Mapa de marcos do ciclo de vida → timestamp (ISO-8601 UTC) em que cada marco foi atingido. Pode ser `null` quando ainda não há marcos."},"error":{"type":"object","nullable":true,"description":"Envelope de erro presente apenas quando o contrato falhou (ex.: `ENDORSEMENT_REJECTED`, `FORMALIZATION_FAILED`, `REVERSAL_FAILED`). Estrutura repassada do formalizer."},"revision":{"allOf":[{"type":"object","description":"Revisão de conta de desembolso em aberto. O `ticket` interno do provedor **nunca** é exposto — a emenda é feita por `PUT /api/v1/fgts/contracts/{contractNumber}/disbursement-account`, que o resolve internamente.","properties":{"dueDate":{"type":"string","format":"date","description":"Último dia (fuso de São Paulo) em que a emenda ainda é aceita. Quando `dueAt` cai à meia-noite, este é o dia **anterior** — o dia da virada não tem segundo útil. Mantido por compatibilidade; para decidir se ainda há tempo, use `dueAt`."},"dueAt":{"type":"string","format":"date-time","nullable":true,"description":"Instante exato (ISO-8601 UTC) de expiração do ticket. `null` em revisões abertas antes desta funcionalidade — nesse caso só `dueDate` está disponível."},"availableActions":{"type":"array","nullable":true,"uniqueItems":true,"minItems":1,"items":{"type":"string","enum":["NEW_ACCOUNT","RETRY"]},"description":"O que o provedor aceita nesta revisão. `NEW_ACCOUNT` = apenas conta/PIX **diferente** da que falhou. `RETRY` = reenviar a **mesma** conta também é aceito (falha por instabilidade bancária). Ausente em revisões abertas antes desta funcionalidade — ausência significa \"não informado\", trate como `NEW_ACCOUNT`."},"expired":{"type":"boolean","nullable":true,"description":"`true` quando o ticket de revisão já venceu (`dueAt` no passado) e o contrato segue aguardando ação — a revisão continua sendo devolvida (em vez de sumir) enquanto o cancelamento automático por vencimento ainda não foi aplicado. Ausente/`false` em revisões dentro do prazo."}}}],"nullable":true,"description":"Presente **apenas** enquanto há uma revisão de conta de desembolso aberta — o mesmo estado anunciado pelo webhook `CONTRACT_PAYMENT_REVISION`. Some quando a emenda é aceita ou o prazo expira. Use para reconciliar por polling quando o webhook se perdeu."},"retry":{"allOf":[{"type":"object","description":"Progresso da janela de retentativa automática da averbação. A Caixa devolveu um código transiente (3 ou 524, ou 14 confirmado por verificação) e o dispatcher reenvia a mesma reserva a cada 15 minutos por até 72 horas, sem intervenção do originador.","properties":{"providerAttempt":{"type":"integer","format":"int32","nullable":true,"description":"Quantas tentativas automáticas **nossas** já foram feitas contra a Caixa nesta janela (pode chegar a ~288 em 72h). **Não confundir** com o seu orçamento de retentativas manuais, que é de 3 por reserva."},"nextAttemptAt":{"type":"string","format":"date-time","nullable":true,"description":"Quando a próxima tentativa automática será feita."},"windowExpiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Fim da janela. Passado esse instante sem sucesso, a averbação é encerrada com `error.code = TRANSIENT_PROVIDER_RETRY_EXHAUSTED` e aí sim a retentativa manual é aceita."},"eligible":{"type":"boolean","nullable":true,"description":"Sempre `false` enquanto a janela está aberta: uma retentativa manual agora é recusada com `409 ENDORSEMENT_NOT_RETRYABLE`, porque a garantia ainda está em processamento."}}}],"nullable":true,"description":"Presente **apenas** enquanto a averbação está em retentativa automática — o mesmo estado anunciado pelo webhook `CONTRACT_ENDORSEMENT_RETRYING`. O contrato permanece em `PENDING_ENDORSEMENT` durante toda a janela; o bloco some quando a averbação se resolve."},"disbursement":{"allOf":[{"type":"object","description":"Fase do desembolso de um contrato em `PENDING_DISBURSEMENT`. Cobre tanto o caminho feliz (aguardando o desembolso ser efetivado) quanto o ciclo de emenda de conta (`REVISAO_DESEMBOLSO`) quando o gtbanker recusa a conta enviada.","required":["phase"],"properties":{"phase":{"type":"string","enum":["AWAITING_DISBURSEMENT","AWAITING_ACCOUNT_AMENDMENT","ACCOUNT_AMENDMENT_IN_FLIGHT","ACCOUNT_AMENDMENT_EXPIRED","AWAITING_DISBURSEMENT_AFTER_AMENDMENT","DISBURSEMENT_FAILED"],"description":"`AWAITING_DISBURSEMENT`: desembolso ainda não foi tentado. `AWAITING_ACCOUNT_AMENDMENT`: o gtbanker recusou a conta e aguarda o originador reenviar via `PUT .../disbursement-account` (ver `revision` no mesmo payload). `ACCOUNT_AMENDMENT_IN_FLIGHT`: a emenda foi enviada e está sendo processada pelo provedor. `ACCOUNT_AMENDMENT_EXPIRED`: o ticket de revisão venceu sem emenda — o contrato é cancelado automaticamente 1 dia depois. `AWAITING_DISBURSEMENT_AFTER_AMENDMENT`: a emenda foi aceita e o desembolso está sendo retentado. `DISBURSEMENT_FAILED`: o gtbanker informou falha no pagamento — o desembolso ainda pode ocorrer, ou pode chegar uma nova revisão de conta; não é um estado terminal."},"phaseSince":{"type":"string","format":"date-time","nullable":true,"description":"Instante (ISO-8601 UTC) em que o contrato entrou nesta fase."},"overdue":{"type":"boolean","nullable":true,"description":"`true` quando o desembolso está além do prazo normal de efetivação para a fase atual. Sinal operacional — não implica em ação disponível ao originador."}}}],"nullable":true,"description":"Presente **apenas** com `status = PENDING_DISBURSEMENT`. Descreve em que fase do desembolso o contrato está — inclusive quando aguarda ou está em curso uma emenda de conta (`REVISAO_DESEMBOLSO`)."},"cancellation":{"allOf":[{"type":"object","description":"Estado do pedido de cancelamento de um contrato — devolvido tanto pelo `DELETE /api/v1/fgts/contracts/{contractNumber}` (que o dispara) quanto pelo `GET` no mesmo recurso (para reconciliar por polling).","required":["outcome","requestedAt","requestedBy"],"properties":{"outcome":{"type":"string","enum":["PENDING","EXECUTED","REJECTED_DISBURSED"],"description":"`PENDING`: o contrato está em curso e o cancelamento foi gravado como pedido — resolve-se assim que o contrato sair do estado atual (ver `waitingFor`). `EXECUTED`: o cancelamento já foi aplicado. `REJECTED_DISBURSED`: o contrato já havia sido desembolsado quando o pedido chegou; o cancelamento não pôde ser atendido."},"requestedAt":{"type":"string","format":"date-time","description":"Instante (ISO-8601 UTC) em que o cancelamento foi solicitado."},"requestedBy":{"type":"string","enum":["ORIGINATOR","SYSTEM"],"description":"Quem solicitou o cancelamento. `ORIGINATOR`: pedido explícito via `DELETE`. `SYSTEM`: cancelamento automático da plataforma por ticket de revisão de conta vencido sem emenda. Os cancelamentos automáticos por recusa da averbação (`ENDORSEMENT_RETRY_WINDOW_EXPIRED`, `ENDORSEMENT_DENIED_NOT_RETRYABLE`) não trazem este bloco."},"resolvedAt":{"type":"string","format":"date-time","nullable":true,"description":"Instante (ISO-8601 UTC) em que o pedido foi resolvido. `null` enquanto `PENDING`."},"waitingFor":{"type":"string","nullable":true,"enum":["FORMALIZATION_IN_FLIGHT","CCB_CONFIRMATION","AWAITING_DISBURSEMENT","ACCOUNT_AMENDMENT_IN_FLIGHT","AWAITING_DISBURSEMENT_AFTER_AMENDMENT","DISBURSEMENT_FAILED"],"description":"Presente **apenas** com `outcome = PENDING` — o que o contrato precisa concluir antes do cancelamento ser aplicado."}}}],"nullable":true,"description":"Presente **apenas** quando há (ou houve) um pedido de cancelamento para este contrato. Ver `outcome`: `PENDING` enquanto o contrato ainda está em curso, `EXECUTED` quando o cancelamento já foi aplicado, `REJECTED_DISBURSED` quando o contrato já havia sido desembolsado e o pedido não pôde ser atendido."},"paymentReceiptUrl":{"type":"string","format":"uri","nullable":true,"description":"URL do comprovante de pagamento emitido pela instituição de pagamento no desembolso. Presente quando o desembolso foi confirmado (inclusive desembolso após cancelamento); ausente antes disso. Permanente; abre sem autenticação — trate como dado sensível."}}}}}},"400":{"description":"Requisição inválida — falha de validação de Bean Validation (campos obrigatórios ausentes, formatos incorretos, CPF com dígitos errados, etc.). O campo `errors` contém um mapa `{ \"campo\": \"mensagem\" }` para cada campo inválido. O campo `title` é sempre `\"Bean validation error\"` e `detail` é sempre `\"One or more fields were invalid. See 'errors' for details.\"`.\nRejeições de regra de negócio também chegam como `400`, com `errorCode` próprio (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Quando a rejeição aponta um campo do request, ela traz o mesmo `errors` e o mesmo `detail`; quando não há campo associado, `errors` é omitido e `detail` é o reason phrase do status.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"401":{"description":"Não autenticado — JWT ausente, inválido ou expirado. Autentique-se e inclua o token no header `Authorization: Bearer <token>`.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"404":{"description":"Recurso não encontrado — identificador inexistente ou ainda não processado.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"503":{"description":"Serviço temporariamente indisponível. Aguarde `Retry-After` segundos e tente novamente.","headers":{"Retry-After":{"description":"Segundos recomendados até a próxima tentativa.","schema":{"type":"integer","format":"int64"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}}}}}}}
```

## Resultado no webhook

Em vez de polling, você pode receber os marcos de formalização diretamente no webhook cadastrado (`source = CONTRACT`). Consulte [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md), [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) e o [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
