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

# Submeter Contrato

Submete um contrato de empréstimo com garantia FGTS (uma CCB) para formalização. A operação é **síncrona**: a resposta `201` confirma o recebimento e devolve o `contractNumber` gerado pela Giro.Tech. A formalização posterior (averbação na Caixa, envio ao provedor, pagamento) é assíncrona.

O envio do PDF assinado define o modo de entrada: com `signedDocumentBase64` (**Modo A**, `status: RECEIVED`) ou sem ele (**Modo B**, `status: AWAITING_SIGNED_DOCUMENT`, anexar depois via [`POST .../documents`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/enviar-documento-assinado.md)).

{% hint style="info" %}
A resposta `201` confirma apenas que o contrato foi **recebido**. Os marcos de averbação, envio ao provedor e formalização chegam depois via [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) (`source = CONTRACT`) ou por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) do `contractNumber`.
{% endhint %}

## Request

`POST /api/v1/fgts/contracts`

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

### Parâmetros

| Parâmetro         | Local  | Tipo             | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                           |
| ----------------- | ------ | ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | header | `string` (1–100) | **Sim**     | Chave de idempotência de negócio. Ausente ou vazia → `400`. Reenviar a mesma chave com o **mesmo payload** devolve o `201` original sem reprocessar; com **payload diferente** → `409`. Escopo isolado por originador. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md). |

### Corpo

`Content-Type: application/json`. O PDF assinado, quando enviado, trafega como **base64** em campo JSON (não há upload `multipart`).

