> 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/cancelar-contrato.md).

# Cancelar Contrato

Cancela um contrato **antes do desembolso**, em qualquer estado não-terminal. Quando o contrato pode ser cancelado imediatamente, a resposta é `200` com o status atualizado. Quando ele está no meio de uma etapa que não pode ser interrompida (envio ao provedor bancário, confirmação da CCB, desembolso em processamento), a Giro **registra o pedido** e responde `202`: o cancelamento é executado sozinho assim que a etapa terminar, e o resultado chega por webhook.

{% hint style="info" %}
**Contrato já pago (`DISBURSED`)?** Use [Encerramento de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento.md) — [`POST .../reserve-cancellations`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md) para desistência ou quitação antecipada com desaverbação na Caixa.
{% endhint %}

## Quando usar

| Situação do contrato                                                                                         | Resposta                                                                 | O que acontece                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Antes da averbação** (`RECEIVED`, `AWAITING_SIGNED_DOCUMENT`)                                              | `200` · `CANCELLED`                                                      | Cancelamento imediato.                                                                                                                                                                                                                                                                                 |
| **Averbação em andamento** (`PENDING_ENDORSEMENT`, inclusive na janela de retentativa da Caixa)              | `200` · `CANCELLED`                                                      | A Giro interrompe a averbação e, se a reserva já tiver sido criada na Caixa, desaverba automaticamente.                                                                                                                                                                                                |
| **Averbação recusada** (`ENDORSEMENT_REJECTED`)                                                              | `200` · `CANCELLED`                                                      | Não há reserva na Caixa a reverter.                                                                                                                                                                                                                                                                    |
| **Aguardando aprovação de pagamento** (`PENDING_PAYMENT_APPROVAL`)                                           | `200` · `REVERSING_ENDORSEMENT`                                          | A reserva é desaverbada automaticamente; ao concluir, o contrato vai a `CANCELLED`.                                                                                                                                                                                                                    |
| **Aguardando formalização** (`PENDING_FORMALIZATION`), fora do envio ao provedor                             | `200` · `REVERSING_ENDORSEMENT`                                          | Idem.                                                                                                                                                                                                                                                                                                  |
| **Envio ao provedor em andamento** (`PENDING_FORMALIZATION`) ou **CCB enviada** (`PENDING_CCB_CONFIRMATION`) | `202` · status inalterado                                                | Pedido registrado; executado quando a etapa terminar. Com a CCB recebida pelo provedor, segue para a aprovação do operacional (linha abaixo).                                                                                                                                                          |
| **CCB no provedor, sem desembolso** (`PENDING_DISBURSEMENT`, qualquer `disbursement.phase`)                  | `202` · `REVERSING_ENDORSEMENT`, `waitingFor = CCB_ARCHIVE_CONFIRMATION` | A operação da Giro arquiva a CCB no provedor bancário antes de desaverbar. **Arquivada:** a reserva é desaverbada e chega `CONTRACT_CANCELLED`. **Já paga:** o cancelamento é interrompido, chega `CONTRACT_CANCELLATION_REJECTED` (`CONTRACT_ALREADY_DISBURSED`) e o contrato segue para `DISBURSED`. |
| **Cancelamento já recusado por pagamento** (`cancellation.outcome = REJECTED_DISBURSED`)                     | `409`                                                                    | `CONTRACT_ALREADY_DISBURSED` — envie a [desistência](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md) (`SEVEN_DAYS_REGRET`).                                                                                                            |
| **Pago ou encerrado** (`DISBURSED`, `CANCELLED`, `FORMALIZATION_FAILED`, `REVERSAL_FAILED`)                  | `409`                                                                    | `CONTRACT_NOT_CANCELLABLE`.                                                                                                                                                                                                                                                                            |

Repetir o `DELETE` enquanto o pedido está pendente (inclusive aguardando a confirmação do arquivamento) devolve `202` com o mesmo `requestedAt`; repetir durante a reversão devolve `200` com o status atual.

{% hint style="info" %}
**O fim de todo cancelamento é `CANCELLED` com o webhook `CONTRACT_CANCELLED`** e `data.reason.code = CANCELLED_BY_ORIGINATOR`. Nos casos em que a reserva já existe na Caixa, o contrato passa por `REVERSING_ENDORSEMENT` enquanto a Giro desaverba, e o webhook chega quando a reserva é liberada. Não use [`POST .../reserve-cancellations`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md) para contratos ainda não pagos.
{% endhint %}

