> 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/revisar-conta-desembolso.md).

# Revisar Conta de Desembolso

Atualiza a **conta de pagamento ao tomador** quando o provedor bancário solicita revisão de desembolso e o pagamento **ainda não foi efetivado**. A nova conta substitui a informada na submissão.

{% hint style="info" %}
Use esta operação quando o contrato estiver em **revisão de desembolso** — sinalizada pelo evento `CONTRACT_PAYMENT_REVISION` em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md). Fora desse estado (sem revisão aberta, conta não-revisável ou prazo expirado) a operação retorna `409`. Também retorna `409` enquanto um ajuste anterior ainda está em curso — consulte `disbursement.phase` na [consulta do contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) antes de reenviar.
{% endhint %}

## Qual conta enviar — `availableActions`

O webhook `CONTRACT_PAYMENT_REVISION` traz `data.availableActions` dizendo **o que o provedor aceita naquele ticket**. O mesmo valor aparece em `revision.availableActions` na [consulta do contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md), útil se o webhook se perdeu.

| `availableActions`         | Causa da falha            | O que enviar                                                                                      |
| -------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
| `["NEW_ACCOUNT"]`          | Dados bancários inválidos | Apenas uma conta ou PIX **diferente** da que falhou. Reenviar a mesma é recusado.                 |
| `["NEW_ACCOUNT", "RETRY"]` | Instabilidade bancária    | A **mesma** conta/PIX da tentativa que falhou (`RETRY`) **ou** uma conta inédita (`NEW_ACCOUNT`). |

Não há campo de ação no corpo: o provedor deduz a intenção pela conta enviada.

{% hint style="warning" %}
**Conta antiga não vale como retentativa.** Em um ticket com `RETRY`, só são aceitas a conta da tentativa que falhou por instabilidade ou uma conta **inédita** naquela operação. Reaproveitar uma conta de revisão anterior — que não seja nenhuma das duas — é recusado com `422`.

Exemplo: a operação foi formalizada com a conta A, revisada para a conta B, e a tentativa com B falhou por instabilidade. Você pode reenviar B ou informar uma conta C. Enviar A de novo é **rejeitado**.
{% endhint %}

O ticket é de **uso único**: aceita a emenda, ele deixa de valer e o provedor dispara a nova transferência automaticamente — o resultado chega por webhook. Se falhar de novo, um **novo** ticket é emitido, com seu próprio `availableActions`. Há um **limite** de tentativas por pagamento, e é você quem decide **quando** retentar: várias retentativas seguidas podem esgotá-lo e encerrar a possibilidade de atuação.

{% hint style="info" %}
`availableActions` **não vem** em tickets abertos antes desta funcionalidade. Ausência significa "não informado" — trate como `["NEW_ACCOUNT"]`, que é como esses tickets sempre se comportaram.
{% endhint %}

### Como testar cada cenário

A conta de desembolso informada na formalização determina qual cenário o provedor devolve. Em homologação, use as [chaves PIX de teste](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/homologacao/chaves-pix-de-teste.md) — a tabela de lá liga cada chave ao erro e, portanto, ao `availableActions` que você vai receber:

| Cenário na tabela de teste                                               | `availableActions` esperado |
| ------------------------------------------------------------------------ | --------------------------- |
| **Instabilidade bancária** (ex.: `c8d3e1f2-7a4b-4c9d-8e6f-1a2b3c4d5e6f`) | `["NEW_ACCOUNT", "RETRY"]`  |
| Demais erros de conta/PIX (ex.: `b6a1e5cc-96c2-488f-b98a-7c9d968f9a11`)  | `["NEW_ACCOUNT"]`           |

Só os cenários de instabilidade admitem `RETRY`. As chaves valem **apenas em homologação**.

## Request

`PUT /api/v1/fgts/contracts/{contractNumber}/disbursement-account`

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

### Corpo

`Content-Type: application/json`. Informe **PIX** ou **conta bancária** (`payoutType` em XOR): preencha apenas os campos do tipo escolhido. Violar a regra → `400`. O contrato e o ticket de revisão são resolvidos internamente — não há campo `ccbNumber` nem `ticket`.