| Campo                  | Tipo                   | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientReference`      | `string` (≤255)        | Não         | Identificador do cliente no originador, ecoado nas respostas e eventos. **Não** é chave de idempotência nem o `contractNumber`.                                                                                                                                                                                                                                                                                                                               |
| `contractNumber`       | `string` (1–8 dígitos) | Não         | Número da CCB escolhido por você. **Ausente** → a Giro.Tech aloca o próximo número sequencial do seu originador. **Informado** → é normalizado para 8 dígitos com zeros à esquerda (`99` e `00000099` são a **mesma** CCB) e a resposta devolve sempre a forma canônica. Reutilizar um número já usado por você, inclusive um gerado pela Giro.Tech para um contrato seu → `422`. Veja [Número da CCB informado por você](#numero-da-ccb-informado-por-voce). |
| `borrower`             | `object`               | Sim         | Dados do tomador.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `address`              | `object`               | Sim         | Endereço do tomador.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `payout`               | `object`               | Sim         | Dados de pagamento ao tomador (PIX **ou** conta bancária — XOR).                                                                                                                                                                                                                                                                                                                                                                                              |
| `financialTerms`       | `object`               | Sim         | Condições financeiras do contrato (valores em BRL).                                                                                                                                                                                                                                                                                                                                                                                                           |
| `installments`         | `array` (1–120)        | Sim         | Plano de parcelas (cronograma 1:1 com as parcelas do contrato).                                                                                                                                                                                                                                                                                                                                                                                               |
| `signedDocumentBase64` | `string` (base64)      | Não         | PDF assinado da CCB. **Presente → Modo A** (`status: RECEIVED`). **Ausente → Modo B** (`status: AWAITING_SIGNED_DOCUMENT`).                                                                                                                                                                                                                                                                                                                                   |
| `generateDocument`     | `boolean`              | Não         | Escolhe o modo explicitamente, em vez de deixá-lo ser inferido. `true` → Modo B, e `signedDocumentBase64` **não pode** ser enviado. `false` → Modo A, e `signedDocumentBase64` passa a ser **obrigatório**. Omitido → o modo é inferido pela presença do PDF.                                                                                                                                                                                                 |
| `contractInfo`         | `object`               | Não         | Campos complementares usados só na geração do PDF da CCB (Modo B). O bloco inteiro pode ser omitido.                                                                                                                                                                                                                                                                                                                                                          |

#### `borrower`

| Campo       | Tipo                              | Obrigatório | Descrição                                  |
| ----------- | --------------------------------- | ----------- | ------------------------------------------ |
| `cpf`       | `string` (`^\d{11}$`)             | Sim         | CPF do tomador, 11 dígitos sem pontuação.  |
| `name`      | `string` (1–150)                  | Sim         | Nome completo do tomador.                  |
| `birthDate` | `string` (`yyyy-MM-dd`, ISO-8601) | Sim         | Data de nascimento. Deve estar no passado. |
| `email`     | `string` (email, ≤150)            | Não         | E-mail do tomador.                         |
| `phone`     | `string` (`^\d{10,13}$`)          | Não         | Telefone, somente dígitos.                 |

#### `address`

| Campo        | Tipo                    | Obrigatório | Descrição                     |
| ------------ | ----------------------- | ----------- | ----------------------------- |
| `zipCode`    | `string` (`^\d{8}$`)    | Sim         | CEP, 8 dígitos sem pontuação. |
| `street`     | `string` (1–150)        | Sim         | Logradouro.                   |
| `number`     | `string` (1–10)         | Sim         | Número.                       |
| `complement` | `string` (≤100)         | Não         | Complemento.                  |
| `district`   | `string` (1–100)        | Sim         | Bairro.                       |
| `city`       | `string` (1–100)        | Sim         | Cidade.                       |
| `state`      | `string` (`^[A-Z]{2}$`) | Sim         | UF (2 letras maiúsculas).     |

#### `payout`

`payoutType` é **`PIX`** ou **`BANK_ACCOUNT`** (XOR): preencha **apenas** os campos do tipo escolhido. Violar a regra → `400`.

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

#### `financialTerms`

Valores monetários em Reais (BRL), com até 2 casas decimais (precisão `Digits 12,2`). Taxas e CET são percentuais com até 6 casas decimais (precisão `Digits 3,6`; `cetAnnual` aceita 4 dígitos inteiros, `Digits 4,6`).

| Campo                    | Tipo                       | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------ | -------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractAmount`         | `number` (> 0)             | Sim         | **Saldo devedor**: o total que o tomador vai pagar. Igual à soma de `installments[].amount`, e a `financedAmount + totalInterest`. Vira o campo 5 do Quadro I da CCB ("Saldo Devedor Financiamento"). **Não** é o valor emprestado — esse é o `financedAmount`.                                                                                                             |
| `installmentCount`       | `integer` (1–120)          | Sim         | Quantidade de parcelas. Na antecipação do saque-aniversário são os períodos anuais liberados pela Caixa, no máximo 5.                                                                                                                                                                                                                                                       |
| `monthlyInterestRate`    | `number` (≥ 0)             | Sim         | Taxa de juros mensal (%).                                                                                                                                                                                                                                                                                                                                                   |
| `cetMonthly`             | `number` (≥ 0)             | Sim         | Custo efetivo total mensal (%).                                                                                                                                                                                                                                                                                                                                             |
| `cetAnnual`              | `number` (0 – 9999,999999) | Sim         | Custo efetivo total anual (%). O teto é o máximo aceito na emissão da CCB; acima dele, `400` com `errorCode: VALIDATION_ERROR` e `errors["financialTerms.cetAnnual"]`. A [simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/criar-simulacao.md#cet-acima-do-teto) já recusa esse caso com `CET_ABOVE_MAXIMUM`.                          |
| `iofAmount`              | `number` (≥ 0)             | Sim         | Valor do IOF. É **financiado**: está dentro do `financedAmount`, o tomador o amortiza nas parcelas, e sai do desembolso.                                                                                                                                                                                                                                                    |
| `tacAmount`              | `number` (≥ 0)             | Sim         | Valor da TAC. **Não é financiada**: não entra no `financedAmount` e o tomador não a amortiza — é retida no desembolso. Alternativa ao `insuranceAmount`. Imprime no campo 3.2 do Quadro I ("Tarifa de Registro e Pagamento").                                                                                                                                               |
| `disbursementAmount`     | `number` (> 0)             | Sim         | Valor líquido que o tomador recebe — campo 6 do Quadro I ("Valor Líquido do Crédito"). Vale `financedAmount − iofAmount − (tacAmount ou insuranceAmount)`. Você envia o valor já calculado; a Giro.Tech não o deriva nem o recusa se divergir.                                                                                                                              |
| `financedAmount`         | `number` (≥ 0)             | Não¹        | **Valor emprestado** (principal), antes dos juros. Igual à soma de `installments[].principalAmount`. Preenche os campos 1 ("Valor do Empréstimo") e 4 ("Valor Financiado") do Quadro I — os dois carregam o mesmo número — e vai ao GTBanker em `valor_emprestimo` **e** `valor_financiado`.                                                                                |
| `totalInterest`          | `number` (≥ 0)             | Não¹        | Total de juros do contrato. Igual à soma de `installments[].interestAmount`.                                                                                                                                                                                                                                                                                                |
| `firstInstallmentAmount` | `number` (≥ 0)             | Não¹        | Valor da primeira parcela — igual a `installments[0].amount`.                                                                                                                                                                                                                                                                                                               |
| `insuranceAmount`        | `number` (≥ 0)             | Não         | Prêmio de seguro. **Não é financiado**, como a TAC: retido no desembolso, fora da amortização. Alternativa ao `tacAmount` — o contrato carrega um ou o outro. Guardado e **reservado**: o contrato do GTBanker não tem campo de seguro, então ele ainda não é repassado. Quem imprime o campo 16 do Quadro I ("Valor do Prêmio") é o `contractInfo.insurancePremiumAmount`. |
| `contractDate`           | `string` (`yyyy-MM-dd`)    | Sim         | Data de contratação (hoje ou passado).                                                                                                                                                                                                                                                                                                                                      |
| `firstDueDate`           | `string` (`yyyy-MM-dd`)    | Sim         | Vencimento da primeira parcela (futuro). Deve ser **igual** à menor `installments[].dueDate` — divergente, `400` com `errorCode: CONTRACT_FIRST_DUE_DATE_MISMATCH`.                                                                                                                                                                                                         |
| `lastDueDate`            | `string` (`yyyy-MM-dd`)    | Sim         | Vencimento da última parcela (futuro).                                                                                                                                                                                                                                                                                                                                      |

¹ Opcionais no contrato, mas **obrigatórios no Modo B**: sem eles a Giro.Tech não consegue gerar o PDF da CCB.

**Como os valores se relacionam**

**Todos os valores são enviados por você e gravados como vieram** — a Giro.Tech não deriva e não recalcula nenhum deles. Mas as relações abaixo **são conferidas na submissão**, e a divergência é recusada com `400` e `errorCode: VALIDATION_ERROR`: o número que a CCB imprime em "Saldo Devedor Financiamento" precisa fechar com o lastro averbado na Caixa, que é a soma das parcelas. Os números são os do exemplo desta página:

```
contractAmount     = financedAmount + totalInterest          1050,00 = 676,65 + 373,35
contractAmount     = Σ installments[].amount                 1050,00 = 350,00 × 3
financedAmount     = Σ installments[].principalAmount         676,65 = 168,41 + 226,50 + 281,74
totalInterest      = Σ installments[].interestAmount          373,35 = 181,59 + 123,50 + 68,26
iofAmount          = Σ installments[].iofAmount                22,87 = 5,69 + 7,66 + 9,52
disbursementAmount = financedAmount − iofAmount
                     − (tacAmount ou insuranceAmount)         653,78 = 676,65 − 22,87 − 0
```

**`tacAmount` e `insuranceAmount` são alternativos** — o contrato carrega um ou o outro, não os dois, e preencher ambos com valor positivo é recusado. Nas cédulas emitidas hoje o que aparece é o prêmio de seguro, com a TAC zerada.

**Todas as identidades acima recusam a submissão.** Some-se a elas uma regra que decorre da primeira: `financedAmount` **não pode ser igual** a `disbursementAmount` quando houver `iofAmount`, `tacAmount` ou `insuranceAmount` positivo. No FGTS nenhum dos três é financiado, e não financiar significa descontar do desembolso — igualar os dois é o de-para do consignado, onde o IOF é financiado.

`financedAmount` e `totalInterest` são opcionais — se você os omitir, as identidades que dependem deles são puladas, não reprovadas.

A resposta da recusa traz o **valor recebido e o calculado** de cada identidade que não fechou, para você saber qual campo mover.

A tolerância é de **um centavo por parcela** (`0,01 × installmentCount`). Ela existe porque o rateio de centavos entre as parcelas não fecha exato: é normal o `iofAmount` divergir um centavo da soma dos `installments[].iofAmount` num contrato de 3 parcelas.

Os dois campos que mais se confundem são `financedAmount` e `contractAmount`. O primeiro é **quanto o tomador pegou emprestado**; o segundo é **quanto ele vai pagar no total**.

**O IOF e a tarifa saem os dois do desembolso, mas por motivos diferentes.** O IOF é *financiado*: está dentro do `financedAmount`, o tomador o amortiza ao longo das parcelas — é por isso que a soma dos `principalAmount` inclui o IOF — e recebe o líquido já descontado. A **TAC não é financiada**: não faz parte da dívida e o tomador não a amortiza, ela é retida no momento do desembolso. O prêmio de seguro segue a mesma regra da TAC.

#### `installments[]`

Os valores monetários da parcela seguem a mesma precisão de `financialTerms` (BRL, `Digits 12,2`).

| Campo                | Tipo                    | Obrigatório | Descrição                                                                                                                                                                                                                                                                                        |
| -------------------- | ----------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `number`             | `integer` (≥ 1)         | Sim         | Número da parcela.                                                                                                                                                                                                                                                                               |
| `dueDate`            | `string` (`yyyy-MM-dd`) | Sim         | Vencimento (futuro).                                                                                                                                                                                                                                                                             |
| `amount`             | `number` (> 0)          | Sim         | Valor da parcela — é o repasse anual do saque-aniversário que a Caixa faz. Vale `principalAmount + interestAmount`; o IOF **não** entra aqui.                                                                                                                                                    |
| `principalAmount`    | `number` (≥ 0)          | Sim         | Principal amortizado na parcela. A soma de todas dá o `financialTerms.financedAmount`.                                                                                                                                                                                                           |
| `interestAmount`     | `number` (≥ 0)          | Sim         | Juros da parcela. A soma de todas dá o `financialTerms.totalInterest`.                                                                                                                                                                                                                           |
| `iofAmount`          | `number` (≥ 0)          | Sim         | Rateio do IOF na parcela — informativo, já embutido no `principalAmount` e **não** somado ao `amount`. A soma de todas dá o `financialTerms.iofAmount`.                                                                                                                                          |
| `outstandingBalance` | `number` (≥ 0)          | Sim         | Saldo de principal após a parcela. Desce de `financedAmount` até zero na última.                                                                                                                                                                                                                 |
| `daysToCompensate`   | `integer` (0–3660)      | Sim         | Dias corridos entre `contractDate` e o `dueDate` da parcela. Obrigatório — alimenta `dias_compensar` no GTBanker. **Não trunque em 365**: o limite de 365 dias vale só para o IOF diário, que já vem calculado em `iofAmount`. Ex.: contrato em 2026-08-24 com vencimento em 2027-09-28 = `400`. |
| `tariffAmount`       | `number` (0–999999,99)  | Não         | Tarifa cobrada na parcela.                                                                                                                                                                                                                                                                       |
| `documentNumber`     | `string` (máx. 10)      | Não         | Número identificador do vencimento.                                                                                                                                                                                                                                                              |
| `ourNumber`          | `string` (máx. 32)      | Não         | Nosso número do documento no banco.                                                                                                                                                                                                                                                              |
| `ourNumberBankCode`  | `string` (máx. 3)       | Não         | Código do banco do nosso número.                                                                                                                                                                                                                                                                 |
| `participantControl` | `string` (máx. 25)      | Não         | Controle do participante.                                                                                                                                                                                                                                                                        |

#### `contractInfo`

Todos opcionais, e nenhum deles é enviado ao GTBanker: servem apenas para preencher quadros da CCB gerada no Modo B. Omitir o bloco todo é válido — os campos correspondentes saem em branco no documento.

| Campo                      | Tipo                  | Descrição                                                                                                                  |
| -------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `attendantName`            | `string`              | Nome do atendente que originou a operação.                                                                                 |
| `attendantCpf`             | `string` (11 dígitos) | CPF do atendente.                                                                                                          |
| `penaltyFee`               | `number`              | Multa (%) sobre o saldo devedor — campo 19 do Quadro IV.                                                                   |
| `remuneratoryInterestRate` | `number`              | Juros remuneratórios (% ao mês) sobre o valor inadimplido — campo 20 do Quadro IV.                                         |
| `guarantees`               | `string`              | Texto livre das garantias — Quadro V.                                                                                      |
| `bankFee`                  | `number`              | Tarifa bancária — campo 3 do Quadro I.                                                                                     |
| `insurancePolicyNumber`    | `string`              | Número da apólice — campo 14 do Quadro I ("Seguro Número").                                                                |
| `insurerName`              | `string`              | Razão social da seguradora — campo 15.                                                                                     |
| `insurancePremiumAmount`   | `number`              | Valor do prêmio — campo 16 ("Valor do Prêmio"). É este campo, e não o `financialTerms.insuranceAmount`, que a CCB imprime. |
| `documentObservation`      | `string`              | Observação livre impressa no documento.                                                                                    |

Os cinco últimos campos de `installments[]` são **opcionais e de repasse**: a Giro não os interpreta nem os valida além do tamanho — cada um é encaminhado ao GTBanker exatamente como você enviou, respectivamente em `valor_tarifa_parcela`, `numero_documento`, `nosso_numero`, `banco_nosso_numero` e `participante_controle`. Campo omitido **não** é enviado (não vai como nulo nem como vazio), e a parcela é formalizada sem ele. Use-os quando o seu backoffice precisa reconciliar a parcela com o documento bancário correspondente.

## Response

| Campo             | Tipo                | Descrição                                                                                                                                                                                                                       |
| ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractNumber`  | `string`            | Identificador do contrato, sempre com 8 dígitos (ex.: `"00012345"`). É o número que você informou (normalizado) ou, se você não informou, o próximo da sequência do seu originador. **Use este valor** nas consultas seguintes. |
| `status`          | `string`            | `RECEIVED` (Modo A) ou `AWAITING_SIGNED_DOCUMENT` (Modo B).                                                                                                                                                                     |
| `clientReference` | `string` (nullable) | Eco do `clientReference` enviado, ou `null`.                                                                                                                                                                                    |

* **201 Created** — contrato recebido para formalização.

## Exemplo — Modo A (PDF assinado junto)

```http
POST /api/v1/fgts/contracts HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "clientReference": "CLI-2024-00042",
  "borrower": {
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "birthDate": "1985-03-12",
    "email": "maria.silva@example.com",
    "phone": "11987654321"
  },
  "address": {
    "zipCode": "01310200",
    "street": "Avenida Paulista",
    "number": "1578",
    "complement": "Conjunto 102",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  },
  "payout": {
    "payoutType": "PIX",
    "pixKey": "12345678901",
    "pixKeyType": "CPF"
  },
  "financialTerms": {
    "contractAmount": 1050.00,
    "installmentCount": 3,
    "monthlyInterestRate": 1.799000,
    "cetMonthly": 1.970000,
    "cetAnnual": 26.440000,
    "iofAmount": 22.87,
    "tacAmount": 0.00,
    "insuranceAmount": 0.00,
    "disbursementAmount": 653.78,
    "financedAmount": 676.65,
    "totalInterest": 373.35,
    "firstInstallmentAmount": 350.00,
    "contractDate": "2026-08-24",
    "firstDueDate": "2027-09-28",
    "lastDueDate": "2029-09-28"
  },
  "installments": [
    {
      "number": 1,
      "dueDate": "2027-09-28",
      "amount": 350.00,
      "principalAmount": 168.41,
      "interestAmount": 181.59,
      "iofAmount": 5.69,
      "outstandingBalance": 508.24,
      "daysToCompensate": 400,
      "documentNumber": "0000009901",
      "ourNumber": "12345678901234567890",
      "ourNumberBankCode": "341",
      "participantControl": "112233456789218"
    },
    {
      "number": 2,
      "dueDate": "2028-09-28",
      "amount": 350.00,
      "principalAmount": 226.50,
      "interestAmount": 123.50,
      "iofAmount": 7.66,
      "outstandingBalance": 281.74,
      "daysToCompensate": 766
    },
    {
      "number": 3,
      "dueDate": "2029-09-28",
      "amount": 350.00,
      "principalAmount": 281.74,
      "interestAmount": 68.26,
      "iofAmount": 9.52,
      "outstandingBalance": 0.00,
      "daysToCompensate": 1131
    }
  ],
  "signedDocumentBase64": "JVBERi0xLjQKJ..."
}
```

O campo `signedDocumentBase64` contém o **PDF assinado da CCB** codificado em base64 (valor encurtado no exemplo).

```json
{
  "contractNumber": "00012345",
  "status": "RECEIVED",
  "clientReference": "CLI-2024-00042"
}
```

## Exemplo — Modo B (PDF enviado depois)

Mesmo corpo, **sem** `signedDocumentBase64`:

```http
POST /api/v1/fgts/contracts HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

