> 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-gtpayroll/api-reference/simulacoes/simular-sem-vinculo-por-parcela.md).

# Simular sem Vínculo por Parcela

Simulação reversa **sem que o trabalhador ou o vínculo empregatício estejam cadastrados** no GT Payroll: você informa a parcela desejada (`targetInstallmentAmount`) e recebe o maior valor de empréstimo que produz essa parcela. As regras de cálculo são as mesmas de [Criar Simulação por Parcela](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao-por-parcela.md).

Uso previsto: **simular a migração de um contrato mantendo a parcela** do contrato de origem, quando o vínculo novo do trabalhador ainda não existe no GT Payroll. Para simular a partir do valor liberado, use [Simular sem Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/simular-sem-vinculo.md). Para contratar, siga o fluxo com vínculo: [Criar Simulação por Parcela](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao-por-parcela.md) → [Criar Proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md).

{% hint style="warning" %}
**O que este endpoint não faz**

* Não exige nem consulta employee ou vínculo cadastrado.
* Não valida margem consignável nem as [regras de elegibilidade](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/elegibilidade.md), inclusive os limites do produto (valor e quantidade de parcelas). O resultado pode não ser contratável no fluxo com vínculo.
* Não gera simulação consultável: a resposta é `200 OK`, **sem `publicId`**. A simulação não é gravada nem pode ser consultada depois, e não pode ser convertida em proposta.
  {% endhint %}

## Request

`POST /api/v1/originator/simulations/by-installment`

Autenticação: `Authorization: Bearer {originatorToken}`. Aceita o header `Idempotency-Key` (ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md)).

### Corpo

Igual ao de [Simular sem Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/simular-sem-vinculo.md), com `targetInstallmentAmount` no lugar de `loanAmount`.

