> 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/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md).

# Cancelamento de Reserva por identificador

{% hint style="warning" %}
**Tem um contrato?** Prefira [`POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md): o `contractNumber` já identifica a reserva, então você não precisa guardar o `reserveIdentifier` nem reenviar o CPF.

Este endpoint permanece disponível para cancelar uma reserva **avulsa** — averbada sem contrato associado na Giro. A reserva é identificada por **exatamente um** de dois campos: `reserveIdentifier` ou `contractNumber` (o número do contrato usado na averbação, quando você não guardou o `reserveIdentifier`).
{% endhint %}

Admite uma operação de cancelamento de reserva FGTS de forma assíncrona com prioridade `NORMAL`. Quando concluída com sucesso, o resultado conterá um protocolo gerado pela Caixa como comprovante do cancelamento.

{% hint style="info" %}
Esta operação é **assíncrona**: a resposta `202` confirma apenas a admissão. O resultado chega depois via [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) ou por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) do `requestId`.
{% endhint %}

## Request

`POST /api/v1/fgts/reserve-cancellations`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Parâmetros

| Parâmetro         | Local  | Tipo               | Obrigatório | Descrição                                                                                                                                                                                                     |
| ----------------- | ------ | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | header | `string` (max 100) | Não         | Chave de idempotência de negócio. Reenviar a mesma chave retorna o `requestId` existente sem publicar novamente. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md). |

### Corpo

| Campo               | Tipo                                | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------- | ----------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpf`               | `string` (11 dígitos, `^\d{11}$`)   | Sim         | CPF do trabalhador, 11 dígitos numéricos sem pontuação.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `reserveIdentifier` | `string` (`^[A-Za-z0-9._-]{1,50}$`) | Condicional | Identificador da reserva FGTS a cancelar — o valor devolvido no `202` da [averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md) (formato `GTD…`, 13 ou 14 caracteres: o código do originador no final tem 2 ou 3). **Exatamente um** dos dois — `reserveIdentifier` ou `contractNumber` — deve ser informado.                                                                                                           |
| `contractNumber`    | `string` (`^\d{1,8}$`)              | Condicional | Número do contrato cuja **garantia mais recente** será cancelada, quando o `reserveIdentifier` não está disponível para o originador. **Exatamente um** dos dois — `reserveIdentifier` ou `contractNumber` — deve ser informado.                                                                                                                                                                                                                                                                      |
| `cancellationType`  | `enum`                              | Sim         | Motivo do cancelamento. Um de: `SEVEN_DAYS_REGRET` (desistência no prazo legal de 7 dias / arrependimento), `SETTLEMENT_DISCHARGE` (baixa por quitação antecipada ou liquidação do contrato), `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 não especificados). |
| `reason`            | `string` (max 2000)                 | Não         | Justificativa textual livre, usada pela Giro na revisão manual.                                                                                                                                                                                                                                                                                                                                                                                                                                       |

{% hint style="warning" %}
`reserveIdentifier` e `contractNumber` são **mutuamente exclusivos**: enviar **os dois** — ou **nenhum** — retorna `400 VALIDATION_ERROR`. Antes, `contractNumber` era um campo desconhecido e ignorado; quem o enviava junto do `reserveIdentifier` passa a receber `400`.
{% endhint %}

## Response

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

* **202 Accepted** — cancelamento de reserva admitido para processamento assíncrono. Quando concluído, o `result` do polling conterá um protocolo.

## Exemplo

### Por `reserveIdentifier`

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

{
  "cpf": "12345678901",
  "reserveIdentifier": "GTD00000042AB",
  "cancellationType": "SETTLEMENT_DISCHARGE",
  "reason": "Contrato liquidado antecipadamente pelo cliente."
}
```

### Por `contractNumber`

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

{
  "cpf": "12345678901",
  "contractNumber": "12345678",
  "cancellationType": "SETTLEMENT_DISCHARGE",
  "reason": "Contrato liquidado antecipadamente pelo cliente."
}
```

Resposta (`202`), nos dois modos:

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

## Próximo passo

Acompanhe o resultado em [Consultar status da operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) usando o `requestId` retornado, ou aguarde o callback no webhook cadastrado.

## Erros

| Código | Situação                                                                                                                                                                                                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Validação de payload (campo obrigatório ausente, CPF fora do padrão `^\d{11}$`, `reserveIdentifier`/`contractNumber` inválidos, **os dois informados juntos ou nenhum informado**, etc.) — `errorCode = VALIDATION_ERROR`                                                             |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                                                      |
| 422    | `Idempotency-Key` já usada nesta rota com outro corpo — `errorCode = IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`. 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) |
| 429    | Hard ceiling de rate limit de ingresso excedido — `errorCode = INGRESS_RATE_LIMIT_EXCEEDED` (header `Retry-After: 1`, sem `X-RateLimit-*`). Ver [Prioridades e rate limit](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md)                       |
| 503    | Indisponibilidade momentânea; nada foi registrado — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`). Repita com o mesmo corpo e a mesma `Idempotency-Key`                                                                                                  |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                                                |

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