{
  "clientReference": "CLI-2024-00042",
  "borrower": {
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "birthDate": "1985-03-12",
    "email": "maria.silva@example.com",
    "phone": "11987654321"
  },
  "address": {
    "zipCode": "01310200",
    "street": "Avenida Paulista",
    "number": "1578",
    "complement": "Conjunto 102",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  },
  "payout": {
    "payoutType": "PIX",
    "pixKey": "12345678901",
    "pixKeyType": "CPF"
  },
  "financialTerms": {
    "contractAmount": 1050.00,
    "installmentCount": 3,
    "monthlyInterestRate": 1.799000,
    "cetMonthly": 1.970000,
    "cetAnnual": 26.440000,
    "iofAmount": 22.87,
    "tacAmount": 0.00,
    "insuranceAmount": 0.00,
    "disbursementAmount": 653.78,
    "financedAmount": 676.65,
    "totalInterest": 373.35,
    "firstInstallmentAmount": 350.00,
    "contractDate": "2026-08-24",
    "firstDueDate": "2027-09-28",
    "lastDueDate": "2029-09-28"
  },
  "installments": [
    {
      "number": 1,
      "dueDate": "2027-09-28",
      "amount": 350.00,
      "principalAmount": 168.41,
      "interestAmount": 181.59,
      "iofAmount": 5.69,
      "outstandingBalance": 508.24,
      "daysToCompensate": 400
    },
    {
      "number": 2,
      "dueDate": "2028-09-28",
      "amount": 350.00,
      "principalAmount": 226.50,
      "interestAmount": 123.50,
      "iofAmount": 7.66,
      "outstandingBalance": 281.74,
      "daysToCompensate": 766
    },
    {
      "number": 3,
      "dueDate": "2029-09-28",
      "amount": 350.00,
      "principalAmount": 281.74,
      "interestAmount": 68.26,
      "iofAmount": 9.52,
      "outstandingBalance": 0.00,
      "daysToCompensate": 1131
    }
  ]
}
```

```json
{
  "contractNumber": "00012346",
  "status": "AWAITING_SIGNED_DOCUMENT",
  "clientReference": "CLI-2024-00042"
}
```

No Modo B, anexe o documento assinado em seguida via [Enviar documento assinado](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/enviar-documento-assinado.md).

## Próximo passo

* **Modo A**: acompanhe a formalização por [Consultar contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) ou pelo [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).
* **Modo B**: envie o PDF assinado em [Enviar documento assinado](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/enviar-documento-assinado.md) e depois acompanhe a formalização.

## Número da CCB informado por você

O `contractNumber` é opcional. Escolha uma das duas formas e mantenha a mesma em todas as submissões:

* **Sempre informar** — você controla a numeração. Use apenas dígitos, de 1 a 8.
* **Nunca informar** — a Giro.Tech gera o próximo número da sua sequência.

Misturar as duas formas pode falhar. Quando o campo falta, a Giro.Tech gera o próximo número da sequência e pula os que você já usou. Depois de **5 números seguidos já usados**, ela desiste e responde `422` com `errorCode = CONTRACT_NUMBER_ALLOCATION_EXHAUSTED`. Isso acontece quando você informa números logo à frente da sequência em algumas submissões e omite o campo em outras.

Os números que a Giro.Tech já gerou para os seus contratos também contam como usados. Se você já submeteu contratos sem `contractNumber` e vai passar a informá-lo, comece acima do maior número que recebeu.

## Erros

| Código | Situação                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Validação de payload (campo obrigatório ausente, formato inválido, violação da regra XOR de `payout`, `Idempotency-Key` ausente/vazia, etc.) — `errorCode = VALIDATION_ERROR`. Inclui o PDF em `signedDocumentBase64` inválido (Base64 inválido, sem cabeçalho `%PDF-` ou acima de 10 MiB decodificado), com o motivo em `errors.signedDocumentBase64`, e a [coerência de valores](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#validation-error), com as chaves na raiz de `errors` |
| 400    | `generateDocument=false` sem `signedDocumentBase64` — `errorCode = CONTRACT_DOCUMENT_REQUIRED`                                                                                                                                                                                                                                                                                                                                                                                                           |
| 400    | `generateDocument=true` com `signedDocumentBase64` preenchido — `errorCode = CONTRACT_DOCUMENT_UNEXPECTED`                                                                                                                                                                                                                                                                                                                                                                                               |
| 400    | `financialTerms.firstDueDate` diferente da primeira parcela — `errorCode = CONTRACT_FIRST_DUE_DATE_MISMATCH`                                                                                                                                                                                                                                                                                                                                                                                             |
| 400    | `installmentCount` diferente do número de parcelas em `installments[]` — `errorCode = CONTRACT_INSTALLMENTS_MISMATCH`                                                                                                                                                                                                                                                                                                                                                                                    |
| 400    | CCB recusada na validação prévia junto ao banco emissor — `errorCode = CCB_VALIDATION_FAILED`, com o objeto `errors` indicando campo a campo o motivo da recusa. Nenhum contrato é criado.                                                                                                                                                                                                                                                                                                               |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 409    | `Idempotency-Key` reutilizada com payload divergente — `errorCode = CONTRACT_IDEMPOTENCY_CONFLICT`                                                                                                                                                                                                                                                                                                                                                                                                       |
| 422    | `clientReference` já usado por outro contrato seu — `errorCode = CONTRACT_CLIENT_REFERENCE_ALREADY_EXISTS`; `errors.clientReference` informa qual                                                                                                                                                                                                                                                                                                                                                        |
| 422    | `contractNumber` informado já usado por você — `errorCode = CONTRACT_NUMBER_ALREADY_EXISTS`                                                                                                                                                                                                                                                                                                                                                                                                              |
| 422    | `contractNumber` ausente e a Giro.Tech não encontrou número livre na sua sequência — `errorCode = CONTRACT_NUMBER_ALLOCATION_EXHAUSTED`. Veja [Número da CCB informado por você](#numero-da-ccb-informado-por-voce).                                                                                                                                                                                                                                                                                     |
| 422    | Originator ainda não configurado para formalizar — `errorCode = FORMALIZATION_CONFIG_NOT_PROVISIONED`, `FORMALIZATION_CONFIG_INCOMPLETE` ou `GTBANKER_CREDENTIAL_NOT_FOUND`. Acione a Giro                                                                                                                                                                                                                                                                                                               |
| 4xx    | O serviço de formalização recusou a requisição — o `errorCode` dele é repassado, ou `CONTRACT_REQUEST_REJECTED` quando não há código próprio. Ver [Erros de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#formalizacao)                                                                                                                                                                                                                                                 |
| 415    | Content-Type da requisição não é `application/json` — resposta padrão do framework, **sem** `errorCode`                                                                                                                                                                                                                                                                                                                                                                                                  |
| 429    | Rate limit excedido (30 req/min por originator) — `errorCode = RATE_LIMIT_EXCEEDED` (headers `Retry-After`, `X-RateLimit-*`)                                                                                                                                                                                                                                                                                                                                                                             |
| 503    | Serviço de formalização temporariamente indisponível — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`)                                                                                                                                                                                                                                                                                                                                                                        |
| 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).