| Campo                     | Tipo            | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------- | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `targetInstallmentAmount` | `decimal`       | Sim         | Valor de parcela desejado em reais (>= 0.01)                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `installmentCount`        | `integer`       | Sim         | Número de parcelas (1–99)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `monthlyInterestRate`     | `decimal`       | Sim         | Taxa de juros mensal em percentual (>= 0.01)                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `loanDate`                | `string` (date) | Sim         | Data do empréstimo (`YYYY-MM-DD`). Não pode ser no passado.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `firstDueDate`            | `string` (date) | Não         | Data do primeiro vencimento, sempre no dia 28. `null` ou omitido para cálculo automático ([regra de vencimento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao.md#regra-de-vencimento-automatico)). Não pode ser no passado.                                                                                                                                                                                                               |
| `tacAmount`               | `decimal`       | Não         | Taxa de Abertura de Crédito. Deve ser `0` ou omitido; valor positivo dá `400` (`TAC_NOT_ALLOWED`).                                                                                                                                                                                                                                                                                                                                                                                        |
| `insuranceAmount`         | `decimal`       | Não         | Seguro prestamista (>= 0).                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `feesAmount`              | `decimal`       | Não         | **Deprecated — use `tacAmount` + `insuranceAmount`.**                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `iofFinanced`             | `boolean`       | Não         | IOF financiado. Omitido: configuração do originador (sem configuração, `true`).                                                                                                                                                                                                                                                                                                                                                                                                           |
| `feesFinanced`            | `boolean`       | Não         | Tarifas (TAC + seguro) financiadas. Omitido: configuração do originador (sem configuração, `true`).                                                                                                                                                                                                                                                                                                                                                                                       |
| `maxEffectiveCostSpread`  | `decimal`       | Não         | Teto de CET relativo à taxa contratada, **em pontos percentuais** (`1.0` = CET mensal máxima de taxa + 1 p.p.; faixa 0.01–100). O campo é **aceito**, mas o teto **não é aplicado nem verificado**: a plataforma não isenta dias de juros de carência por causa dele. O único efeito observável de enviá-lo é a resposta vir com `effectiveCostWithinLimit` = `null` (explícito no JSON). Omitido, `effectiveCostWithinLimit` volta `true`. Não há default do originador para este campo. |

As tarifas seguem a mesma [regra tudo-ou-nada](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/simular-sem-vinculo.md#tarifas-regra-tudo-ou-nada): se `tacAmount` **ou** `insuranceAmount` vier, os dois são usados e o que faltar vale `0` (enviar só `tacAmount: 0` zera o seguro); só `feesAmount` vira seguro com `tacAmount = 0`; sem nenhum dos três, vale o default do originador, com a TAC default zerada e somada ao seguro.

## Response

`200 OK`. Mesmo formato de [Simular sem Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/simular-sem-vinculo.md#response). A diferença: `requestedAmount` é o valor de empréstimo que o cálculo encontrou para a parcela pedida.

## Exemplo

```http
POST /api/v1/originator/simulations/by-installment HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json
Idempotency-Key: sim-sem-vinculo-parcela-0001

{
  "targetInstallmentAmount": 501.18,
  "installmentCount": 12,
  "monthlyInterestRate": 1.97,
  "loanDate": "2027-01-04",
  "firstDueDate": "2027-03-28",
  "iofFinanced": true
}
```

A resposta completa, com os valores calculados, está no exemplo do bloco de referência no fim da página.

## Erros

| Código        | `errorCode`                         | Situação                                                                                                                                                      |
| ------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400           | —                                   | Payload inválido (`properties.errors`), data no passado ou fora do calendário Dataprev, simulação recusada pela validação de Valor Presente da Dataprev       |
| 400           | —                                   | JSON malformado ou data inválida (`type: about:blank`)                                                                                                        |
| 400           | `TAC_NOT_ALLOWED`                   | `tacAmount` diferente de 0 (positivo ou negativo)                                                                                                             |
| 400           | —                                   | `Simulação reversa não convergiu para o valor de parcela informado.` — ajuste a parcela ou o prazo                                                            |
| 429           | —                                   | Mais de 100 requisições por segundo. Reenvie com uma **nova** `Idempotency-Key`                                                                               |
| 4xx repassado | `LOAN_SIMULATOR_ERROR`              | O simulador de crédito recusou o cálculo, com o status devolvido por ele (`502` se o status não for reconhecido; `500` se a resposta vier vazia)              |
| 503           | `SERVICE_UNAVAILABLE_LOANSIMULATOR` | Simulador de crédito indisponível. Reenvie com uma **nova** `Idempotency-Key`: com a mesma chave, a resposta guardada (este mesmo erro) é repetida por 7 dias |

Erros comuns a todos os endpoints — `401`, `403` de token, `409` de `Idempotency-Key` em processamento, `500` e `503` — e o formato `ProblemDetail` estão em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md).

## Simular sem vínculo por parcela (reversa)

> Simulação reversa \*\*sem employee e sem vínculo empregatício cadastrados\*\*: dado o valor de\
> parcela desejado (\`targetInstallmentAmount\`), encontra o maior valor de empréstimo que produz\
> essa parcela. Uso previsto: simular a \*\*migração de contrato\*\* quando o vínculo novo ainda\
> não está cadastrado — por exemplo, manter a parcela do contrato de origem.\
> \
> Não exige employee nem vínculo, não valida margem nem elegibilidade e não persiste a\
> simulação (\`200 OK\`, sem \`publicId\`; o resultado não vira proposta). Com\
> \`Idempotency-Key\`, a resposta fica guardada para replay, como em todo POST do originador.\
> As regras de cálculo e de primeiro vencimento são as de "Criar Simulação por Parcela (Reversa)".\
> \
> \*\*Limites do produto não são checados.\*\* Valor e prazo \*\*não\*\* são validados contra os limites\
> do produto do originador (os mesmos devolvidos por \`GET /loan-limits\`: valor mínimo/máximo e\
> quantidade de parcelas). O resultado pode não ser contratável no fluxo com vínculo.\
> \
> \*\*Tarifas (tudo-ou-nada).\*\* Se \`tacAmount\` \*\*ou\*\* \`insuranceAmount\` vier, os dois são usados\
> e o que faltar vale \`0\` — o default do originador \*\*não\*\* é aplicado (enviar só\
> \`tacAmount: 0\` zera o seguro). Se só \`feesAmount\` (deprecated) vier, ele vira seguro e\
> \`tacAmount = 0\`. Se nenhum dos três vier, vale o default de tarifas do originador autenticado,\
> com a TAC default zerada e somada ao seguro (ex.: TAC default 50 + seguro default 100 →\
> \`tacAmount = 0\`, \`insuranceAmount = 150\`).\
> \
> \*\*Financiamento.\*\* \`iofFinanced\` e \`feesFinanced\` omitidos seguem a configuração do\
> originador (sem configuração, \`true\`). \`maxEffectiveCostSpread\` é \*\*aceito\*\* nesta\
> operação, mas o teto \*\*não é aplicado nem verificado\*\*: o simulador não isenta dias de\
> juros de carência por causa dele.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Simulations","description":"Simulações de empréstimo"}],"servers":[{"url":"https://ingress.gtpayroll.staging.giro.tech","description":"Ambiente de Staging"},{"url":"https://ingress.gtpayroll.giro.tech","description":"Ambiente de Produção"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token fornecido pelo administrador"}}},"paths":{"/api/v1/originator/simulations/by-installment":{"post":{"summary":"Simular sem vínculo por parcela (reversa)","description":"Simulação reversa **sem employee e sem vínculo empregatício cadastrados**: dado o valor de\nparcela desejado (`targetInstallmentAmount`), encontra o maior valor de empréstimo que produz\nessa parcela. Uso previsto: simular a **migração de contrato** quando o vínculo novo ainda\nnão está cadastrado — por exemplo, manter a parcela do contrato de origem.\n\nNão exige employee nem vínculo, não valida margem nem elegibilidade e não persiste a\nsimulação (`200 OK`, sem `publicId`; o resultado não vira proposta). Com\n`Idempotency-Key`, a resposta fica guardada para replay, como em todo POST do originador.\nAs regras de cálculo e de primeiro vencimento são as de \"Criar Simulação por Parcela (Reversa)\".\n\n**Limites do produto não são checados.** Valor e prazo **não** são validados contra os limites\ndo produto do originador (os mesmos devolvidos por `GET /loan-limits`: valor mínimo/máximo e\nquantidade de parcelas). O resultado pode não ser contratável no fluxo com vínculo.\n\n**Tarifas (tudo-ou-nada).** Se `tacAmount` **ou** `insuranceAmount` vier, os dois são usados\ne o que faltar vale `0` — o default do originador **não** é aplicado (enviar só\n`tacAmount: 0` zera o seguro). Se só `feesAmount` (deprecated) vier, ele vira seguro e\n`tacAmount = 0`. Se nenhum dos três vier, vale o default de tarifas do originador autenticado,\ncom a TAC default zerada e somada ao seguro (ex.: TAC default 50 + seguro default 100 →\n`tacAmount = 0`, `insuranceAmount = 150`).\n\n**Financiamento.** `iofFinanced` e `feesFinanced` omitidos seguem a configuração do\noriginador (sem configuração, `true`). `maxEffectiveCostSpread` é **aceito** nesta\noperação, mas o teto **não é aplicado nem verificado**: o simulador não isenta dias de\njuros de carência por causa dele.\n","tags":["Simulations"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Chave de idempotência. Se fornecida, o servidor devolve a mesma resposta para chamadas\ncom a mesma chave do mesmo originador. A chave é retida por 7 dias.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Simulação reversa sem vínculo: mesmos campos de \"Criar Simulação por Parcela (Reversa)\", sem identificador de vínculo.","required":["targetInstallmentAmount","installmentCount","monthlyInterestRate","loanDate"],"properties":{"targetInstallmentAmount":{"type":"number","format":"decimal","minimum":0.01,"description":"Valor de parcela desejado em reais (decimal com 2 casas decimais). O sistema encontra o valor máximo de empréstimo que produz essa parcela."},"installmentCount":{"type":"integer","minimum":1,"description":"Quantidade de parcelas desejada para pagamento do empréstimo.","maximum":99},"monthlyInterestRate":{"type":"number","format":"decimal","minimum":0.01,"description":"Taxa de juros mensal nominal em percentual (decimal com 4 casas decimais). Ex. 4.0"},"loanDate":{"type":"string","format":"date","description":"Data base de contratação considerada para cálculo da operação. Não pode ser no passado."},"firstDueDate":{"type":"string","format":"date","nullable":true,"description":"Data do primeiro vencimento (sempre dia 28). Não pode ser no passado.\n- Se informado, deve seguir o calendário Dataprev.\n- Se `null` (ou omitido), o sistema aplica automaticamente o primeiro vencimento no dia 28 conforme o calendário Dataprev.\n"},"tacAmount":{"type":"number","format":"decimal","minimum":0,"nullable":true,"description":"Valor de TAC (Taxa de Abertura de Crédito) em reais. Para consignado privado deve ser `0` ou omitido — `tacAmount > 0` retorna `400` com `errorCode = TAC_NOT_ALLOWED`.\nAtenção: enviar `tacAmount` (mesmo `0`) sem `insuranceAmount` zera o seguro, porque desliga o default do originador.\nRegra das tarifas (tudo-ou-nada, não por campo):\n- `tacAmount` **ou** `insuranceAmount` informado → usa os dois; o que faltar vale `0`. O default do originador **não** é aplicado.\n- só `feesAmount` (legado) informado → vira `insuranceAmount`, com `tacAmount = 0`.\n- nenhum dos três informado → vale o default de tarifas configurado para o originador autenticado, com a TAC default zerada e somada ao seguro (ex.: TAC default 50 + seguro default 100 → `tacAmount = 0`, `insuranceAmount = 150`).\n"},"insuranceAmount":{"type":"number","format":"decimal","minimum":0,"nullable":true,"description":"Valor do seguro prestamista em reais.\nRegra das tarifas (tudo-ou-nada, não por campo):\n- `tacAmount` **ou** `insuranceAmount` informado → usa os dois; o que faltar vale `0`. O default do originador **não** é aplicado.\n- só `feesAmount` (legado) informado → vira `insuranceAmount`, com `tacAmount = 0`.\n- nenhum dos três informado → vale o default de tarifas configurado para o originador autenticado, com a TAC default zerada e somada ao seguro (ex.: TAC default 50 + seguro default 100 → `tacAmount = 0`, `insuranceAmount = 150`).\n"},"feesAmount":{"type":"number","format":"decimal","minimum":0,"nullable":true,"deprecated":true,"description":"**DEPRECATED** — use `tacAmount` + `insuranceAmount`. Só é considerado quando nenhum dos dois vem; nesse caso vira `insuranceAmount`, com `tacAmount = 0`.\nRegra das tarifas (tudo-ou-nada, não por campo):\n- `tacAmount` **ou** `insuranceAmount` informado → usa os dois; o que faltar vale `0`. O default do originador **não** é aplicado.\n- só `feesAmount` (legado) informado → vira `insuranceAmount`, com `tacAmount = 0`.\n- nenhum dos três informado → vale o default de tarifas configurado para o originador autenticado, com a TAC default zerada e somada ao seguro (ex.: TAC default 50 + seguro default 100 → `tacAmount = 0`, `insuranceAmount = 150`).\n"},"iofFinanced":{"type":"boolean","nullable":true,"description":"Define se o IOF é financiado (embutido no valor financiado e diluído nas parcelas).\n- `true`: IOF financiado. `false`: IOF descontado do desembolso.\n- omitido/`null`: vale a configuração do originador autenticado; sem configuração, `true`.\n"},"feesFinanced":{"type":"boolean","nullable":true,"description":"Define se as tarifas (TAC + seguro) são financiadas (embutidas no valor financiado e diluídas nas parcelas).\n- `true`: tarifas financiadas. `false`: custo das tarifas descontado do desembolso.\n- omitido/`null`: vale a configuração do originador autenticado; sem configuração, `true`.\n"},"maxEffectiveCostSpread":{"type":"number","format":"decimal","minimum":0.01,"maximum":100,"nullable":true,"description":"Teto de CET relativo à taxa contratada, **em pontos percentuais** — mesma forma do `monthlyInterestRate`\n(ex.: `1.0` = CET mensal máxima de taxa + 1 p.p.). O campo é **aceito** na reversa, mas o teto\n**não é aplicado nem verificado** nesta operação: o simulador não isenta dias de juros de carência\npor causa dele.\nO único efeito observável de enviá-lo é a resposta vir com `effectiveCostWithinLimit` = `null`\n(teto não verificado).\nNão tem default do originador: omitido, `effectiveCostWithinLimit` volta `true`.\n"}}}}}},"responses":{"200":{"description":"Simulação reversa calculada (nada é persistido)","content":{"application/json":{"schema":{"type":"object","description":"Resultado de cálculo de simulação sem vínculo. A simulação não é persistida: não tem identificador, status nem expiração, e não pode ser convertida em proposta. Os campos fora de `required` podem vir `null` quando o cálculo não os devolve.\n\nOs valores do exemplo são ilustrativos: mostram a forma e as relações entre os campos, não o resultado exato do cálculo. Correspondem ao request de exemplo (R$ 5.000,00 em 12x a 1,97% a.m., `loanDate` 2027-01-04, 1º vencimento 2027-03-28, IOF financiado, sem tarifas): como o IOF é financiado, `disbursementAmount` = `requestedAmount` e `financedAmount` = `requestedAmount` + `iofAmount`; `debitAmount` = soma das parcelas; `totalInterestAmount` = `debitAmount` − `financedAmount`; `annualEffectiveCost` = (1 + `monthlyEffectiveCost`/100)^12 − 1. O array `installments` do exemplo mostra só a 1ª, a 2ª e a última parcela.\n","required":["requestedAmount","tacAmount","insuranceAmount","iofFinanced","installments"],"properties":{"requestedAmount":{"type":"number","format":"decimal","description":"Valor solicitado em reais (decimal com 2 casas decimais). Na simulação por parcela (reversa), é o\nvalor de empréstimo que o cálculo encontrou para a parcela pedida.\n"},"disbursementAmount":{"type":"number","format":"decimal","nullable":true,"description":"Valor desembolsado em reais (decimal com 2 casas decimais)."},"installmentCount":{"type":"integer","nullable":true,"description":"Quantidade de parcelas calculada para a proposta simulada."},"monthlyInterestRate":{"type":"number","format":"decimal","nullable":true,"description":"Taxa de juros mensal em percentual (decimal com 4 casas decimais)."},"termMonths":{"type":"integer","nullable":true,"description":"Prazo total da operação em meses."},"installmentAmount":{"type":"number","format":"decimal","nullable":true,"description":"Parcela mensal em reais (decimal com 2 casas decimais)."},"monthlyEffectiveCost":{"type":"number","format":"decimal","nullable":true,"description":"CET mensal em percentual (decimal com 4 casas decimais)."},"annualEffectiveCost":{"type":"number","format":"decimal","nullable":true,"description":"CET anual em percentual (decimal com 4 casas decimais)."},"iofAmount":{"type":"number","format":"decimal","nullable":true,"description":"IOF estimado em reais (decimal com 2 casas decimais)."},"tacAmount":{"type":"number","format":"decimal","description":"TAC (Taxa de Abertura de Crédito) em reais. Para consignado privado, sempre `0`."},"insuranceAmount":{"type":"number","format":"decimal","description":"Seguro prestamista em reais. Snapshot do valor usado no cálculo da simulação."},"financedAmount":{"type":"number","format":"decimal","nullable":true,"description":"Valor financiado em reais (decimal com 2 casas decimais)."},"debitAmount":{"type":"number","format":"decimal","nullable":true,"minimum":0,"description":"Total a pagar em reais (soma das parcelas, decimal com 2 casas decimais). A última parcela pode diferir das demais por arredondamento."},"outstandingBalance":{"type":"number","format":"decimal","nullable":true,"description":"Saldo devedor em reais (decimal com 2 casas decimais)."},"totalInterestAmount":{"type":"number","format":"decimal","nullable":true,"description":"Juros totais em reais (decimal com 2 casas decimais)."},"firstDueDate":{"type":"string","format":"date","nullable":true,"description":"Data do primeiro vencimento."},"lastDueDate":{"type":"string","format":"date","nullable":true,"description":"Data do último vencimento."},"installments":{"type":"array","description":"Lista de parcelas da simulação com detalhamento por parcela. Vem `[]` quando o cálculo não devolve parcelas, nunca `null`.","items":{"type":"object","description":"Detalhamento de uma parcela da simulação sem vínculo.","properties":{"installmentNumber":{"type":"integer","nullable":true,"description":"Número da parcela (1-based)."},"dueDate":{"type":"string","format":"date","nullable":true,"description":"Data de vencimento da parcela."},"installmentAmount":{"type":"number","format":"decimal","nullable":true,"description":"Valor total da parcela em reais."},"amortizationAmount":{"type":"number","format":"decimal","nullable":true,"description":"Capital amortizado na parcela em reais."},"interestAmount":{"type":"number","format":"decimal","nullable":true,"description":"Valor dos juros na parcela em reais."},"iofAmount":{"type":"number","format":"decimal","nullable":true,"description":"IOF da parcela em reais."},"outstandingBalance":{"type":"number","format":"decimal","nullable":true,"description":"Saldo devedor após a parcela em reais."},"daysToCompensate":{"type":"integer","nullable":true,"description":"Dias a compensar para a parcela."}}}},"iofFinanced":{"type":"boolean","description":"Indica se o IOF foi financiado na simulação."},"graceDaysCharged":{"type":"integer","format":"int64","nullable":true,"description":"Dias de juros de carência efetivamente cobrados pelo simulador."},"graceDaysWaived":{"type":"integer","format":"int64","nullable":true,"description":"Dias de juros de carência isentados pela convergência do teto de CET (0 sem teto)."},"effectiveCostWithinLimit":{"type":"boolean","nullable":true,"description":"Na simulação direta: `true` quando a CET mensal ficou dentro do teto solicitado (ou nenhum teto foi informado);\n`false` quando nem isentando toda a carência o teto foi atingido (best-effort).\nNa reversa (por parcela): o teto não é verificado. Vem `true` quando a requisição não trouxe `maxEffectiveCostSpread`;\nvem `null` quando trouxe — o campo é serializado como `null` **explícito** no JSON (não omitido).\n"}}}}}},"400":{"description":"Dados inválidos, corpo ilegível ou regra de negócio.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"401":{"description":"Não autenticado","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autenticação (HTTP 401). Token ausente, com prefixo diferente de `Bearer `, expirado, revogado ou inválido.","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"403":{"description":"Permissão insuficiente","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autorização (HTTP 403). Token válido de outro perfil, sem permissão de originador.\nRecusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam\n`#business-rule-violation` com `properties.errorCode`.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"409":{"description":"Mesma `Idempotency-Key` ainda em processamento; tente de novo depois","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro das simulações sem vínculo, no formato Problem Details (RFC 7807). Os campos além de\n`type`, `title`, `status`, `detail` e `instance` vêm **dentro de `properties`**, não na raiz.\n","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri","description":"URI que identifica o tipo do problema na documentação."},"title":{"type":"string","description":"Resumo curto do tipo do problema."},"status":{"type":"integer","description":"Código HTTP do erro."},"detail":{"type":"string","description":"Explicação desta ocorrência do problema."},"instance":{"type":"string","description":"Caminho da requisição que gerou o problema."},"properties":{"type":"object","description":"Campos extras do erro. Cada campo só aparece quando se aplica ao tipo do problema.","properties":{"message":{"type":"string","description":"Mensagem de erro legível (repete `detail`)."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Só em erro na validação do corpo (`400`). Mapa campo → mensagem."},"errorCode":{"type":"string","description":"Código estável do erro, quando existe. Valores possíveis nestes endpoints:\n- `TAC_NOT_ALLOWED` (`400`): `tacAmount > 0`;\n- `LOAN_SIMULATOR_ERROR` (`4xx` repassado do motor de cálculo, ou `502`): o cálculo recusou a simulação;\n- `SERVICE_UNAVAILABLE_LOANSIMULATOR` (`503`): motor de cálculo indisponível.\n"},"retryAfter":{"type":"integer","format":"int64","description":"Só em `429`. Segundos até poder tentar de novo."},"limit":{"type":"integer","description":"Só em `429`. Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"Só em `429`. Momento em que a janela reinicia, em epoch **milissegundos**."}}}}}}}},"429":{"description":"Rate limit excedido","headers":{"Retry-After":{"description":"Segundos a aguardar antes da próxima requisição.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Limite de requisições da janela.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela (sempre `0` no `429`).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Momento em que a janela reinicia, em epoch milissegundos.","schema":{"type":"integer","format":"int64"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Erro das simulações sem vínculo, no formato Problem Details (RFC 7807). Os campos além de\n`type`, `title`, `status`, `detail` e `instance` vêm **dentro de `properties`**, não na raiz.\n","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri","description":"URI que identifica o tipo do problema na documentação."},"title":{"type":"string","description":"Resumo curto do tipo do problema."},"status":{"type":"integer","description":"Código HTTP do erro."},"detail":{"type":"string","description":"Explicação desta ocorrência do problema."},"instance":{"type":"string","description":"Caminho da requisição que gerou o problema."},"properties":{"type":"object","description":"Campos extras do erro. Cada campo só aparece quando se aplica ao tipo do problema.","properties":{"message":{"type":"string","description":"Mensagem de erro legível (repete `detail`)."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Só em erro na validação do corpo (`400`). Mapa campo → mensagem."},"errorCode":{"type":"string","description":"Código estável do erro, quando existe. Valores possíveis nestes endpoints:\n- `TAC_NOT_ALLOWED` (`400`): `tacAmount > 0`;\n- `LOAN_SIMULATOR_ERROR` (`4xx` repassado do motor de cálculo, ou `502`): o cálculo recusou a simulação;\n- `SERVICE_UNAVAILABLE_LOANSIMULATOR` (`503`): motor de cálculo indisponível.\n"},"retryAfter":{"type":"integer","format":"int64","description":"Só em `429`. Segundos até poder tentar de novo."},"limit":{"type":"integer","description":"Só em `429`. Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"Só em `429`. Momento em que a janela reinicia, em epoch **milissegundos**."}}}}}}}},"502":{"description":"Status não reconhecido do motor de cálculo (`errorCode` LOAN_SIMULATOR_ERROR)","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro das simulações sem vínculo, no formato Problem Details (RFC 7807). Os campos além de\n`type`, `title`, `status`, `detail` e `instance` vêm **dentro de `properties`**, não na raiz.\n","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri","description":"URI que identifica o tipo do problema na documentação."},"title":{"type":"string","description":"Resumo curto do tipo do problema."},"status":{"type":"integer","description":"Código HTTP do erro."},"detail":{"type":"string","description":"Explicação desta ocorrência do problema."},"instance":{"type":"string","description":"Caminho da requisição que gerou o problema."},"properties":{"type":"object","description":"Campos extras do erro. Cada campo só aparece quando se aplica ao tipo do problema.","properties":{"message":{"type":"string","description":"Mensagem de erro legível (repete `detail`)."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Só em erro na validação do corpo (`400`). Mapa campo → mensagem."},"errorCode":{"type":"string","description":"Código estável do erro, quando existe. Valores possíveis nestes endpoints:\n- `TAC_NOT_ALLOWED` (`400`): `tacAmount > 0`;\n- `LOAN_SIMULATOR_ERROR` (`4xx` repassado do motor de cálculo, ou `502`): o cálculo recusou a simulação;\n- `SERVICE_UNAVAILABLE_LOANSIMULATOR` (`503`): motor de cálculo indisponível.\n"},"retryAfter":{"type":"integer","format":"int64","description":"Só em `429`. Segundos até poder tentar de novo."},"limit":{"type":"integer","description":"Só em `429`. Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"Só em `429`. Momento em que a janela reinicia, em epoch **milissegundos**."}}}}}}}},"503":{"description":"Simulador de crédito indisponível. Reenvie com **nova** `Idempotency-Key`.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"4XX":{"description":"Recusada pelo motor de cálculo, com o status dele (`errorCode` LOAN_SIMULATOR_ERROR)","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro das simulações sem vínculo, no formato Problem Details (RFC 7807). Os campos além de\n`type`, `title`, `status`, `detail` e `instance` vêm **dentro de `properties`**, não na raiz.\n","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri","description":"URI que identifica o tipo do problema na documentação."},"title":{"type":"string","description":"Resumo curto do tipo do problema."},"status":{"type":"integer","description":"Código HTTP do erro."},"detail":{"type":"string","description":"Explicação desta ocorrência do problema."},"instance":{"type":"string","description":"Caminho da requisição que gerou o problema."},"properties":{"type":"object","description":"Campos extras do erro. Cada campo só aparece quando se aplica ao tipo do problema.","properties":{"message":{"type":"string","description":"Mensagem de erro legível (repete `detail`)."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Só em erro na validação do corpo (`400`). Mapa campo → mensagem."},"errorCode":{"type":"string","description":"Código estável do erro, quando existe. Valores possíveis nestes endpoints:\n- `TAC_NOT_ALLOWED` (`400`): `tacAmount > 0`;\n- `LOAN_SIMULATOR_ERROR` (`4xx` repassado do motor de cálculo, ou `502`): o cálculo recusou a simulação;\n- `SERVICE_UNAVAILABLE_LOANSIMULATOR` (`503`): motor de cálculo indisponível.\n"},"retryAfter":{"type":"integer","format":"int64","description":"Só em `429`. Segundos até poder tentar de novo."},"limit":{"type":"integer","description":"Só em `429`. Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"Só em `429`. Momento em que a janela reinicia, em epoch **milissegundos**."}}}}}}}}}}}}}
```

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