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

# Buscar Simulação

Recupera uma simulação de empréstimo FGTS previamente criada pelo originator autenticado, com o plano completo de pagamento calculado no momento da criação.

{% hint style="info" %}
Apenas o originator dono da simulação pode consultá-la. Acesso cruzado entre originators retorna `403`; simulação inexistente ou de outro originator retorna `404` (`errorCode = SIMULATION_NOT_FOUND`).
{% endhint %}

## Request

`GET /api/v1/simulations/{simulationId}`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Parâmetros

| Parâmetro      | Local | Tipo            | Obrigatório | Descrição                                                             |
| -------------- | ----- | --------------- | ----------- | --------------------------------------------------------------------- |
| `simulationId` | path  | `string` (uuid) | Sim         | Identificador único da simulação (UUID) retornado na criação (`POST`) |

## Response

O corpo da resposta segue o mesmo schema da [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/criar-simulacao.md#response).

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

* **200 OK** — simulação encontrada e retornada com sucesso.

## Exemplo

```http
GET /api/v1/simulations/9f1c0c2e-4b8a-4f1e-9a2b-1d2c3e4f5a6b HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
```

```json
{
  "simulationId": "9f1c0c2e-4b8a-4f1e-9a2b-1d2c3e4f5a6b",
  "identification": "12345678901",
  "monthlyInterestRate": 1.799,
  "contractDate": "2026-06-14",
  "installments": [
    {
      "installmentNumber": 1,
      "transferDate": "2026-11-01",
      "amount": 374.57,
      "daysTerm": 140,
      "presentValue": 325.94,
      "interest": 48.63,
      "amortization": 325.93,
      "iofAmount": 7.49,
      "outstandingBalance": 0
    }
  ],
  "totals": {
    "grossAmount": 374.57,
    "netAmount": 325.94,
    "installmentCount": 1,
    "totalIof": 7.49,
    "interestAmount": 48.63,
    "disbursementAmount": 318.44,
    "monthlyEffectiveCost": 2.13,
    "annualEffectiveCost": 28.82
  }
}
```

## Erros

| Código | Situação                                                                                                                                           |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                   |
| 404    | Simulação não encontrada para o `simulationId`, ou não pertence ao originator autenticado — `errorCode = SIMULATION_NOT_FOUND`                     |
| 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).

## Recupera uma simulação de empréstimo FGTS por ID

> Recupera uma simulação de empréstimo FGTS previamente criada pelo originator autenticado.\
> Apenas o originator dono da simulação pode consultá-la (\`403\` em acesso cruzado). \`404\` se a simulação não existir ou não pertencer ao originator autenticado (errorCode \`SIMULATION\_NOT\_FOUND\`). \`503\` quando a consulta 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/{simulationId}":{"get":{"operationId":"getOriginatorSimulationById","tags":["originator-simulations"],"summary":"Recupera uma simulação de empréstimo FGTS por ID","description":"Recupera uma simulação de empréstimo FGTS previamente criada pelo originator autenticado.\nApenas o originator dono da simulação pode consultá-la (`403` em acesso cruzado). `404` se a simulação não existir ou não pertencer ao originator autenticado (errorCode `SIMULATION_NOT_FOUND`). `503` quando a consulta está temporariamente indisponível.","parameters":[{"name":"simulationId","in":"path","required":true,"description":"Identificador da simulação retornado na criação (`POST`). Validado na borda (`^[A-Za-z0-9-]{1,64}$`) para bloquear path-traversal antes de alcançar o simulador.","schema":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$","maxLength":64}}],"responses":{"200":{"description":"Simulação encontrada. Contém o plano completo de pagamento calculado no momento da criação.","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 — falha de validação de Bean Validation (campos obrigatórios ausentes, formatos incorretos, CPF com dígitos errados, etc.). O campo `errors` contém um mapa `{ \"campo\": \"mensagem\" }` para cada campo inválido. O campo `title` é sempre `\"Bean validation error\"` e `detail` é sempre `\"One or more fields were invalid. See 'errors' for details.\"`.\nRejeições de regra de negócio também chegam como `400`, com `errorCode` próprio (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Quando a rejeição aponta um campo do request, ela traz o mesmo `errors` e o mesmo `detail`; quando não há campo associado, `errors` é omitido e `detail` é o reason phrase do status.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"401":{"description":"Não autenticado — JWT ausente, inválido ou expirado. Autentique-se e inclua o token no header `Authorization: Bearer <token>`.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"404":{"description":"Simulação não encontrada para o `simulationId` informado, ou não pertence ao originator autenticado (errorCode `SIMULATION_NOT_FOUND`).","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/>" %}