| Campo           | Tipo                    | Obrigatório | Descrição                                                                    |
| --------------- | ----------------------- | ----------- | ---------------------------------------------------------------------------- |
| `payoutType`    | `string` (enum)         | Sim         | `PIX` ou `BANK_ACCOUNT`.                                                     |
| `pixKey`        | `string` (≤140)         | Condicional | Chave PIX (quando `payoutType = PIX`).                                       |
| `pixKeyType`    | `string` (enum)         | Condicional | Tipo da chave: `CPF`, `EMAIL`, `PHONE` ou `EVP` (quando `payoutType = PIX`). |
| `bankCode`      | `string` (`^\d{3}$`)    | Condicional | Código do banco (quando `payoutType = BANK_ACCOUNT`).                        |
| `branch`        | `string` (`^\d{1,5}$`)  | Condicional | Agência (quando `payoutType = BANK_ACCOUNT`).                                |
| `accountNumber` | `string` (`^\d{1,20}$`) | Condicional | Número da conta (quando `payoutType = BANK_ACCOUNT`).                        |
| `accountDigit`  | `string` (`^[0-9Xx]$`)  | Condicional | Dígito verificador da conta (quando `payoutType = BANK_ACCOUNT`).            |
| `accountType`   | `string` (enum)         | Condicional | `CHECKING` ou `SAVINGS` (quando `payoutType = BANK_ACCOUNT`).                |

## Response

* **204 No Content** — conta de desembolso atualizada. Sem corpo.

## Exemplo — PIX

```http
PUT /api/v1/fgts/contracts/00012345/disbursement-account HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "payoutType": "PIX",
  "pixKey": "maria.silva@example.com",
  "pixKeyType": "EMAIL"
}
```

```http
HTTP/1.1 204 No Content
```

## Exemplo — conta bancária

```http
PUT /api/v1/fgts/contracts/00012345/disbursement-account HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "payoutType": "BANK_ACCOUNT",
  "bankCode": "001",
  "branch": "1234",
  "accountNumber": "567890",
  "accountDigit": "1",
  "accountType": "CHECKING"
}
```

```http
HTTP/1.1 204 No Content
```

## Erros