{% hint style="warning" %}
**Cancelar uma averbação recusada abre mão das retentativas restantes.** `CANCELLED` não tem volta: para tentar de novo depois, é preciso submeter um contrato novo. Enquanto o contrato segue em `ENDORSEMENT_REJECTED`, [`POST .../endorsement-retries`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md) continua disponível dentro do teto de 3 retentativas por reserva.
{% endhint %}

{% hint style="info" %}
**A Giro também cancela sozinha.** Uma averbação recusada que ninguém retentar dentro da janela é cancelada pela plataforma (`ENDORSEMENT_RETRY_WINDOW_EXPIRED`); recusa por **código 52** da Caixa é cancelada na chegada do resultado (`ENDORSEMENT_DENIED_NOT_RETRYABLE`). Uma **revisão de conta de desembolso que expira sem nova conta** é cancelada 1 dia após o vencimento, com a reserva desaverbada (`DISBURSEMENT_REVISION_EXPIRED`).
{% endhint %}

{% hint style="info" %}
Em `PENDING_PAYMENT_APPROVAL`, você pode **aprovar** o pagamento em [`POST .../payment-approval`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/aprovar-pagamento.md) em vez de cancelar. Para rejeitar, use este `DELETE`.
{% endhint %}

## Request

`DELETE /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`            | `CANCELLED` ou `REVERSING_ENDORSEMENT`. Com `202`, o status atual (inalterado), exceto em `PENDING_DISBURSEMENT`, que responde `REVERSING_ENDORSEMENT` com `cancellation.waitingFor = CCB_ARCHIVE_CONFIRMATION`.                                                                                                                                                                                                                                                 |
| `milestones`      | `object` (nullable) | Inclui `cancelledAt` quando o contrato chega a `CANCELLED`.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `cancellation`    | `object` (nullable) | Presente quando há pedido de cancelamento. Campos: `outcome` (`PENDING`, `EXECUTED` ou `REJECTED_DISBURSED`), `requestedAt`, `requestedBy` (`ORIGINATOR` ou `SYSTEM`), `resolvedAt` e, com `PENDING`, `waitingFor` — a etapa que o contrato está terminando (`FORMALIZATION_IN_FLIGHT`, `CCB_CONFIRMATION`, `AWAITING_DISBURSEMENT`, `ACCOUNT_AMENDMENT_IN_FLIGHT`, `AWAITING_DISBURSEMENT_AFTER_AMENDMENT`, `DISBURSEMENT_FAILED`, `CCB_ARCHIVE_CONFIRMATION`). |
| `error`           | `object` (nullable) | `null` em cancelamento bem-sucedido.                                                                                                                                                                                                                                                                                                                                                                                                                             |

* **200 OK** — cancelamento executado ou reversão da reserva iniciada.
* **202 Accepted** — pedido registrado; o cancelamento será executado quando a etapa em andamento terminar ou, com a CCB no provedor (`waitingFor = CCB_ARCHIVE_CONFIRMATION`), quando a operação da Giro confirmar o arquivamento.

## Exemplos

### Antes da averbação — `200` · `CANCELLED`

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

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

### Após averbação — `200` · `REVERSING_ENDORSEMENT`

```json
{
  "contractNumber": "00012346",
  "clientReference": "CLI-2024-00043",
  "status": "REVERSING_ENDORSEMENT",
  "milestones": {
    "receivedAt": "2026-07-01T12:00:00Z",
    "endorsedAt": "2026-07-01T12:05:00Z"
  },
  "cancellation": {
    "outcome": "EXECUTED",
    "requestedAt": "2026-07-01T13:00:00Z",
    "requestedBy": "ORIGINATOR",
    "resolvedAt": null
  },
  "error": null
}
```

### CCB no provedor, sem desembolso — `202` · `REVERSING_ENDORSEMENT`

```json
{
  "contractNumber": "00012347",
  "clientReference": "CLI-2024-00044",
  "status": "REVERSING_ENDORSEMENT",
  "milestones": {
    "receivedAt": "2026-09-22T12:00:00Z",
    "endorsedAt": "2026-09-22T12:05:00Z",
    "formalizedAt": "2026-09-22T12:40:00Z"
  },
  "cancellation": {
    "outcome": "PENDING",
    "requestedAt": "2026-09-22T12:41:10Z",
    "requestedBy": "ORIGINATOR",
    "resolvedAt": null,
    "waitingFor": "CCB_ARCHIVE_CONFIRMATION"
  },
  "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`                                                                                                                                                                       |