Esses são os erros da **requisição**. O desfecho da operação chega depois, no `error.code` do polling e do webhook — ver [`error.code` de operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-operacao) e [Códigos da Caixa](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-caixa). No cancelamento, a recusa pode vir da revisão manual (`GUARANTEE_APPROVAL_REJECTED`), da validação da garantia (`GUARANTEE_NOT_FOUND`, `GUARANTEE_NOT_GATEABLE`, `GUARANTEE_ALREADY_CANCELLED`) ou da Caixa (`CANCELLATION_DENIED`, `ENDORSEMENT_DENIED`, `PROVIDER_ERROR` com os códigos crus `27` — reserva já cancelada — e `28`).

## Submete cancelamento de reserva FGTS

> Admite uma operação de cancelamento de reserva FGTS de forma assíncrona com prioridade \`NORMAL\`. O resultado é entregue via webhook cadastrado ou via polling em \`GET /api/v1/fgts/operations/{requestId}\`.\
> Quando concluída com sucesso, o \`result\` do polling conterá um \`ProtocolResult\` como comprovante do cancelamento.\
> \*\*Estado intermediário:\*\* o dispatcher pode reter a desaverbação aguardando aprovação manual antes de enviá-la à Caixa. Nesse caso, o polling retornará \`status: PENDING\_MANUAL\_APPROVAL\` (não terminal) e o serviço \`fgts-webhook\` emitirá o evento \`CANCEL\_RESERVE\_UNDER\_REVIEW\` — seguido de um evento terminal (\`CANCEL\_RESERVE\_COMPLETED\` ou \`CANCEL\_RESERVE\_FAILED\`) após a decisão manual.\
> O header \`Idempotency-Key\` é aceito para deduplicação de negócio.

```json
{"openapi":"3.0.3","info":{"title":"gtfgts-ingress Public API","version":"0.0.1"},"tags":[{"name":"fgts-operations","description":"Submissão assíncrona de operações FGTS (balance-queries, endorsements, guarantee-maintenances, reserve-cancellations, reserve-value-queries, reserve-protocol-queries, protocol-status-queries), polling de status por `requestId` e cancelamento síncrono de operação. Todas protegidas por JWT do originator."}],"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/reserve-cancellations":{"post":{"operationId":"submitReserveCancellation","tags":["fgts-operations"],"summary":"Submete cancelamento de reserva FGTS","description":"Admite uma operação de cancelamento de reserva FGTS de forma assíncrona com prioridade `NORMAL`. O resultado é entregue via webhook cadastrado ou via polling em `GET /api/v1/fgts/operations/{requestId}`.\nQuando concluída com sucesso, o `result` do polling conterá um `ProtocolResult` como comprovante do cancelamento.\n**Estado intermediário:** o dispatcher pode reter a desaverbação aguardando aprovação manual antes de enviá-la à Caixa. Nesse caso, o polling retornará `status: PENDING_MANUAL_APPROVAL` (não terminal) e o serviço `fgts-webhook` emitirá o evento `CANCEL_RESERVE_UNDER_REVIEW` — seguido de um evento terminal (`CANCEL_RESERVE_COMPLETED` ou `CANCEL_RESERVE_FAILED`) após a decisão manual.\nO header `Idempotency-Key` é aceito para deduplicação de negócio.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Chave de idempotência de negócio. Reenviar a mesma chave retorna o `requestId` existente sem reprocessar.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Corpo da requisição para cancelamento de reserva FGTS (`/reserve-cancellations`). Estende os campos comuns de reserva com metadados obrigatórios de cancelamento para auditoria e revisão manual. Os campos `cancellationType` e `reason` **não alteram** as chamadas à Caixa; servem exclusivamente para rastreabilidade interna. Exatamente um dos campos `reserveIdentifier` ou `contractNumber` deve ser informado — a garantia é resolvida por qualquer um dos dois.","required":["cpf","cancellationType"],"properties":{"cpf":{"type":"string","pattern":"^\\d{11}$","minLength":11,"maxLength":11,"description":"CPF do trabalhador — 11 dígitos numéricos sem pontuação. Campo PII. Formato e dígitos verificadores (mód-11) validados na entrada; sequências de dígitos repetidos são rejeitadas com `400`."},"reserveIdentifier":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,50}$","description":"Identificador da reserva FGTS a cancelar. Exatamente um dos dois — `reserveIdentifier` ou `contractNumber` — deve ser informado."},"contractNumber":{"type":"string","pattern":"^\\d{1,8}$","description":"Número do contrato cuja garantia mais recente será cancelada, quando `reserveIdentifier` não está disponível para o originador. Exatamente um dos dois — `reserveIdentifier` ou `contractNumber` — deve ser informado."},"cancellationType":{"type":"string","description":"Motivo estruturado do cancelamento. Obrigatório para auditoria. Serializado como string (nome do enum).","enum":["SEVEN_DAYS_REGRET","SETTLEMENT_DISCHARGE","OPERATIONAL_ERROR","FRAUD_PREVENTION","BANK_REJECTION","JUDICIAL_ORDER","OTHER"]},"reason":{"type":"string","maxLength":2000,"description":"Justificativa livre opcional para o cancelamento (máx. 2 000 caracteres). Complementa o `cancellationType` com contexto adicional."},"originatorNote":{"type":"string","maxLength":500,"description":"Observação livre do originador (máx. 500 caracteres). Opcional — armazenada no ledger de garantias para consulta de operadores de suporte e financeiro durante revisão manual. Não afeta o processamento pela Caixa."}}}}}},"responses":{"202":{"description":"Cancelamento de reserva admitido para processamento assíncrono. Quando concluído, o `result` do polling conterá um `ProtocolResult`.","content":{"application/json":{"schema":{"type":"object","description":"Confirmação de admissão assíncrona da operação FGTS (`202 Accepted`). O processamento ocorre em background; acompanhe pelo `requestId` via polling (`GET /api/v1/fgts/operations/{requestId}`) ou pelo webhook cadastrado.\n**Exceção para `balance-queries`:** quando o saldo já está disponível, a resposta é `200 OK` com `status: COMPLETED`, `source: CAIXA_CALL` e `result` com o saldo — não é necessário polling, e o webhook é enviado também. Caso contrário, retorna `202`.","required":["requestId","status"],"properties":{"requestId":{"type":"string","format":"uuid","description":"Identificador único (UUID) gerado pelo serviço para esta chamada. Em resposta `202` a requisição foi admitida no processamento assíncrono e este é o identificador de polling: use-o em `GET /api/v1/fgts/operations/{requestId}`. Em resposta `200` de `balance-queries` o resultado já vem inline em `result`, e a operação também é admitida com este `requestId`: é o mesmo do webhook e é consultável em `GET /api/v1/fgts/operations/{requestId}`. Só é preciso fazer polling quando o `status` for `QUEUED`."},"status":{"type":"string","enum":["QUEUED","COMPLETED"],"description":"Status da operação no momento da admissão. `QUEUED`: operação enfileirada para processamento assíncrono (resposta `202`). `COMPLETED`: resultado disponível inline no campo `result` — ocorre apenas quando o saldo de `balance-queries` já está disponível (resposta `200`)."},"source":{"type":"string","nullable":true,"enum":["CAIXA_CALL"],"description":"Origem do resultado. Presente apenas em resposta `200` de `balance-queries`. `CAIXA_CALL`: saldo apurado na Caixa. Nulo em respostas `202`."},"result":{"nullable":true,"description":"Resultado da operação. Presente apenas em resposta `200` de `balance-queries`. Nulo em respostas `202`.","oneOf":[{"type":"object","description":"Resultado de consulta de saldo (`BALANCE_QUERY`) com saldo disponível — saldo FGTS do trabalhador, com a lista de períodos e valores por competência.","required":["workerCpf","balanceDate"],"properties":{"workerCpf":{"type":"string","description":"CPF do trabalhador (11 dígitos, sem pontuação)."},"balanceDate":{"type":"string","format":"date","description":"Data de referência do saldo consultado (ISO-8601, ex. `2026-05-20`)."},"hasDisregardedBalance":{"type":"boolean","description":"Indica que o trabalhador possui valores de FGTS não considerados no saldo retornado, por não estarem disponíveis para uso como garantia. Pode vir ausente quando a Caixa não informa o campo."},"activeRequestCount":{"type":"integer","description":"Quantidade de pedidos de garantia ativos para o trabalhador na Caixa, considerando todas as instituições — não apenas as reservas deste originador. Reflete o momento da apuração do saldo, não o da requisição: o valor pode estar desatualizado."},"periods":{"type":"array","description":"Lista de períodos com valor disponível para averbação.","items":{"type":"object","description":"Período de competência com valor disponível para averbação.","required":["transferDate","amount"],"properties":{"transferDate":{"type":"string","format":"date","description":"Data de transferência (competência) do período (ISO-8601, ex. `2026-05-01`)."},"amount":{"type":"number","description":"Valor disponível para averbação neste período."}}}}}},{"type":"object","description":"Resultado de consulta de saldo (`BALANCE_QUERY`) sem saldo disponível para averbação.","required":["hasBalance"],"properties":{"hasBalance":{"type":"boolean","description":"Sempre `false` — indica ausência de saldo."}}}]},"reserveIdentifier":{"type":"string","nullable":true,"minLength":13,"maxLength":14,"pattern":"^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$","description":"Identificador determinístico de 13 ou 14 caracteres (`GTD{contractNumber:8}{code:2..3}`) gerado no momento da submissão de averbação — o código do originador tem 2 ou 3 caracteres. Presente apenas em respostas `202` de `POST /endorsements`. Nulo para todos os outros tipos de operação."}}}}}},"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."}}}}}},"429":{"description":"Teto de vazão das submissões FGTS excedido (`INGRESS_RATE_LIMIT_EXCEEDED`) — a requisição foi rejeitada e nenhum `requestId` foi gerado. Aguarde `Retry-After` (1 segundo) e reduza a taxa. Esta resposta não traz os headers de janela. Abaixo do teto e acima da cota, a requisição é admitida com prioridade `DEFERRED` (`202`).","headers":{"Retry-After":{"description":"Segundos até a próxima janela disponível.","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."}}}}}},"500":{"description":"Erro interno inesperado no servidor.","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

Concluído o cancelamento, a Giro.Tech envia ao webhook cadastrado um envelope `{ source, eventType, data }`. Para esta operação o `source` é **`CANCEL_RESERVE`** e os `eventType` possíveis são:

| `eventType`                         | Quando                                                                                                                                | `data`                                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `CANCEL_RESERVE_UNDER_REVIEW`       | cancelamento aceito e em **revisão manual** da Giro (`data.status = UNDER_REVIEW`) — **intermediário**, sempre seguido de um terminal | sem `result` nem `error` — a operação ainda não foi à Caixa                                                           |
| `CANCEL_RESERVE_COMPLETED`          | cancelamento concluído com sucesso                                                                                                    | `result` = `ProtocolResult` (`protocolNumber`, `protocolStatus`, `detail`); `protocolNumber` também no nível superior |
| `CANCEL_RESERVE_FAILED`             | cancelamento negado/com erro, **ou rejeitado na revisão manual**                                                                      | `error` (`OperationError`; `originalErrors[]` quando a Caixa retornou erro)                                           |
| `CANCEL_RESERVE_NEEDS_VERIFICATION` | expirou sem desfecho (`status = EXPIRED`)                                                                                             | sem `result`; `error.code = EXPIRED_TTL` — verifique por polling antes de assumir o desfecho                          |

Nos quatro eventos, `data.contractNumber` acompanha o desfecho quando a reserva pertence a um contrato — inclusive no `CANCEL_RESERVE_UNDER_REVIEW`, que é emitido antes de qualquer chamada à Caixa. Submeter por `reserveIdentifier`, sem informar `contractNumber` no corpo, **não** tira o campo do evento: a plataforma resolve o número a partir da própria garantia.

{% hint style="info" %}
Todo cancelamento de reserva passa por um **gate de revisão manual da Giro** antes do envio à Caixa: ao ser submetido, entra no estado intermediário `PENDING_MANUAL_APPROVAL` e emite o evento `CANCEL_RESERVE_UNDER_REVIEW`. Aprovada na revisão, a operação segue para a fila normal (`QUEUED`) e o desfecho chega em `CANCEL_RESERVE_COMPLETED`; rejeitada, chega em `CANCEL_RESERVE_FAILED` com `error.code = GUARANTEE_APPROVAL_REJECTED` (no polling, `status = FAILED`).
{% endhint %}

### CANCEL\_RESERVE\_UNDER\_REVIEW

Cancelamento de reserva aceito e em **revisão manual** da Giro (`data.status = UNDER_REVIEW`; no polling da operação esse estado aparece como `PENDING_MANUAL_APPROVAL`) — evento **intermediário**, sem `result` nem `error`. Aguarde o terminal subsequente (`CANCEL_RESERVE_COMPLETED` ou `CANCEL_RESERVE_FAILED`).

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_UNDER_REVIEW",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789011",
    "contractNumber": "00000042",
    "reserveIdentifier": "GTD00000042AB",
    "status": "UNDER_REVIEW",
    "source": "NA"
  }
}
```

### CANCEL\_RESERVE\_COMPLETED

Cancelamento de reserva concluído. O `result` é um `ProtocolResult` (mesmo formato da averbação).

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_COMPLETED",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "contractNumber": "00000042",
    "reserveIdentifier": "GTD00000042AB",
    "protocolNumber": "555444333",
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": {
      "protocolNumber": "555444333",
      "protocolStatus": "ENDORSED",
      "detail": { "href": "/fgts/v1/protocolos/555444333", "rel": "self" }
    }
  }
}
```

### CANCEL\_RESERVE\_FAILED

Falha no cancelamento de reserva.

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_FAILED",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789013",
    "reserveIdentifier": "GTD00000042AB",
    "status": "FAILED",
    "source": "CAIXA_CALL",
    "error": {
      "code": "CANCELLATION_DENIED",
      "message": "Cancel reserve denied by Caixa"
    }
  }
}
```

Quando a falha é uma **rejeição na revisão manual** (antes do envio à Caixa), o `error.code` é `GUARANTEE_APPROVAL_REJECTED` e não há `originalErrors[]` — a Caixa não chegou a ser chamada. No webhook, `error.message` traz o motivo informado na revisão; no polling, uma mensagem fixa.

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_FAILED",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789011",
    "reserveIdentifier": "GTD00000042AB",
    "status": "FAILED",
    "source": "NA",
    "error": {
      "code": "GUARANTEE_APPROVAL_REJECTED",
      "message": "Operation rejected in manual approval"
    }
  }
}
```

### CANCEL\_RESERVE\_NEEDS\_VERIFICATION

Cancelamento de reserva **expirado** (`status = EXPIRED`): atingiu o tempo limite interno sem chegar a um desfecho, ainda na fila da Giro. Não há `result`; o `error` traz apenas `code = EXPIRED_TTL`, que marca a expiração e **não** é veredito da Caixa. **Verifique** por polling em [`GET /api/v1/fgts/operations/{requestId}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) antes de assumir qualquer resultado.

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_NEEDS_VERIFICATION",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789014",
    "reserveIdentifier": "GTD00000043CD",
    "status": "EXPIRED",
    "source": "NA",
    "error": {
      "code": "EXPIRED_TTL"
    }
  }
}
```

Catálogo completo de eventos e payloads em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) e [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

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