> 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/simulacoes/criar-simulacao.md).

# Criar Simulação

Cria uma simulação de empréstimo consignado FGTS para o originator autenticado. A API calcula o plano de pagamento com base na taxa de juros mensal, na data de contratação e nas parcelas anuais a antecipar.

{% hint style="info" %}
Requisições que violam as regras de produto são recusadas com um `errorCode` que identifica a regra: `INSTALLMENT_AMOUNT_BELOW_MINIMUM`, `INSTALLMENT_AMOUNT_ABOVE_MAXIMUM`, `MAX_INSTALLMENT_YEARS_EXCEEDED` e `INVALID_TRANSFER_DATE` (400); `CET_NOT_CONVERGED` e `CET_ABOVE_MAXIMUM` (422). Veja [Erros](#erros).
{% endhint %}

## Request

`POST /api/v1/simulations`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Corpo

| Campo                    | Tipo                              | Obrigatório | Descrição                                                                                                         |
| ------------------------ | --------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `identification`         | `string` (11 dígitos, `^\d{11}$`) | Sim         | CPF do tomador, 11 dígitos numéricos sem pontuação.                                                               |
| `monthlyInterestRate`    | `number` (double, > 0)            | Sim         | Taxa de juros mensal em percentual (ex.: `1.799` = 1,799% a.m.). Deve ser estritamente positiva (maior que zero). |
| `contractDate`           | `string` (date)                   | Não         | Data de contratação no formato ISO-8601 (`yyyy-MM-dd`). Quando ausente, usa a data atual.                         |
| `periods`                | `array` (1–5 itens)               | Sim         | Parcelas anuais a antecipar. Máximo de 5 parcelas anuais.                                                         |
| `periods[].transferDate` | `string` (date)                   | Sim         | Data de transferência da parcela (ISO-8601 `yyyy-MM-dd`). Deve ser uma data futura.                               |
| `periods[].amount`       | `number` (double, 50–500)         | Sim         | Valor do saque anual em Reais (BRL). Faixa de 50,00 a 500,00 por parcela.                                         |
| `tac`                    | `number` (double, ≥ 0)            | Não         | Tarifa de administração de contrato (TAC) em Reais (BRL). Quando ausente, vale `0,00`.                            |
| `insurance`              | `number` (double, ≥ 0)            | Não         | Prêmio de seguro prestamista em Reais (BRL). Quando ausente, vale `0,00`.                                         |
| `tacFinanced`            | `boolean`                         | Não         | **Descontinuado e ignorado.** Aceito apenas para não quebrar integrações existentes; será removido.               |
| `insuranceFinanced`      | `boolean`                         | Não         | **Descontinuado e ignorado.** Aceito apenas para não quebrar integrações existentes; será removido.               |

{% hint style="info" %}
**Tarifa entra no CET.** `tac` e `insurance` são sempre retidos no desembolso — o tomador não os amortiza, exatamente como em [Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md). Logo `disbursementAmount = netAmount − totalIof − tac − insurance`, e como o CET é a TIR do fluxo que parte desse desembolso, cobrar tarifa **aumenta** `monthlyEffectiveCost` e `annualEffectiveCost`. As parcelas não mudam: elas são os repasses anuais do FGTS, fixos.
{% endhint %}

## Response

A resposta contém o plano completo de pagamento com detalhamento por parcela e os totais consolidados.

| Campo                               | Tipo            | Descrição                                                                                       |
| ----------------------------------- | --------------- | ----------------------------------------------------------------------------------------------- |
| `simulationId`                      | `string` (uuid) | Identificador único da simulação gerado pela API                                                |
| `identification`                    | `string`        | CPF do tomador (11 dígitos) informado na criação                                                |
| `monthlyInterestRate`               | `number`        | Taxa de juros mensal em percentual utilizada no cálculo                                         |
| `contractDate`                      | `string` (date) | Data de contratação utilizada no cálculo (ISO-8601)                                             |
| `installments`                      | `array`         | Lista de parcelas calculadas (ver campos abaixo)                                                |
| `installments[].installmentNumber`  | `integer`       | Número sequencial da parcela (base 1)                                                           |
| `installments[].transferDate`       | `string` (date) | Data de transferência da parcela (ISO-8601)                                                     |
| `installments[].amount`             | `number`        | Valor bruto da parcela em reais                                                                 |
| `installments[].daysTerm`           | `integer`       | Dias entre a contratação e a data de transferência da parcela                                   |
| `installments[].presentValue`       | `number`        | Valor presente da parcela em reais (descontado pela taxa mensal)                                |
| `installments[].interest`           | `number`        | Valor dos juros na parcela em reais                                                             |
| `installments[].amortization`       | `number`        | Valor de amortização do principal na parcela em reais                                           |
| `installments[].iofAmount`          | `number`        | IOF da parcela em reais                                                                         |
| `installments[].outstandingBalance` | `number`        | Saldo devedor remanescente após esta parcela (zero na última)                                   |
| `totals.grossAmount`                | `number`        | Soma dos valores brutos de todas as parcelas em reais                                           |
| `totals.netAmount`                  | `number`        | Valor de emissão (VE) — soma dos valores presentes (Σ VP), valor líquido antes de IOF e tarifas |
| `totals.installmentCount`           | `integer`       | Número total de parcelas da simulação                                                           |
| `totals.totalIof`                   | `number`        | Soma do IOF de todas as parcelas em reais                                                       |
| `totals.interestAmount`             | `number`        | Soma dos juros de todas as parcelas em reais                                                    |
| `totals.disbursementAmount`         | `number`        | Valor efetivamente desembolsado ao tomador (VE − IOF total − tarifas)                           |
| `totals.monthlyEffectiveCost`       | `number`        | Custo Efetivo Total (CET) mensal em percentual                                                  |
| `totals.annualEffectiveCost`        | `number`        | Custo Efetivo Total (CET) anual em percentual                                                   |

* **201 Created** — simulação criada com sucesso.

## Exemplo

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

{
  "identification": "12345678901",
  "monthlyInterestRate": 1.799,
  "contractDate": "2026-03-12",
  "periods": [
    {
      "transferDate": "2026-11-01",
      "amount": 374.57
    }
  ],
  "tac": 15.00,
  "insurance": 30.00
}
```

```json
{
  "simulationId": "9f1c0c2e-4b8a-4f1e-9a2b-1d2c3e4f5a6b",
  "identification": "12345678901",
  "monthlyInterestRate": 1.799,
  "contractDate": "2026-03-12",
  "installments": [
    {
      "installmentNumber": 1,
      "transferDate": "2026-11-01",
      "amount": 374.57,
      "daysTerm": 234,
      "presentValue": 325.94,
      "interest": 48.63,
      "amortization": 325.94,
      "iofAmount": 7.49,
      "outstandingBalance": 0
    }
  ],
  "totals": {
    "grossAmount": 374.57,
    "netAmount": 325.94,
    "installmentCount": 1,
    "totalIof": 7.49,
    "interestAmount": 48.63,
    "disbursementAmount": 273.44,
    "monthlyEffectiveCost": 4.18,
    "annualEffectiveCost": 63.37
  }
}
```

O desembolso é `netAmount − totalIof − tac − insurance` — aqui `325,94 − 7,49 − 15,00 − 30,00`, que dá **273,44** (o cálculo desconta antes de arredondar, por isso a conta com duas casas pode diferir um centavo). O CET é a TIR desse fluxo: recebe 273,44 na contratação e paga 374,57 em 234 dias.

O mesmo contrato **sem tarifa alguma** desembolsaria 318,44 com CET de 2,13% a.m. e 28,82% a.a. Os R$ 45,00 de tarifa são o que separa 28,82% de 63,37% — num contrato de parcela única e prazo curto, qualquer tarifa fixa domina o CET.

### CET acima do teto <a href="#cet-acima-do-teto" id="cet-acima-do-teto"></a>

O CET anual tem teto de **9999,999999%**, o máximo aceito na emissão da CCB. Uma simulação cujo CET anual passa disso é recusada com `422` e `errorCode = CET_ABOVE_MAXIMUM`, e **nenhuma simulação é criada**. A mensagem traz o CET calculado.

O caso típico é tarifa grande em prazo curto. Exemplo: TAC de R$ 91,20 sobre uma única parcela de R$ 182,36 com repasse em 33 dias. O desembolso fica em R$ 86,45 e o tomador devolve 2,1 vezes esse valor em pouco mais de um mês, o que dá CET de 98,96% a.m. e **384.754,18% a.a.**

```json
{
  "type": "https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#business-rule-violation",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Annual effective cost (CET) of 384754.18% exceeds the maximum of 9999.999999%",
  "instance": "/api/v1/simulations",
  "message": "Annual effective cost (CET) of 384754.18% exceeds the maximum of 9999.999999%",
  "errorCode": "CET_ABOVE_MAXIMUM",
  "timestamp": "2026-09-29T15:42:10.123Z"
}
```

Para ficar abaixo do teto, reduza `tac`/`insurance` ou antecipe mais parcelas. O mesmo teto vale para `financialTerms.cetAnnual` em [Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md).

## Próximo passo

Com a simulação criada, use o `simulationId` retornado para recuperar os detalhes a qualquer momento em [Buscar Simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/buscar-simulacao.md).

## Erros

| Código | Situação                                                                                                                                                                                                                                                                                                                                                   |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Validação de schema (campo obrigatório ausente, CPF fora do padrão `^\d{11}$`) — `errorCode = VALIDATION_ERROR`                                                                                                                                                                                                                                            |
| 400    | Recusada por regra de produto — valor por parcela fora da faixa (`INSTALLMENT_AMOUNT_BELOW_MINIMUM`, `INSTALLMENT_AMOUNT_ABOVE_MAXIMUM`), excesso de parcelas (`MAX_INSTALLMENT_YEARS_EXCEEDED`) ou data de repasse não posterior à contratação (`INVALID_TRANSFER_DATE`). `SIMULATION_REJECTED` só aparece quando a recusa não traz um código específico. |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                                                                                                                           |
| 422    | CET não calculável: IOF + TAC + seguro consomem todo o valor das parcelas e o desembolso não é positivo — `errorCode = CET_NOT_CONVERGED`                                                                                                                                                                                                                  |
| 422    | CET anual acima de 9999,999999% — `errorCode = CET_ABOVE_MAXIMUM`. Veja [CET acima do teto](#cet-acima-do-teto).                                                                                                                                                                                                                                           |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                                                                                                                     |
| 503    | Serviço de simulação temporariamente indisponível — `errorCode = UPSTREAM_UNAVAILABLE`. A resposta **não** traz `Retry-After`: use backoff próprio                                                                                                                                                                                                         |

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

## Cria uma simulação de empréstimo FGTS

> Cria uma simulação de empréstimo consignado FGTS para o originator autenticado.\
> A simulação calcula o plano de pagamento com base na taxa de juros mensal, data de contratação e lista de parcelas (períodos de transferência com valores).\
> O campo \`identification\` é o CPF do tomador (11 dígitos) — campo PII. Validado estruturalmente no formato (11 dígitos numéricos); as regras de dígito verificador são validadas no processamento da simulação.\
> Recusas de regra de produto (faixa de valor por parcela, máximo de parcelas) são propagadas preservando o status HTTP e o \`errorCode\` do simulador — \`INSTALLMENT\_AMOUNT\_BELOW\_MINIMUM\`, \`INSTALLMENT\_AMOUNT\_ABOVE\_MAXIMUM\`, \`MAX\_INSTALLMENT\_YEARS\_EXCEEDED\`, \`INVALID\_TRANSFER\_DATE\`, \`CET\_NOT\_CONVERGED\`, \`CET\_ABOVE\_MAXIMUM\` (422). \`SIMULATION\_REJECTED\` continua sendo o código devolvido quando a resposta do simulador não traz \`errorCode\`.\
> \`503\` quando a simulação está temporariamente indisponível.

```json
{"openapi":"3.0.3","info":{"title":"gtfgts-ingress Public API","version":"0.0.1"},"tags":[{"name":"originator-simulations","description":"Simulação de empréstimo consignado FGTS. Protegido por JWT do originator."}],"servers":[{"url":"https://ingress.gtfgts.staging.giro.tech","description":"Homologação (testes e validação da integração)"},{"url":"https://gtfgts.giro.tech","description":"Produção (operações reais)"},{"url":"http://localhost:8080","description":"Local (bootRun -Pprofiles=local)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT de originator fornecido pela GTLab no cadastro do originator. Identifica e autoriza o originator em todos os endpoints `/api/v1/**`.\nInclua no header: `Authorization: Bearer <token>`."}}},"paths":{"/api/v1/simulations":{"post":{"operationId":"createOriginatorSimulation","tags":["originator-simulations"],"summary":"Cria uma simulação de empréstimo FGTS","description":"Cria uma simulação de empréstimo consignado FGTS para o originator autenticado.\nA simulação calcula o plano de pagamento com base na taxa de juros mensal, data de contratação e lista de parcelas (períodos de transferência com valores).\nO campo `identification` é o CPF do tomador (11 dígitos) — campo PII. Validado estruturalmente no formato (11 dígitos numéricos); as regras de dígito verificador são validadas no processamento da simulação.\nRecusas de regra de produto (faixa de valor por parcela, máximo de parcelas) são propagadas preservando o status HTTP e o `errorCode` do simulador — `INSTALLMENT_AMOUNT_BELOW_MINIMUM`, `INSTALLMENT_AMOUNT_ABOVE_MAXIMUM`, `MAX_INSTALLMENT_YEARS_EXCEEDED`, `INVALID_TRANSFER_DATE`, `CET_NOT_CONVERGED`, `CET_ABOVE_MAXIMUM` (422). `SIMULATION_REJECTED` continua sendo o código devolvido quando a resposta do simulador não traz `errorCode`.\n`503` quando a simulação está temporariamente indisponível.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Corpo para criação de simulação de empréstimo consignado FGTS. O cálculo e as regras de produto (faixas de valor, máximo de parcelas, etc.) são validados e aplicados no processamento da simulação.","required":["identification","monthlyInterestRate","periods"],"properties":{"identification":{"type":"string","minLength":11,"maxLength":11,"pattern":"^\\d{11}$","description":"CPF do tomador do empréstimo — 11 dígitos numéricos sem pontuação. Campo PII. Validado estruturalmente no formato; as regras de dígito verificador são aplicadas no processamento da simulação."},"monthlyInterestRate":{"type":"number","format":"double","minimum":0,"exclusiveMinimum":true,"description":"Taxa de juros mensal em percentual (ex.: `1.799` = 1,799% a.m.). Deve ser estritamente positiva (maior que zero)."},"contractDate":{"type":"string","format":"date","description":"Data de contratação no formato ISO-8601 (`yyyy-MM-dd`). Quando ausente, a data atual é utilizada."},"periods":{"type":"array","minItems":1,"maxItems":5,"description":"Parcelas a antecipar. Regras de validação: máximo de 5 parcelas; os anos podem ser quaisquer, não precisam ser consecutivos nem distintos; a primeira parcela (menor data) deve ter `transferDate` estritamente no futuro (hoje não conta como futuro). Os limites de valor por parcela são aplicados na validação.","items":{"type":"object","description":"Parcela individual da simulação de empréstimo.","required":["transferDate","amount"],"properties":{"transferDate":{"type":"string","format":"date","description":"Data de transferência da parcela no formato ISO-8601 (`yyyy-MM-dd`). Deve ser uma data futura."},"amount":{"type":"number","format":"double","minimum":50,"maximum":500,"description":"Valor do saque anual em Reais (BRL). Faixa permitida de 50,00 a 500,00."}}}},"tac":{"type":"number","format":"double","minimum":0,"description":"Tarifa de administração de contrato (TAC) em Reais (BRL). Opcional — quando ausente é tratado como `0,00`. Sempre deduzida do desembolso (`totals.disbursementAmount`) e, portanto, refletida no CET (`monthlyEffectiveCost` / `annualEffectiveCost`)."},"insurance":{"type":"number","format":"double","minimum":0,"description":"Valor do seguro prestamista em Reais (BRL). Opcional — quando ausente é tratado como `0,00`. Sempre deduzido do desembolso (`totals.disbursementAmount`) e, portanto, refletido no CET (`monthlyEffectiveCost` / `annualEffectiveCost`)."},"tacFinanced":{"type":"boolean","deprecated":true,"description":"Ignorado. A TAC é sempre deduzida do desembolso — como as parcelas do FGTS são fixas, financiá-la no saldo não altera pagamento nenhum e removeria a tarifa do CET. Aceito apenas para não quebrar clientes existentes; será removido."},"insuranceFinanced":{"type":"boolean","deprecated":true,"description":"Ignorado. O seguro é sempre deduzido do desembolso, pelo mesmo motivo do `tacFinanced`. Aceito apenas para não quebrar clientes existentes; será removido."}}}}}},"responses":{"201":{"description":"Simulação de empréstimo criada com sucesso. Contém o plano completo de pagamento com parcelas, valores de IOF, valor de emissão (VE = Σ valor presente) e custo efetivo total (CET).","content":{"application/json":{"schema":{"type":"object","description":"Resultado da simulação de empréstimo consignado FGTS. Contém o plano completo de pagamento com detalhamento por parcela (IOF, juros, amortização, valor presente) e totais consolidados (VE, CET, IOF total).","properties":{"simulationId":{"type":"string","format":"uuid","description":"Identificador único da simulação (UUID)."},"identification":{"type":"string","description":"CPF do tomador (11 dígitos) informado na criação."},"monthlyInterestRate":{"type":"number","format":"double","description":"Taxa de juros mensal em percentual utilizada no cálculo."},"contractDate":{"type":"string","format":"date","description":"Data de contratação utilizada no cálculo (ISO-8601)."},"installments":{"type":"array","description":"Lista de parcelas calculadas com detalhamento financeiro.","items":{"type":"object","description":"Detalhamento financeiro de uma parcela calculada na simulação.","properties":{"installmentNumber":{"type":"integer","format":"int32","description":"Número sequencial da parcela (base 1)."},"transferDate":{"type":"string","format":"date","description":"Data de transferência da parcela (ISO-8601)."},"amount":{"type":"number","format":"double","description":"Valor bruto da parcela em Reais (BRL)."},"daysTerm":{"type":"integer","format":"int32","description":"Número de dias entre a data de contratação e a data de transferência da parcela."},"presentValue":{"type":"number","format":"double","description":"Valor presente da parcela em Reais (BRL) — valor da parcela descontado pela taxa mensal para a data de contratação."},"interest":{"type":"number","format":"double","description":"Valor dos juros na parcela em Reais (BRL)."},"amortization":{"type":"number","format":"double","description":"Valor de amortização do principal na parcela em Reais (BRL)."},"iofAmount":{"type":"number","format":"double","description":"Valor do IOF (Imposto sobre Operações Financeiras) da parcela em Reais (BRL)."},"outstandingBalance":{"type":"number","format":"double","description":"Saldo devedor remanescente após esta parcela em Reais (BRL). Zero na última parcela."}}}},"totals":{"type":"object","description":"Totais consolidados da simulação de empréstimo. Agrega os valores de todas as parcelas e apresenta os indicadores de custo efetivo (CET).","properties":{"grossAmount":{"type":"number","format":"double","description":"Soma dos valores brutos de todas as parcelas em Reais (BRL)."},"netAmount":{"type":"number","format":"double","description":"Valor de emissão (VE) — soma dos valores presentes de todas as parcelas (Σ VP). Representa o valor líquido antes da dedução de IOF e tarifas."},"installmentCount":{"type":"integer","format":"int32","description":"Número total de parcelas da simulação."},"totalIof":{"type":"number","format":"double","description":"Soma do IOF de todas as parcelas em Reais (BRL)."},"interestAmount":{"type":"number","format":"double","description":"Soma dos juros de todas as parcelas em Reais (BRL)."},"disbursementAmount":{"type":"number","format":"double","description":"Valor efetivamente desembolsado ao tomador em Reais (BRL) = VE − IOF total − `tac` − `insurance`. As tarifas são sempre deduzidas aqui, e é sobre este valor que o CET é apurado."},"monthlyEffectiveCost":{"type":"number","format":"double","description":"Custo Efetivo Total (CET) mensal em percentual."},"annualEffectiveCost":{"type":"number","format":"double","description":"Custo Efetivo Total (CET) anual em percentual."}}}}}}}},"400":{"description":"Requisição inválida (validação de schema) ou recusada pelas regras de produto — valor por parcela fora da faixa permitida ou excesso de parcelas.\nDois sub-casos distintos com `errorCode` diferente:\n- **`VALIDATION_ERROR`** (Bean Validation): falha estrutural nos campos\n  (`identification` ausente, `periods` vazio, etc.). Inclui o campo `errors`\n  com o mapa `{ \"campo\": \"mensagem\" }`.\n- **`errorCode` do simulador** (regra de produto): `INSTALLMENT_AMOUNT_BELOW_MINIMUM`,\n  `INSTALLMENT_AMOUNT_ABOVE_MAXIMUM`, `MAX_INSTALLMENT_YEARS_EXCEEDED`,\n  `INVALID_TRANSFER_DATE`, `INVALID_CONTRACT_DATE`, `INVALID_INTEREST_RATE` ou\n  `EMPTY_PERIODS`. `SIMULATION_REJECTED` aparece apenas quando a resposta do simulador\n  não traz `errorCode`.","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."}}}}}},"422":{"description":"Entidade não processável — o Custo Efetivo Total (CET) do fluxo informado não pode ser usado:\n- `CET_NOT_CONVERGED`: o desembolso líquido não é positivo, isto é, IOF + TAC + seguro\n  consomem todo o valor presente das parcelas.\n\n- `CET_ABOVE_MAXIMUM`: o CET anual passa de `9999.999999`%, o teto aceito na emissão da\n  CCB (o mesmo de `financialTerms.cetAnnual` na criação do contrato). Acontece com\n  tarifa grande em prazo curto — ex.: TAC de R$ 91,20 sobre uma parcela de R$ 182,36 em\n  33 dias → ~384.754% a.a. Reduza a TAC/seguro ou alongue o prazo.","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 de simulação temporariamente indisponível (`UPSTREAM_UNAVAILABLE`). A resposta não traz `Retry-After`: use backoff próprio.","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."}}}}}}}}}}}
```

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