| 409    | Contrato pago (`DISBURSED`) ou em estado terminal (`CANCELLED`, `FORMALIZATION_FAILED`, `REVERSAL_FAILED`) — `errorCode = CONTRACT_NOT_CANCELLABLE`                                                                                                      |
| 409    | O cancelamento anterior foi interrompido porque o provedor já pagou — `errorCode = CONTRACT_ALREADY_DISBURSED`                                                                                                                                           |
| 4xx    | O serviço de formalização recusou a requisição — o `errorCode` dele é repassado, ou `CONTRACT_REQUEST_REJECTED` quando não há código próprio. Ver [Erros de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#formalizacao) |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                   |
| 503    | Serviço temporariamente indisponível — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`)                                                                                                                                        |

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).

## Cancela um contrato por contractNumber

> Solicita o cancelamento do contrato identificado pelo \`contractNumber\` e retorna o status resultante.\
> \*\*Escopo por originador:\*\* apenas o originador dono pode cancelar; um \`contractNumber\` fora do escopo do token resolve para \`404\`.\
> \*\*Desfecho do cancelamento:\*\* ao ser concluído — na hora ou depois de uma janela em \`PENDING\` — o contrato termina em \`status = CANCELLED\` e o originador recebe o webhook \`CONTRACT\_CANCELLED\` com \`result.reason.code = CANCELLED\_BY\_ORIGINATOR\` (pedido do originador) ou o código específico do gatilho automático (ver abaixo). Isso vale mesmo quando o desfecho imediato do \`DELETE\` é \`REVERSING\_ENDORSEMENT\`: esse é um status transitório enquanto a reserva é revertida na Caixa; o \`CONTRACT\_CANCELLED\` chega depois, via webhook. Enquanto a reversão está em curso, a resposta já traz \`cancellation.outcome = EXECUTED\` com \`resolvedAt = null\` — o cancelamento foi aceito e está sendo aplicado; \`resolvedAt\` só é preenchido quando o contrato chega a \`CANCELLED\`.\
> \*\*Antes da averbação:\*\* retorna \`status = CANCELLED\`.\
> \*\*Averbação em andamento:\*\* contrato em \`PENDING\_ENDORSEMENT\` — inclusive dentro da janela de retentativa da Caixa — é cancelável e retorna \`status = CANCELLED\` na hora. A plataforma interrompe a averbação e confere a reserva na Caixa: se ela já tiver sido criada, é desaverbada automaticamente, sem nova ação do originador.\
> \*\*Envio ao provedor em curso (\`PENDING\_FORMALIZATION\`):\*\* se o envio da CCB ao gtbanker está em andamento (\`POST operations\` disparado e ainda não confirmado), o cancelamento \*\*não\*\* pode ser aplicado na hora — responde \`202\` com \`cancellation.outcome = PENDING\` e \`cancellation.waitingFor = FORMALIZATION\_IN\_FLIGHT\`, executado assim que o envio terminar. Fora dessa janela, \`PENDING\_FORMALIZATION\` cancela na hora: responde \`200\` com \`status = REVERSING\_ENDORSEMENT\`.\
> \*\*Rejeição de pagamento (pós-averbação):\*\* se o contrato aguarda sua aprovação manual de pagamento, use este endpoint em vez de \`POST .../payment-approval\`. A reserva na Caixa é revertida — o status retornado é \`REVERSING\_ENDORSEMENT\`, não \`CANCELLED\`.\
> \*\*Averbação recusada:\*\* contrato em \`ENDORSEMENT\_REJECTED\` é cancelável e retorna \`status = CANCELLED\` — não há reserva na Caixa a reverter. O cancelamento é definitivo e abre mão das retentativas restantes de \`POST .../endorsement-retries\`.\
> \*\*Cancelamento automático:\*\* uma averbação recusada que ninguém retentar dentro da janela configurada é cancelada pela plataforma, e o originador recebe o evento \`CONTRACT\_CANCELLED\` com \`result.reason.code = ENDORSEMENT\_RETRY\_WINDOW\_EXPIRED\`. Recusa por código 52 da Caixa ("Trabalhador já possui quantidade máxima permitida de operação de reserva") não espera a janela: o contrato é cancelado na chegada do resultado, com \`result.reason.code = ENDORSEMENT\_DENIED\_NOT\_RETRYABLE\`. Um ticket de revisão de conta de desembolso vencido sem emenda também é cancelado automaticamente (\`cancellation.requestedBy = SYSTEM\`), com \`result.reason.code = DISBURSEMENT\_REVISION\_EXPIRED\`.\
> \*\*Contrato em curso (\`202\`):\*\* com o contrato em \`PENDING\_FORMALIZATION\` (envio em curso), \`PENDING\_CCB\_CONFIRMATION\`, ou \`PENDING\_DISBURSEMENT\` nas fases em curso (\`disbursement.phase = AWAITING\_DISBURSEMENT | ACCOUNT\_AMENDMENT\_IN\_FLIGHT | AWAITING\_DISBURSEMENT\_AFTER\_AMENDMENT | DISBURSEMENT\_FAILED\`), o cancelamento não pode ser aplicado na hora — o pedido é gravado (\`cancellation.outcome = PENDING\`) e resolvido assim que o contrato sair do estado atual (\`cancellation.waitingFor\`). Repetir o \`DELETE\` enquanto \`PENDING\` devolve \`202\` com o mesmo \`cancellation.requestedAt\` (nenhuma nova gravação). Exceção: \`PENDING\_DISBURSEMENT\` com uma emenda de conta aguardando o originador ou já vencida (\`disbursement.phase = AWAITING\_ACCOUNT\_AMENDMENT | ACCOUNT\_AMENDMENT\_EXPIRED\`) cancela na hora e responde \`200\`. Esses dois estados \*\*deixam de responder \`409\`\*\*.\
> \*\*Repetir o \`DELETE\` durante a reversão:\*\* com o contrato já em \`REVERSING\_ENDORSEMENT\` por um cancelamento — ou seja, exceto quando a reversão veio de uma rejeição de pagamento via \`POST .../payment-approval\` — um novo \`DELETE\` é idempotente e responde \`200\` com o status atual — sem reiniciar a reversão.\
> \*\*Estados não canceláveis:\*\* contratos já \`CANCELLED\`, por qualquer motivo, respondem \`409\` (\`CONTRACT\_NOT\_CANCELLABLE\`) — assim como qualquer outro estado terminal, inclusive \`DISBURSED\`.

```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}":{"delete":{"operationId":"cancelContract","tags":["fgts-contracts"],"summary":"Cancela um contrato por contractNumber","description":"Solicita o cancelamento do contrato identificado pelo `contractNumber` e retorna o status resultante.\n**Escopo por originador:** apenas o originador dono pode cancelar; um `contractNumber` fora do escopo do token resolve para `404`.\n**Desfecho do cancelamento:** ao ser concluído — na hora ou depois de uma janela em `PENDING` — o contrato termina em `status = CANCELLED` e o originador recebe o webhook `CONTRACT_CANCELLED` com `result.reason.code = CANCELLED_BY_ORIGINATOR` (pedido do originador) ou o código específico do gatilho automático (ver abaixo). Isso vale mesmo quando o desfecho imediato do `DELETE` é `REVERSING_ENDORSEMENT`: esse é um status transitório enquanto a reserva é revertida na Caixa; o `CONTRACT_CANCELLED` chega depois, via webhook. Enquanto a reversão está em curso, a resposta já traz `cancellation.outcome = EXECUTED` com `resolvedAt = null` — o cancelamento foi aceito e está sendo aplicado; `resolvedAt` só é preenchido quando o contrato chega a `CANCELLED`.\n**Antes da averbação:** retorna `status = CANCELLED`.\n**Averbação em andamento:** contrato em `PENDING_ENDORSEMENT` — inclusive dentro da janela de retentativa da Caixa — é cancelável e retorna `status = CANCELLED` na hora. A plataforma interrompe a averbação e confere a reserva na Caixa: se ela já tiver sido criada, é desaverbada automaticamente, sem nova ação do originador.\n**Envio ao provedor em curso (`PENDING_FORMALIZATION`):** se o envio da CCB ao gtbanker está em andamento (`POST operations` disparado e ainda não confirmado), o cancelamento **não** pode ser aplicado na hora — responde `202` com `cancellation.outcome = PENDING` e `cancellation.waitingFor = FORMALIZATION_IN_FLIGHT`, executado assim que o envio terminar. Fora dessa janela, `PENDING_FORMALIZATION` cancela na hora: responde `200` com `status = REVERSING_ENDORSEMENT`.\n**Rejeição de pagamento (pós-averbação):** se o contrato aguarda sua aprovação manual de pagamento, use este endpoint em vez de `POST .../payment-approval`. A reserva na Caixa é revertida — o status retornado é `REVERSING_ENDORSEMENT`, não `CANCELLED`.\n**Averbação recusada:** contrato em `ENDORSEMENT_REJECTED` é cancelável e retorna `status = CANCELLED` — não há reserva na Caixa a reverter. O cancelamento é definitivo e abre mão das retentativas restantes de `POST .../endorsement-retries`.\n**Cancelamento automático:** uma averbação recusada que ninguém retentar dentro da janela configurada é cancelada pela plataforma, e o originador recebe o evento `CONTRACT_CANCELLED` com `result.reason.code = ENDORSEMENT_RETRY_WINDOW_EXPIRED`. Recusa por código 52 da Caixa (\"Trabalhador já possui quantidade máxima permitida de operação de reserva\") não espera a janela: o contrato é cancelado na chegada do resultado, com `result.reason.code = ENDORSEMENT_DENIED_NOT_RETRYABLE`. Um ticket de revisão de conta de desembolso vencido sem emenda também é cancelado automaticamente (`cancellation.requestedBy = SYSTEM`), com `result.reason.code = DISBURSEMENT_REVISION_EXPIRED`.\n**Contrato em curso (`202`):** com o contrato em `PENDING_FORMALIZATION` (envio em curso), `PENDING_CCB_CONFIRMATION`, ou `PENDING_DISBURSEMENT` nas fases em curso (`disbursement.phase = AWAITING_DISBURSEMENT | ACCOUNT_AMENDMENT_IN_FLIGHT | AWAITING_DISBURSEMENT_AFTER_AMENDMENT | DISBURSEMENT_FAILED`), o cancelamento não pode ser aplicado na hora — o pedido é gravado (`cancellation.outcome = PENDING`) e resolvido assim que o contrato sair do estado atual (`cancellation.waitingFor`). Repetir o `DELETE` enquanto `PENDING` devolve `202` com o mesmo `cancellation.requestedAt` (nenhuma nova gravação). Exceção: `PENDING_DISBURSEMENT` com uma emenda de conta aguardando o originador ou já vencida (`disbursement.phase = AWAITING_ACCOUNT_AMENDMENT | ACCOUNT_AMENDMENT_EXPIRED`) cancela na hora e responde `200`. Esses dois estados **deixam de responder `409`**.\n**Repetir o `DELETE` durante a reversão:** com o contrato já em `REVERSING_ENDORSEMENT` por um cancelamento — ou seja, exceto quando a reversão veio de uma rejeição de pagamento via `POST .../payment-approval` — um novo `DELETE` é idempotente e responde `200` com o status atual — sem reiniciar a reversão.\n**Estados não canceláveis:** contratos já `CANCELLED`, por qualquer motivo, respondem `409` (`CONTRACT_NOT_CANCELLABLE`) — assim como qualquer outro estado terminal, inclusive `DISBURSED`.","responses":{"200":{"description":"Cancelamento ou rejeição processada; status atualizado 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."}}}}}},"202":{"description":"Pedido de cancelamento gravado; o contrato ainda está em curso (`cancellation.outcome = PENDING`). Repita a consulta por `GET` — ou repita este mesmo `DELETE`, que devolve `202` com o mesmo `cancellation.requestedAt` — para acompanhar a resolução.","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."}}}}}},"409":{"description":"Conflito com o estado atual do recurso — o pedido é válido, mas não cabe no estado em que o recurso está. O caso específico vem no `errorCode` do corpo; a descrição de cada rota lista os códigos que ela pode devolver.","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

O cancelamento é notificado com `CONTRACT_CANCELLED` (`source = CONTRACT`) quando o contrato chega a `CANCELLED` — inclusive nos pedidos respondidos com `202`. Se a operação da Giro confirmar que o provedor já pagou a CCB, chega `CONTRACT_CANCELLATION_REJECTED` com `data.error.code = CONTRACT_ALREADY_DISBURSED`, o `cancellation.outcome` passa a `REJECTED_DISBURSED` e, quando o pagamento é confirmado, chega `CONTRACT_PAID`. Para desfazer a operação a partir daí, envie a [desistência](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md) com `cancellationType = SEVEN_DAYS_REGRET`. 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/>" %}