## Submete um contrato de formalização FGTS

> Admite um contrato de formalização FGTS. A requisição é \`application/json\` (\`CreateContractRequest\`). O PDF assinado da CCB, quando enviado junto, vai no campo \`signedDocumentBase64\` (base64) — não há upload \`multipart\`.\
> \*\*Dois modos de submissão:\*\*\
> 1\. \*\*Com documento (Modo A):\*\* \`signedDocumentBase64\` presente →\
> &#x20;  o formalizer atribui \`status: RECEIVED\`.\
> 2\. \*\*Sem documento (Modo B):\*\* \`signedDocumentBase64\` ausente →\
> &#x20;  \`status: AWAITING\_SIGNED\_DOCUMENT\`. O PDF assinado é enviado depois via\
> &#x20;  \`POST /api/v1/fgts/contracts/{contractNumber}/documents\`.\
> \
> O ingress não gera o \`contractNumber\` nem toca no S3 (D16): repassa o corpo ao formalizer e devolve o \`201 { contractNumber, status, clientReference }\`.\
> \*\*Idempotência:\*\* o header \`Idempotency-Key\` é \*\*obrigatório\*\*. Reenviar a mesma chave retorna o resultado existente sem reprocessar (escopo isolado por originator).\
> \*\*\`contractNumber\`:\*\* repete entre originadores diferentes; o acesso é sempre escopado pelo token do originador. Por isso não há \`403\` cross-originator — um número fora do escopo do token resolve para \`404\` nas consultas.

````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":{"post":{"operationId":"submitContract","tags":["fgts-contracts"],"summary":"Submete um contrato de formalização FGTS","description":"Admite um contrato de formalização FGTS. A requisição é `application/json` (`CreateContractRequest`). O PDF assinado da CCB, quando enviado junto, vai no campo `signedDocumentBase64` (base64) — não há upload `multipart`.\n**Dois modos de submissão:**\n1. **Com documento (Modo A):** `signedDocumentBase64` presente →\n   o formalizer atribui `status: RECEIVED`.\n2. **Sem documento (Modo B):** `signedDocumentBase64` ausente →\n   `status: AWAITING_SIGNED_DOCUMENT`. O PDF assinado é enviado depois via\n   `POST /api/v1/fgts/contracts/{contractNumber}/documents`.\n\nO ingress não gera o `contractNumber` nem toca no S3 (D16): repassa o corpo ao formalizer e devolve o `201 { contractNumber, status, clientReference }`.\n**Idempotência:** o header `Idempotency-Key` é **obrigatório**. Reenviar a mesma chave retorna o resultado existente sem reprocessar (escopo isolado por originator).\n**`contractNumber`:** repete entre originadores diferentes; o acesso é sempre escopado pelo token do originador. Por isso não há `403` cross-originator — um número fora do escopo do token resolve para `404` nas consultas.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Chave de idempotência de negócio (string livre, ex.: UUID do cliente). **Obrigatória.** Escopo isolado por originador — a mesma chave não colide entre originadores diferentes. Requisições com a mesma chave retornam o resultado existente sem reprocessar. Ausente ou em branco → `400`.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Corpo JSON de submissão de contrato (`POST /api/v1/fgts/contracts`). A validação na borda é estrutural (formato/limites), não regras de negócio de precificação — estas são de responsabilidade da Caixa/gtbanker e do formalizer.\n**Estratégia de documento (campo `generateDocument`):**\n- `generateDocument: true` → **Mode B (GENERATE)**: o satellite gera o template PDF\n  da CCB automaticamente. `signedDocumentBase64` **não deve** ser enviado (`400`\n  `CONTRACT_DOCUMENT_UNEXPECTED` se presente).\n- `generateDocument: false` → **Mode A (PROVIDED)**: o originador envia o PDF assinado\n  em `signedDocumentBase64` (**obrigatório**; `400` `CONTRACT_DOCUMENT_REQUIRED` se ausente).\n- `generateDocument` ausente (null) → **inferido** pela presença de\n  `signedDocumentBase64`: presente → Mode A (PROVIDED); ausente → Mode B (GENERATE).\n\nO `clientReference` é o identificador do cliente no originador (opcional) e é ecoado de volta nas respostas para correlação/exibição — **não** é a chave de deduplicação (essa é o header `Idempotency-Key`) nem o `contractNumber` (gerado pelo formalizer). É, porém, **único por originador**: reenviá-lo devolve `422` `CONTRACT_CLIENT_REFERENCE_ALREADY_EXISTS`. Não há `contractId` (eliminado, D16) nem `s3Key` (interno ao formalizer) neste corpo.","required":["borrower","address","payout","financialTerms","installments"],"properties":{"clientReference":{"type":"string","maxLength":255,"description":"Identificador do cliente no originador (opcional). Ecoado nas respostas para correlação/exibição. Não é a chave de idempotência nem o `contractNumber`, mas é **único por originador**: identifica uma CCB e só uma. Reutilizar um valor já usado pelo mesmo originador devolve `422` com `errorCode: CONTRACT_CLIENT_REFERENCE_ALREADY_EXISTS`, trazendo em `errors.clientReference` o `contractNumber` que já o ocupa. Omitido, não há restrição."},"contractNumber":{"type":"string","pattern":"^[0-9]{1,8}$","description":"Número da CCB escolhido pelo originador (opcional). Ausente, o formalizer aloca o próximo número do contador do próprio originador. Informado, é normalizado para 8 dígitos com zeros à esquerda — `99` e `00000099` são a MESMA CCB — e a resposta devolve sempre a forma canônica (`00000099`). Reutilizar um número já usado pelo mesmo originador devolve `422` com `errorCode: CONTRACT_NUMBER_ALREADY_EXISTS`. Isso vale também para os números que o contador gerou para contratos já criados do originador.\nInforme sempre ou nunca. Quando o campo falta, o contador pula os números que o originador já ocupou, mas desiste depois de 5 números seguidos ocupados e devolve `422` com `errorCode: CONTRACT_NUMBER_ALLOCATION_EXHAUSTED`. Um originador que informa números à frente do contador em parte das submissões e omite o campo nas outras pode cair nesse caso."},"borrower":{"type":"object","description":"Identificação do mutuário (borrower). O CPF é PII e só é tokenizado/criptografado a jusante. A validação na borda inclui formato e dígito verificador (mesma regra aplicada pela Caixa/gtbanker) — CPF com dígito inválido é rejeitado com `400`.","required":["cpf","name","birthDate"],"properties":{"cpf":{"type":"string","pattern":"^\\d{11}$","minLength":11,"maxLength":11,"description":"CPF do mutuário — 11 dígitos numéricos sem pontuação, com dígito verificador válido (algoritmo módulo 11). Campo PII."},"name":{"type":"string","minLength":1,"maxLength":150,"description":"Nome completo do mutuário."},"birthDate":{"type":"string","format":"date","description":"Data de nascimento em formato ISO-8601 `yyyy-MM-dd`. Deve ser uma data no passado (`@Past`)."},"email":{"type":"string","format":"email","maxLength":150,"description":"E-mail do mutuário (opcional)."},"phone":{"type":"string","pattern":"^\\d{10,13}$","maxLength":20,"description":"Telefone do mutuário (opcional) — 10 a 13 dígitos numéricos sem pontuação."}}},"address":{"type":"object","description":"Endereço do mutuário.","required":["zipCode","street","number","district","city","state"],"properties":{"zipCode":{"type":"string","pattern":"^\\d{8}$","description":"CEP — 8 dígitos numéricos sem pontuação."},"street":{"type":"string","minLength":1,"maxLength":150,"description":"Logradouro."},"number":{"type":"string","minLength":1,"maxLength":10,"description":"Número do endereço."},"complement":{"type":"string","maxLength":100,"description":"Complemento (opcional)."},"district":{"type":"string","minLength":1,"maxLength":100,"description":"Bairro."},"city":{"type":"string","minLength":1,"maxLength":100,"description":"Cidade."},"state":{"type":"string","pattern":"^[A-Z]{2}$","description":"UF — sigla de 2 letras maiúsculas."}}},"payout":{"type":"object","description":"Forma de pagamento (payout) do valor desembolsado. **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 esperado para `pixKeyType` (CPF/CNPJ com dígito verificador válido, e-mail, telefone ou UUID para EVP) — chave incompatível com o tipo é rejeitada com `400`.","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."}}},"financialTerms":{"type":"object","description":"Condições financeiras do contrato. A Giro.Tech **não deriva e não recalcula** nenhum valor: todos são enviados por você e gravados como vieram. Mas as relações abaixo **são conferidas na submissão** e a divergência é recusada com `400 VALIDATION_ERROR` — o número que a CCB imprime em \"Saldo Devedor Financiamento\" precisa fechar com o lastro que vai ser averbado na Caixa, que é a soma das parcelas. Os números são os do exemplo desta página, um contrato real de 3 parcelas anuais do saque-aniversário:\n``` contractAmount     = financedAmount + totalInterest            1050,00 = 676,65 + 373,35 contractAmount     = Σ installments[].amount                   1050,00 = 350,00 x 3 financedAmount     = Σ installments[].principalAmount           676,65 = 168,41 + 226,50 + 281,74 totalInterest      = Σ installments[].interestAmount            373,35 = 181,59 + 123,50 + 68,26 iofAmount          = Σ installments[].iofAmount                  22,87 = 5,69 + 7,66 + 9,52 disbursementAmount = financedAmount - iofAmount\n                     - (tacAmount ou insuranceAmount)            653,78 = 676,65 - 22,87 - 0\n```\n**`tacAmount` e `insuranceAmount` são alternativos** — o contrato carrega um ou o outro, não os dois, e preencher ambos com valor positivo é recusado. Nas cédulas emitidas hoje o que aparece é o prêmio de seguro, com a TAC zerada.\n**Todas as identidades acima recusam a submissão.** Some-se a elas uma regra que decorre da primeira: `financedAmount` **não pode ser igual** a `disbursementAmount` quando houver `iofAmount`, `tacAmount` ou `insuranceAmount` positivo — no FGTS nenhum dos três é financiado, e não financiar significa descontar do desembolso. Igualar os dois é o de-para do consignado, onde o IOF é financiado; foi ele que produziu cédula com \"Valor do Empréstimo\" igual ao saldo devedor.\n`financedAmount` e `totalInterest` são opcionais — omitidos, as identidades que dependem deles são puladas, não reprovadas.\nA mensagem de recusa carrega o **valor recebido e o calculado** para cada identidade que não fechou, para você saber qual campo mover.\nA tolerância é de **um centavo por parcela** (`0,01 × installmentCount`), porque o rateio de centavo entre as parcelas não fecha exato: é normal `iofAmount` divergir 1 centavo da soma de `installments[].iofAmount` num contrato de 3 parcelas.\nOs dois valores que mais se confundem: **`financedAmount` é o que o tomador pegou emprestado** (campos 1 e 4 do Quadro I da CCB, que carregam o mesmo número) e **`contractAmount` é o total que ele vai pagar** (campo 5, \"Saldo Devedor Financiamento\").\n**O IOF e a tarifa saem os dois do desembolso, mas por motivos diferentes.** O IOF é *financiado*: está dentro do `financedAmount`, o tomador o amortiza ao longo das parcelas (é por isso que `Σ principalAmount` inclui o IOF) e recebe o líquido já descontado. A **TAC não é financiada**: não faz parte da dívida e o tomador não a amortiza — é retida no momento do desembolso. O prêmio de seguro segue a mesma regra da TAC.","required":["contractAmount","installmentCount","monthlyInterestRate","cetMonthly","cetAnnual","iofAmount","tacAmount","disbursementAmount","contractDate","firstDueDate","lastDueDate"],"properties":{"contractAmount":{"type":"number","format":"double","minimum":0,"exclusiveMinimum":true,"description":"**Saldo devedor** — total que o tomador vai pagar, em Reais (BRL). É a soma de `installments[].amount` e equivale a `financedAmount + totalInterest`. Corresponde ao campo 5 do Quadro I da CCB (\"Saldo Devedor Financiamento\"). **Não** é o valor emprestado — esse é o `financedAmount`. Deve ser positivo. Precisão `Digits 12,2`."},"installmentCount":{"type":"integer","format":"int32","minimum":1,"maximum":120,"description":"Quantidade de parcelas. Entre 1 e 120 inclusive."},"monthlyInterestRate":{"type":"number","format":"double","minimum":0,"description":"Taxa de juros mensal (%). Deve ser positivo ou zero. Precisão `Digits 3,6`."},"cetMonthly":{"type":"number","format":"double","minimum":0,"description":"CET mensal (%). Deve ser positivo ou zero. Precisão `Digits 3,6`."},"cetAnnual":{"type":"number","format":"double","minimum":0,"maximum":9999.999999,"description":"CET anual (%). Deve ser positivo ou zero. Precisão `Digits 4,6` (até 9999.999999)."},"iofAmount":{"type":"number","format":"double","minimum":0,"description":"Valor do IOF em Reais (BRL). É **financiado**: está dentro do `financedAmount`, entra na amortização das parcelas e é descontado do `disbursementAmount`. Deve ser positivo ou zero. Precisão `Digits 12,2`."},"tacAmount":{"type":"number","format":"double","minimum":0,"description":"Valor da TAC em Reais (BRL). **Não é financiada**: não entra no `financedAmount` e o tomador não a amortiza — é retida no desembolso, então sai do `disbursementAmount`. Alternativa ao `insuranceAmount`: o contrato carrega um ou o outro. Vai ao gtbanker em `valor_tarifas` e imprime no campo 3.2 do Quadro I da CCB (\"Tarifa de Registro e Pagamento\"). Deve ser positivo ou zero. Precisão `Digits 12,2`."},"disbursementAmount":{"type":"number","format":"double","minimum":0,"exclusiveMinimum":true,"description":"Valor líquido que o tomador recebe, em Reais (BRL) — campo 6 do Quadro I da CCB (\"Valor Líquido do Crédito\"). Vale `financedAmount - iofAmount - (tacAmount ou insuranceAmount)`. Você envia o valor já calculado; a Giro.Tech não o deriva, mas **recusa** a submissão se ele divergir. Deve ser positivo. Precisão `Digits 12,2`."},"financedAmount":{"type":"number","format":"double","minimum":0,"description":"**Valor emprestado** (principal) em Reais (BRL) — o que o tomador deve, antes dos juros. É a soma de `installments[].principalAmount`. Preenche os campos 1 (\"Valor do Empréstimo\") e 4 (\"Valor Financiado\") do Quadro I da CCB, que carregam o mesmo número, e vai para o gtbanker em `valor_emprestimo` **e** `valor_financiado`. É dele que saem o IOF e a tarifa até chegar ao `disbursementAmount`. Opcional no contrato, mas obrigatório para a geração do PDF (Modo B). Positivo ou zero quando presente. Precisão `Digits 12,2`."},"totalInterest":{"type":"number","format":"double","minimum":0,"description":"Total de juros do contrato em Reais (BRL). É a soma de `installments[].interestAmount` e fecha a identidade `contractAmount = financedAmount + totalInterest`. Opcional no contrato, mas obrigatório para a geração do PDF (Modo B). Positivo ou zero quando presente. Precisão `Digits 12,2`."},"firstInstallmentAmount":{"type":"number","format":"double","minimum":0,"description":"Valor da primeira parcela em Reais (BRL) — igual a `installments[0].amount`. Opcional no contrato, mas obrigatório para a geração do PDF (Modo B). Vai para o gtbanker em `valor_primeira_parcela`. Positivo ou zero quando presente. Precisão `Digits 12,2`."},"insuranceAmount":{"type":"number","format":"double","minimum":0,"description":"Prêmio de seguro em Reais (BRL) (opcional). **Não é financiado**, como a TAC: é retido no desembolso e não entra na amortização. Alternativa ao `tacAmount` — o contrato carrega um ou o outro. Persistido e **reservado**: o contrato do gtbanker não tem campo de seguro hoje, então ele ainda não é repassado. Quem alimenta o campo 16 do Quadro I da CCB (\"Valor do Prêmio\") é `contractInfo.insurancePremiumAmount`. Positivo ou zero quando presente. Precisão `Digits 12,2`."},"contractDate":{"type":"string","format":"date","description":"Data do contrato (ISO-8601 `yyyy-MM-dd`). Não pode ser futura — hoje ou passado (`@PastOrPresent`). Mesma regra aplicada pela Caixa/gtbanker (`data_emprestimo`)."},"firstDueDate":{"type":"string","format":"date","description":"Data do primeiro vencimento (ISO-8601 `yyyy-MM-dd`). Deve ser no futuro (`@Future`), estritamente posterior a `contractDate` (igual a `contractDate` é rejeitado) e **igual à menor `installments[].dueDate`** — mesma regra que o gtbanker aplica na CCB (`data_primeiro_vencimento_parcela` = menor `parcelas[*].data_vencimento`). Divergente → `400` com `errorCode: CONTRACT_FIRST_DUE_DATE_MISMATCH`."},"lastDueDate":{"type":"string","format":"date","description":"Data do último vencimento (ISO-8601 `yyyy-MM-dd`). Deve ser no futuro (`@Future`)."}}},"installments":{"type":"array","minItems":1,"maxItems":120,"items":{"type":"object","description":"Parcela individual do cronograma do contrato (1:1 com `parcelas[]` do gtbanker).","required":["number","dueDate","amount","principalAmount","interestAmount","iofAmount","outstandingBalance","daysToCompensate"],"properties":{"number":{"type":"integer","format":"int32","minimum":1,"description":"Número sequencial da parcela (1-based)."},"dueDate":{"type":"string","format":"date","description":"Data de vencimento da parcela (ISO-8601 `yyyy-MM-dd`). Deve ser no futuro (`@Future`)."},"amount":{"type":"number","format":"double","minimum":0,"exclusiveMinimum":true,"description":"Valor total da parcela em Reais (BRL) — é o repasse anual do saque-aniversário que a Caixa faz. Vale `principalAmount + interestAmount`; o IOF **não** entra aqui (ele já está embutido no principal). Deve ser positivo. Precisão `Digits 12,2`."},"principalAmount":{"type":"number","format":"double","minimum":0,"description":"Valor do principal amortizado na parcela em Reais (BRL). A soma de todas as parcelas é o `financialTerms.financedAmount`. Positivo ou zero. Precisão `Digits 12,2`."},"interestAmount":{"type":"number","format":"double","minimum":0,"description":"Valor dos juros na parcela em Reais (BRL). A soma de todas as parcelas é o `financialTerms.totalInterest`. Positivo ou zero. Precisão `Digits 12,2`."},"iofAmount":{"type":"number","format":"double","minimum":0,"description":"Rateio do IOF na parcela em Reais (BRL) — informativo, já embutido no `principalAmount` e **não** somado ao `amount`. A soma de todas as parcelas é o `financialTerms.iofAmount`. Positivo ou zero. Precisão `Digits 12,2`."},"outstandingBalance":{"type":"number","format":"double","minimum":0,"description":"Saldo de principal após a parcela em Reais (BRL). Desce de `financedAmount` até zero na última parcela. Positivo ou zero. Precisão `Digits 12,2`."},"daysToCompensate":{"type":"integer","format":"int32","minimum":0,"maximum":3660,"description":"Dias corridos entre a data do contrato (`financialTerms.contractDate`) e o vencimento da parcela (obrigatório). Enviado ao GTBanker como `dias_compensar`. Não é truncado em 365: o limite de 365 dias vale só para o IOF diário, já refletido em `iofAmount`. Entre 0 e 3660 inclusive. Ex.: contrato em 2026-08-24 com vencimento em 2027-09-28 = 400."},"tariffAmount":{"type":"number","format":"double","minimum":0,"maximum":999999.99,"description":"Tarifa cobrada na parcela em Reais (BRL), opcional. Enviada ao GTBanker como `valor_tarifa_parcela` somente quando presente."},"documentNumber":{"type":"string","maxLength":10,"description":"Número identificador do vencimento, opcional. Enviado ao GTBanker como `numero_documento` somente quando presente."},"ourNumber":{"type":"string","maxLength":32,"description":"Nosso número do documento no banco, opcional. Enviado ao GTBanker como `nosso_numero` somente quando presente."},"ourNumberBankCode":{"type":"string","maxLength":3,"description":"Código do banco do nosso número, opcional. Enviado ao GTBanker como `banco_nosso_numero` somente quando presente."},"participantControl":{"type":"string","maxLength":25,"description":"Controle do participante, opcional. Enviado ao GTBanker como `participante_controle` somente quando presente."}}},"description":"Cronograma de parcelas do contrato (1:1 com `parcelas[]` do gtbanker). Pelo menos uma parcela é obrigatória; no máximo 120 (limite estrutural da borda)."},"signedDocumentBase64":{"type":"string","format":"byte","description":"PDF assinado da CCB codificado em base64 (opcional quando `generateDocument` é omitido ou `false`; proibido quando `generateDocument: true`). Deve representar um `application/pdf` válido de até 10 MiB decodificado. Base64 inválido, conteúdo sem o cabeçalho `%PDF-` ou acima do limite → `400` `VALIDATION_ERROR`, com o motivo em `errors.signedDocumentBase64`. Ausente com `generateDocument: false` → `400` `CONTRACT_DOCUMENT_REQUIRED`; preenchido com `generateDocument: true` → `400` `CONTRACT_DOCUMENT_UNEXPECTED`."},"generateDocument":{"type":"boolean","description":"Hint explícito de estratégia de documento (opcional). - `true` → Mode B (GENERATE): o satellite gera o template PDF da CCB;\n  `signedDocumentBase64` **não deve** ser enviado.\n- `false` → Mode A (PROVIDED): `signedDocumentBase64` é **obrigatório**. - Ausente (null) → inferido: `signedDocumentBase64` presente → Mode A;\n  ausente → Mode B."},"contractInfo":{"type":"object","description":"Campos complementares do contrato usados para geração do documento CCB (opcional). Todos os campos são opcionais. O bloco inteiro pode ser omitido quando não aplicável.","properties":{"attendantName":{"type":"string","maxLength":150,"description":"Nome do atendente responsável pelo contrato (opcional)."},"attendantCpf":{"type":"string","maxLength":14,"description":"CPF do atendente (opcional). Pode conter pontuação ou só dígitos."},"penaltyFee":{"type":"number","description":"Multa contratual (opcional), em percentual ou valor conforme acordado."},"remuneratoryInterestRate":{"type":"number","description":"Taxa de juros remuneratórios (opcional)."},"guarantees":{"type":"string","maxLength":500,"description":"Descrição de garantias adicionais (opcional). Quando informado, complementa (não substitui) o texto padrão de cessão fiduciária da operação FGTS na CCB."},"bankFee":{"type":"number","description":"Tarifa bancária (opcional), em Reais (BRL)."},"insurancePolicyNumber":{"type":"string","maxLength":50,"description":"Número da apólice de seguro (opcional)."},"insurerName":{"type":"string","maxLength":100,"description":"Nome da seguradora (opcional)."},"insurancePremiumAmount":{"type":"number","description":"Valor do prêmio de seguro em Reais (BRL) (opcional)."},"documentObservation":{"type":"string","maxLength":2048,"description":"Observações adicionais para o documento CCB (opcional)."}}}}}}}},"responses":{"201":{"description":"Contrato admitido. `status: RECEIVED` quando o PDF foi enviado; `AWAITING_SIGNED_DOCUMENT` quando aguarda o upload posterior do documento assinado.","content":{"application/json":{"schema":{"type":"object","description":"Resposta de `POST /api/v1/fgts/contracts` (e `/documents`, `/reprocess`). Repassa a resposta do formalizer. O ingress **não** gera o `contractNumber`; não há `contractId` (D16) nem `s3Key` (interno ao formalizer).","required":["contractNumber","status"],"properties":{"contractNumber":{"type":"string","description":"Número do contrato gerado pelo formalizer, sequencial por originador. O ingress NÃO gera este número."},"status":{"type":"string","enum":["RECEIVED","AWAITING_SIGNED_DOCUMENT"],"description":"Status inicial atribuído pelo formalizer na admissão. `RECEIVED`: contrato recebido (PDF presente). `AWAITING_SIGNED_DOCUMENT`: aguardando upload posterior do documento assinado."},"clientReference":{"type":"string","nullable":true,"maxLength":255,"description":"Identificador do cliente no originador, ecoado da requisiçã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."}}}}}},"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."}}}}}},"415":{"description":"`Content-Type` da requisição diferente de `application/json`. Resposta padrão do framework: `type: about:blank` e **sem** `errorCode` nem `timestamp`.","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."}}}}}},"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

Recebido o contrato, os marcos de formalização chegam ao webhook cadastrado num envelope `{ source, eventType, data }` com `source = CONTRACT`. Consulte o catálogo completo em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) e [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md), e o ciclo de vida em [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).

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