> 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/encerramento/submeter-solicitacao.md).

# Submeter Solicitação

Registra o encerramento de um **contrato FGTS já vigente** (formalizado, com garantia averbada na Caixa) — por **desistência no prazo legal** (`SEVEN_DAYS_REGRET`) ou **quitação antecipada** (`SETTLEMENT_DISCHARGE`). Após autorização na análise interna da Giro, leva à **desaverbação** da garantia na Caixa.

{% hint style="info" %}
**Ainda em formalização?** Use [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) (`DELETE /api/v1/fgts/contracts/{contractNumber}`) — não este endpoint.
{% endhint %}

{% hint style="info" %}
Esta operação é **assíncrona** e passa por **autorização interna da Giro** antes de ir à Caixa: a resposta `202` confirma apenas o registro. Acompanhe o desfecho por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/consultar-status.md) do `requestId` ou pelos eventos de webhook `CANCEL_RESERVE_*`.
{% endhint %}

{% hint style="warning" %}
Não confunda com outros cancelamentos da API:

* [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) (`DELETE .../contracts/{contractNumber}`) — cancela contrato **em formalização** (pré-terminal).
* [Cancelamento de Reserva por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md) (`POST /api/v1/fgts/reserve-cancellations`) — cancela uma reserva avulsa pelo `reserveIdentifier`, sem contrato associado.
* [Cancelar operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/gerenciar-operacoes/cancelar-operacao.md) (`DELETE /api/v1/fgts/operations/{requestId}`) — cancela uma **operação FGTS** submetida, antes do processamento.
  {% endhint %}

## Request

`POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Parâmetros

| Parâmetro         | Local  | Tipo                             | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                    |
| ----------------- | ------ | -------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractNumber`  | path   | `string` numérico, 1 a 8 dígitos | Sim         | Número do contrato FGTS vigente — o mesmo valor devolvido na formalização, zero-padded em 8 dígitos (ex.: `00012345`). O endpoint aceita uma faixa mais ampla de caracteres na entrada, mas **só valor numérico é processado**: qualquer outro formato é rejeitado adiante com `400`. Apenas contratos do próprio originator são acessíveis. |
| `Idempotency-Key` | header | `string` (máx. 100)              | Não         | Chave de idempotência de negócio. Reenviar a mesma chave dentro da janela de TTL retorna o `requestId` existente sem registrar novamente. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).                                                                                                       |

### Corpo

| Campo              | Tipo                | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------ | ------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cancellationType` | `enum`              | Sim         | Motivo do encerramento. Um de: `SEVEN_DAYS_REGRET` (desistência no prazo legal de 7 dias / arrependimento), `SETTLEMENT_DISCHARGE` (baixa por quitação antecipada ou liquidação), `OPERATIONAL_ERROR` (erro operacional, dados incorretos ou falha no envio), `FRAUD_PREVENTION` (suspeita de fraude ou análise de risco), `BANK_REJECTION` (banco/Caixa recusa por falta de saldo ou divergência), `JUDICIAL_ORDER` (determinação judicial), `OTHER` (outros motivos). |
| `reason`           | `string` (max 2000) | Não         | Justificativa textual livre, usada pela Giro na análise interna.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `originatorNote`   | `string` (max 500)  | Não         | Observação do originator, registrada na trilha de auditoria e visível aos operadores durante a análise.                                                                                                                                                                                                                                                                                                                                                                 |
| `paymentProof`     | `object`            | Não         | Comprovante do pagamento ou do estorno feito pelo cliente (PDF ou imagem). Ver [Objeto `paymentProof`](#objeto-paymentproof). Sem o campo, a solicitação segue exatamente como antes.                                                                                                                                                                                                                                                                                   |

#### Objeto `paymentProof`

| Campo           | Tipo               | Obrigatório | Descrição                                                                                                                                                                                                                                                        |
| --------------- | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentBase64` | `string` (Base64)  | Sim         | Conteúdo do arquivo em Base64 padrão (RFC 4648, com `=` de padding). O prefixo `data:<tipo>;base64,`, espaços e quebras de linha são aceitos e descartados. Até **5 MiB** decodificados (cerca de 6,99 MiB em Base64).                                           |
| `contentType`   | `string` (max 100) | Sim         | Tipo do arquivo — um de `application/pdf`, `image/png`, `image/jpeg`, sem parâmetros (`; charset=...` é recusado). Maiúsculas e espaços nas pontas são tolerados. O conteúdo precisa ser de fato desse tipo: um PNG declarado como `application/pdf` é recusado. |
| `filename`      | `string` (max 255) | Não         | Nome original do arquivo, sem `/` nem `\`. Informativo: hoje não é armazenado nem exibido na análise.                                                                                                                                                            |

{% hint style="info" %}
O comprovante fica disponível para quem analisa o encerramento na Giro e **não é enviado à Caixa**. É opcional em todos os `cancellationType`; num `SEVEN_DAYS_REGRET` com estorno já feito, enviá-lo aqui evita que a análise precise solicitá-lo por outro canal. Um comprovante inválido é recusado com `400`/`413` e **nada é registrado**: corrija e reenvie, mesmo com a mesma `Idempotency-Key`.
{% endhint %}

{% hint style="success" %}
O corpo **não** leva `cpf` nem `reserveIdentifier`: o `contractNumber` do path identifica a operação. O CPF é derivado do contrato e a reserva ativa é resolvida internamente. Campos extras enviados por integrações antigas são ignorados, sem erro.
{% endhint %}

## Response

| Campo       | Tipo            | Descrição                                                                                                                                                   |
| ----------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId` | `string` (uuid) | Identificador único da solicitação registrada, gerado pela API. Use no polling em `GET /api/v1/fgts/operations/{requestId}` e para correlacionar o webhook. |
| `status`    | `string`        | `QUEUED` — solicitação registrada e encaminhada para processamento assíncrono.                                                                              |