| Código | Situação                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Validação de payload (violação da regra XOR de `payoutType`, formato inválido, etc.) — `errorCode = VALIDATION_ERROR`. Na regra XOR (PIX **ou** conta bancária) e no formato da `pixKey`, o `errors` hoje vem vazio; a causa está em `detail`                                                                                                                                                             |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                                                                                                                                                                          |
| 404    | Contrato inexistente ou fora do escopo do token — `errorCode = CONTRACT_NOT_FOUND`                                                                                                                                                                                                                                                                                                                        |
| 409    | Sem revisão de desembolso aberta, conta não-revisável ou prazo de revisão expirado — `errorCode = CONTRACT_NOT_IN_REVISION`                                                                                                                                                                                                                                                                               |
| 409    | Já existe um ajuste de conta em curso, ou uma tentativa anterior terminou sem resposta definitiva do provedor — `errorCode = ACCOUNT_AMENDMENT_IN_FLIGHT`. Aguarde `disbursement.phase` sair de `ACCOUNT_AMENDMENT_IN_FLIGHT` na [consulta do contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) e reenvie; se a fase não mudar, acione o suporte |
| 422    | Provedor bancário recusou a nova conta — `errorCode = DISBURSEMENT_ACCOUNT_REJECTED`. Inclui a mesma conta num ticket sem `RETRY` e o reaproveitamento de conta antiga (ver acima)                                                                                                                                                                                                                        |
| 429    | Rate limit excedido (30 req/min por originator) — `errorCode = RATE_LIMIT_EXCEEDED` (headers `Retry-After`, `X-RateLimit-*`)                                                                                                                                                                                                                                                                              |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                                                                                                                                                                    |
| 503    | Serviço temporariamente indisponível — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`)                                                                                                                                                                                                                                                                                         |
| 415    | Content-Type da requisição não é `application/json` — resposta padrão do framework, **sem** `errorCode`                                                                                                                                                                                                                                                                                                   |

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

## Revisa a conta de desembolso de um contrato (REVISAO\_DESEMBOLSO)

> Reenvia a conta de desembolso (PIX ou conta bancária) de um contrato quando o provedor (gtbanker) solicitou uma revisão de pagamento (\`REVISAO\_DESEMBOLSO\`) e o pagamento ainda não foi efetivado. O corpo carrega exatamente um bloco (PIX \*\*XOR\*\* conta), validado na borda. O ingress resolve o originador pelo token e repassa ao formalizer, que aplica o guard de revisabilidade e aciona o amend no gtbanker.\
> \*\*Qual conta enviar:\*\* o webhook \`CONTRACT\_PAYMENT\_REVISION\` traz \`availableActions\` (também disponível em \`revision.availableActions\` no \`GET\` do contrato). Com \`\["NEW\_ACCOUNT"]\` — falha de dados bancários — só uma conta/PIX \*\*diferente\*\* da que falhou é aceita. Com \`\["NEW\_ACCOUNT","RETRY"]\` — instabilidade bancária — reenviar a \*\*mesma\*\* conta da tentativa que falhou também é aceito. Reaproveitar uma conta de revisão anterior que não seja nem a da instabilidade nem uma inédita é recusado pelo provedor (\`422\`). O ticket é de \*\*uso único\*\*: aceita a emenda, ele deixa de existir e o provedor dispara a nova transferência automaticamente.\
> \*\*Escopo por originador:\*\* um \`contractNumber\` fora do escopo do token resolve para \`404\` (não há \`403\` cross-originator). \*\*Estado (\`409\`):\*\* \`CONTRACT\_NOT\_IN\_REVISION\` — contrato não está aguardando revisão de conta (sem ticket aberto, ticket vencido, ou status diferente de \`PENDING\_DISBURSEMENT\`); \`ACCOUNT\_AMENDMENT\_IN\_FLIGHT\` — já existe um ajuste de conta em curso, ou uma tentativa anterior terminou sem resposta definitiva do provedor; aguarde e consulte \`disbursement.phase\` no \`GET\` do contrato antes de reenviar. \*\*Recusa do provedor:\*\* se o gtbanker recusar a nova conta → \`422\`.

```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}/disbursement-account":{"put":{"operationId":"updateDisbursementAccount","tags":["fgts-contracts"],"summary":"Revisa a conta de desembolso de um contrato (REVISAO_DESEMBOLSO)","description":"Reenvia a conta de desembolso (PIX ou conta bancária) de um contrato quando o provedor (gtbanker) solicitou uma revisão de pagamento (`REVISAO_DESEMBOLSO`) e o pagamento ainda não foi efetivado. O corpo carrega exatamente um bloco (PIX **XOR** conta), validado na borda. O ingress resolve o originador pelo token e repassa ao formalizer, que aplica o guard de revisabilidade e aciona o amend no gtbanker.\n**Qual conta enviar:** o webhook `CONTRACT_PAYMENT_REVISION` traz `availableActions` (também disponível em `revision.availableActions` no `GET` do contrato). Com `[\"NEW_ACCOUNT\"]` — falha de dados bancários — só uma conta/PIX **diferente** da que falhou é aceita. Com `[\"NEW_ACCOUNT\",\"RETRY\"]` — instabilidade bancária — reenviar a **mesma** conta da tentativa que falhou também é aceito. Reaproveitar uma conta de revisão anterior que não seja nem a da instabilidade nem uma inédita é recusado pelo provedor (`422`). O ticket é de **uso único**: aceita a emenda, ele deixa de existir e o provedor dispara a nova transferência automaticamente.\n**Escopo por originador:** um `contractNumber` fora do escopo do token resolve para `404` (não há `403` cross-originator). **Estado (`409`):** `CONTRACT_NOT_IN_REVISION` — contrato não está aguardando revisão de conta (sem ticket aberto, ticket vencido, ou status diferente de `PENDING_DISBURSEMENT`); `ACCOUNT_AMENDMENT_IN_FLIGHT` — já existe um ajuste de conta em curso, ou uma tentativa anterior terminou sem resposta definitiva do provedor; aguarde e consulte `disbursement.phase` no `GET` do contrato antes de reenviar. **Recusa do provedor:** se o gtbanker recusar a nova conta → `422`.","parameters":[{"name":"contractNumber","in":"path","required":true,"description":"Número do contrato gerado pelo formalizer. Validado na borda contra o padrão `^\\d{1,20}$` para prevenção de path traversal antes do gateway.","schema":{"type":"string","pattern":"^\\d{1,20}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Revisão da conta de desembolso (disbursement-account amendment). Enviado pelo originador quando o gtbanker solicita uma revisão de pagamento (`REVISAO_DESEMBOLSO`), enquanto o pagamento ainda não foi efetivado. **Exatamente um bloco preenchido conforme `payoutType`**: PIX → `pixKey` + `pixKeyType`; BANK_ACCOUNT → `bankCode`/`branch`/`accountNumber`/`accountDigit`/`accountType`. A regra XOR é validada no servidor (retorna `400` quando violada); quando `payoutType = PIX`, `pixKey` também deve corresponder ao formato de `pixKeyType`. O contrato é referenciado pelo `contractNumber` no path; não há `ccbNumber`/`ticket` no corpo (o ticket é resolvido internamente pelo formalizer).","required":["payoutType"],"properties":{"payoutType":{"type":"string","enum":["PIX","BANK_ACCOUNT"],"description":"Discriminador da forma de pagamento. `PIX`: usa `pixKey` + `pixKeyType`. `BANK_ACCOUNT`: usa `bankCode`/`branch`/`accountNumber`/`accountDigit`/`accountType`."},"pixKey":{"type":"string","maxLength":140,"description":"Chave PIX (obrigatória quando `payoutType = PIX`). Deve corresponder ao formato de `pixKeyType`: CPF (11 dígitos com dígito verificador válido), CNPJ (14 dígitos com dígito verificador válido), EMAIL (formato de e-mail), PHONE (10 a 13 dígitos, com ou sem o `+` do E.164) ou EVP (UUID)."},"pixKeyType":{"type":"string","enum":["CPF","CNPJ","EMAIL","PHONE","EVP"],"description":"Tipo da chave PIX (obrigatório quando `payoutType = PIX`)."},"bankCode":{"type":"string","pattern":"^\\d{3}$","description":"Código do banco — 3 dígitos (obrigatório quando `payoutType = BANK_ACCOUNT`)."},"branch":{"type":"string","pattern":"^\\d{1,5}$","description":"Agência — 1 a 5 dígitos (obrigatório quando `payoutType = BANK_ACCOUNT`)."},"accountNumber":{"type":"string","pattern":"^\\d{1,20}$","description":"Número da conta — 1 a 20 dígitos (obrigatório quando `payoutType = BANK_ACCOUNT`)."},"accountDigit":{"type":"string","pattern":"^[0-9Xx]$","description":"Dígito verificador da conta — um único dígito ou `X` (obrigatório quando `payoutType = BANK_ACCOUNT`)."},"accountType":{"type":"string","enum":["CHECKING","SAVINGS"],"description":"Tipo de conta (obrigatório quando `payoutType = BANK_ACCOUNT`). `CHECKING`: conta corrente. `SAVINGS`: conta poupança."}}}}}},"responses":{"204":{"description":"Revisão aceita e propagada ao provedor; sem corpo de resposta."},"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."}}}}}},"422":{"description":"Entidade não processável — a nova conta de desembolso foi recusada pelo provedor (gtbanker) durante a revisão. Corrija os dados da conta e reenvie.","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":"Limite de requisições por originator excedido (`RATE_LIMIT_EXCEEDED`) — 30 req/min nas rotas de contrato e 25 req/min no cadastro de webhook. Aguarde `Retry-After` segundos. O corpo traz também `retryAfter`, `limit` e `resetAt`.","headers":{"Retry-After":{"description":"Segundos até a próxima janela disponível.","schema":{"type":"integer","format":"int64"}},"X-RateLimit-Limit":{"description":"Teto máximo de requisições na janela de medição.","schema":{"type":"integer","format":"int32"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela atual.","schema":{"type":"integer","format":"int32"}},"X-RateLimit-Reset":{"description":"Epoch (ms) em que a janela de rate limit reinicia.","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."}}}}}},"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 pedido de revisão chega no evento `CONTRACT_PAYMENT_REVISION` ([Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md)), com `dueAt` (instante exato do prazo) e `availableActions`; o desfecho do pagamento, após a nova conta, é notificado no mesmo webhook (`source = CONTRACT`). Consulte [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/>" %}