* **202 Accepted** — solicitação registrada. Ela entra em **análise interna da Giro** e só vai à Caixa após ser autorizada. O desfecho chega por webhook ou polling.

## Exemplo

```http
POST /api/v1/fgts/contracts/00012345/reserve-cancellations HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json
Idempotency-Key: terminate-00012345

{
  "cancellationType": "SETTLEMENT_DISCHARGE",
  "reason": "Contrato liquidado antecipadamente pelo cliente.",
  "originatorNote": "Solicitado via atendimento telefônico em 12/08."
}
```

```json
{
  "requestId": "a1b2c3d4-58cc-4372-a567-0e02b2c3d479",
  "status": "QUEUED"
}
```

### Com comprovante

```http
POST /api/v1/fgts/contracts/00015774/reserve-cancellations HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json
Idempotency-Key: cancel-00015774-2026-10-14

{
  "cancellationType": "SEVEN_DAYS_REGRET",
  "reason": "Cliente desistiu em 5 dias e estornou o PIX.",
  "originatorNote": "Estorno confirmado no extrato em 13/10.",
  "paymentProof": {
    "contentBase64": "JVBERi0xLjQK",
    "contentType": "application/pdf",
    "filename": "comprovante-estorno.pdf"
  }
}
```

A resposta é a mesma `202`:

```json
{
  "requestId": "019a2c0e-7b3e-7c1a-9f7d-3e2b1c0d9a10",
  "status": "QUEUED"
}
```

Comprovante acima do limite (`413`):

```json
{
  "type": "https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#business-rule-violation",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "Payment proof exceeds the maximum allowed size of 5242880 bytes",
  "instance": "/api/v1/fgts/contracts/00015774/reserve-cancellations",
  "errorCode": "PAYMENT_PROOF_TOO_LARGE",
  "timestamp": "2026-10-14T18:21:03Z"
}
```

## Próximo passo

Acompanhe o desfecho em [Acompanhar o encerramento](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/consultar-status.md) usando o `requestId` retornado, ou aguarde o callback no webhook cadastrado.

## Erros

| Status | Quando ocorre                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Corpo inválido — `cancellationType` ausente ou fora do enum, `reason`/`originatorNote` acima do limite, `Idempotency-Key` acima de 100 caracteres, `paymentProof` sem `contentBase64` ou sem `contentType`, `paymentProof.filename` acima de 255 caracteres ou com `/` ou `\` — `VALIDATION_ERROR` (campo em `errors`, ex.: `errors["paymentProof.contentType"]`). `contractNumber` não-numérico ou com mais de 8 dígitos — `CONTRACT_REQUEST_REJECTED`. |
| `400`  | Comprovante recusado: `PAYMENT_PROOF_UNSUPPORTED_CONTENT_TYPE` (`contentType` diferente de `application/pdf`, `image/png` e `image/jpeg`); `PAYMENT_PROOF_INVALID_BASE64` (`contentBase64` não é Base64 válido); `PAYMENT_PROOF_CONTENT_MISMATCH` (o conteúdo não é do tipo declarado em `contentType`). Nada é registrado.                                                                                                                              |
| `401`  | Token ausente, expirado ou inválido — `UNAUTHORIZED`.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `404`  | Contrato inexistente, ou pertencente a outro originator — `CONTRACT_NOT_FOUND`.                                                                                                                                                                                                                                                                                                                                                                          |
| `409`  | `CONTRACT_NO_ACTIVE_RESERVATION` — o contrato não tem reserva ativa a cancelar.                                                                                                                                                                                                                                                                                                                                                                          |
| `413`  | `PAYMENT_PROOF_TOO_LARGE` — comprovante acima de 5 MiB decodificado. Nada é registrado.                                                                                                                                                                                                                                                                                                                                                                  |
| `422`  | `IDEMPOTENCY_KEY_PAYLOAD_MISMATCH` — a `Idempotency-Key` já foi usada nesta rota com outro corpo ou para outro `contractNumber`. Nada é enfileirado; para uma operação nova, use uma chave nova. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md#payload-diferente).                                                                                                                                          |
| `500`  | Erro interno inesperado — `INTERNAL_ERROR`.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `503`  | Indisponibilidade temporária do processamento — `SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`). Repita com a **mesma** `Idempotency-Key`.                                                                                                                                                                                                                                                                                                |

Ver o formato de erro em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).
