> 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/guias/sandbox-mock-caixa.md).

# Sandbox de Testes (Mock da Caixa)

O **sandbox** permite que você controle, em **homologação**, como a Caixa responde às suas operações FGTS — sem depender do comportamento real ou de um CPF específico. Você define o resultado (saldo disponível, averbação acatada, erro com um código específico, protocolo não encontrado, etc.) e a API GTFgts passa a responder conforme o cenário que você configurou.

Use-o para validar toda a integração — inclusive os caminhos de erro, difíceis de reproduzir com dados reais — antes de ir para produção.

{% hint style="warning" %}
O sandbox existe **apenas em homologação** (`https://ingress.gtfgts.staging.giro.tech`). Em produção, qualquer chamada a `/api/v1/mock/caixa/**` retorna `404` — lá as respostas vêm sempre da Caixa real.
{% endhint %}

## Como funciona

O sandbox é uma "mesa de controle": você **pré-configura o desfecho** de cada operação FGTS e depois chama a operação normalmente. O ciclo é sempre o mesmo:

```
1. Configurar o cenário   →  PUT /api/v1/mock/caixa/... (ou aplicar um preset)
2. Executar a operação    →  POST /api/v1/fgts/... (saldo, averbação, ...)
3. Observar o resultado   →  webhook  ou  GET /api/v1/fgts/operations/{requestId}
```

Pontos-chave do modelo:

* **Escopo do seu originator.** Tudo é isolado pelo seu JWT. Você só enxerga e altera o seu próprio sandbox — **não há `originatorId` no path nem no corpo**.
* **Dois níveis de cenário:**
  * **Default** — vale para qualquer CPF do seu escopo que não tenha configuração própria.
  * **Por CPF** — sobrepõe o default para um CPF específico.
* **Precedência.** O cenário efetivo de um CPF é o *merge* do default com o que você definiu para aquele CPF (o **por-CPF vence**). Consulte o resultado com `GET /cpfs/{cpf}`.
* **Assíncrono.** Exceto a consulta de saldo com cache, as operações FGTS respondem `202 Accepted` e o desfecho chega depois — por **webhook** ou **polling**. Portanto o resultado que você configura aqui aparece no *evento terminal*, não na resposta imediata. Veja [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).

## Autenticação e base

O sandbox usa o **mesmo JWT** do originator das demais operações (veja [Ambientes e Autenticação](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/ambientes-e-autenticacao.md)). Todos os endpoints ficam sob:

```
https://ingress.gtfgts.staging.giro.tech/api/v1/mock/caixa
```

Envie sempre `Authorization: Bearer {{seu_token_jwt}}`. Sem token válido → `401`; com um token que não seja de originator → `403`.

## Operações

O `operation` no path identifica qual operação FGTS você está configurando:

| `operation`      | Operação FGTS               | Endpoint FGTS correspondente           |
| ---------------- | --------------------------- | -------------------------------------- |
| `balance`        | Consulta de saldo           | `POST /api/v1/fgts/balance-queries`    |
| `endorsement`    | Averbação                   | `POST /api/v1/fgts/endorsements`       |
| `query`          | Consulta de valor reservado | (via Contratos / operações de reserva) |
| `maintenance`    | Manutenção de garantia      | (via Contratos)                        |
| `cancellation`   | Cancelamento de reserva     | (via Contratos)                        |
| `protocol-query` | Consulta por protocolo      | (via Contratos)                        |

## Resultados (`outcome`)

Ao configurar uma operação você escolhe um `outcome`. Cada operação aceita um subconjunto:

| `outcome`     | Operações                                               | O que faz                                                                                        |
| ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `AVAILABLE`   | `balance`                                               | Saldo disponível. Exige `balanceAmount` e `periodCount`.                                         |
| `NO_BALANCE`  | `balance`                                               | Sem saldo (a operação retorna "sem margem").                                                     |
| `ERROR`       | `balance`, `endorsement`, `maintenance`, `cancellation` | Erro de negócio da Caixa. Exige `errorCode` (veja [Códigos de erro](#codigos-de-erro)).          |
| `ACCEPTED`    | `endorsement`, `maintenance`, `cancellation`            | Operação acatada.                                                                                |
| `REJECTED`    | `endorsement`, `maintenance`, `cancellation`            | Operação não acatada.                                                                            |
| `PROCESSING`  | `endorsement`, `maintenance`                            | Fica em processamento (protocolo pendente).                                                      |
| `FOUND`       | `query`, `protocol-query`                               | A consulta encontra o registro.                                                                  |
| `NOT_FOUND`   | `query`, `protocol-query`                               | A consulta não encontra o registro.                                                              |
| `UNAVAILABLE` | qualquer                                                | Força um HTTP status (default `503`) em **todas** as operações daquele CPF. Aceita `httpStatus`. |
| `RAW`         | qualquer (**apenas escopo por CPF**)                    | Devolve um corpo HTTP exato que você fornece. Exige `httpStatus` e `body`.                       |

Consulte sempre o catálogo vigente do seu escopo em `GET /outcomes` — ele reflete exatamente o que cada operação aceita.

### Corpo da configuração (`StubRequest`)

O corpo de `PUT /default/operations/{operation}` e `PUT /cpfs/{cpf}/operations/{operation}`:

| Campo           | Tipo                | Obrigatório quando                                                   | Observações                                                              |
| --------------- | ------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `outcome`       | string (enum acima) | **sempre**                                                           | —                                                                        |
| `balanceAmount` | number > 0          | `outcome=AVAILABLE`                                                  | Valor do saldo disponível.                                               |
| `periodCount`   | integer ≥ 1         | `outcome=AVAILABLE`                                                  | Quantidade de períodos/parcelas.                                         |
| `errorCode`     | integer             | `outcome=ERROR`                                                      | Código de erro da Caixa (deve ser válido para a operação — veja abaixo). |
| `httpStatus`    | integer             | `outcome=RAW` (obrigatório); `UNAVAILABLE` (opcional, default `503`) | —                                                                        |
| `body`          | object              | `outcome=RAW`                                                        | Corpo JSON exato a devolver.                                             |
| `latencyMs`     | integer ≥ 0         | opcional                                                             | Latência artificial em milissegundos, para testar timeouts.              |

Se faltar um campo obrigatório ou o `outcome` não valer para a operação, o sandbox responde `400` com `errorCode` `MOCK_INVALID_OUTCOME`.

## Configurando um cenário

### Erro com código (`ERROR`)

```bash
# Averbação passa a falhar com o código 11 (CPF não operável) para este CPF
curl -X PUT 'https://ingress.gtfgts.staging.giro.tech/api/v1/mock/caixa/cpfs/12345678901/operations/endorsement' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' \
  -H 'Content-Type: application/json' \
  -d '{ "outcome": "ERROR", "errorCode": 11 }'
```

### Saldo disponível (`AVAILABLE`)

```bash
curl -X PUT 'https://ingress.gtfgts.staging.giro.tech/api/v1/mock/caixa/cpfs/12345678901/operations/balance' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' \
  -H 'Content-Type: application/json' \
  -d '{ "outcome": "AVAILABLE", "balanceAmount": 5000.00, "periodCount": 8 }'
```

### Averbação acatada / recusada / em processamento

```bash
# Acatada
-d '{ "outcome": "ACCEPTED" }'
# Recusada
-d '{ "outcome": "REJECTED" }'
# Em processamento (protocolo fica pendente; útil para testar polling)
-d '{ "outcome": "PROCESSING" }'
```

### Indisponibilidade / lentidão

```bash
# Todas as operações deste CPF passam a retornar 503
-d '{ "outcome": "UNAVAILABLE", "httpStatus": 503 }'
# Qualquer cenário pode incluir latência artificial:
-d '{ "outcome": "ACCEPTED", "latencyMs": 3000 }'
```

### Cenário default (vale para todos os CPF sem configuração própria)

Troque `/cpfs/{cpf}/operations/{operation}` por `/default/operations/{operation}`:

```bash
curl -X PUT 'https://ingress.gtfgts.staging.giro.tech/api/v1/mock/caixa/default/operations/balance' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' \
  -H 'Content-Type: application/json' \
  -d '{ "outcome": "NO_BALANCE" }'
```

O `outcome` `RAW` **não** é permitido no escopo default (só por CPF).

## Códigos de erro

Quando você usa `outcome: ERROR`, o `errorCode` deve ser um código válido **para aquela operação**. O catálogo completo e vigente está em `GET /codes`. Os mais usados:

### Consulta de saldo (`balance`)

| Código | HTTP | Descrição                                                                              |
| ------ | ---- | -------------------------------------------------------------------------------------- |
| `7`    | 403  | Instituição Fiduciária não possui autorização do Trabalhador para Operação Fiduciária. |
| `8`    | 404  | Trabalhador informado não possui contas de FGTS.                                       |
| `9`    | 400  | Trabalhador não possui adesão ao saque aniversário vigente na data corrente.           |
| `10`   | 400  | Operação não permitida antes de \<data>.                                               |
| `11`   | 400  | Não é possível realizar a operação para o CPF informado.                               |
| `3`    | 500  | Ocorreu um erro inesperado. Tente novamente mais tarde.                                |

### Averbação (`endorsement`)

| Código | HTTP | Descrição                                                                  |
| ------ | ---- | -------------------------------------------------------------------------- |
| `11`   | 400  | Não é possível realizar a operação para o CPF informado.                   |
| `12`   | 400  | Trabalhador não possui saldo disponível para Operação Fiduciária.          |
| `14`   | 400  | Existe uma solicitação de garantia com o mesmo número identificador.       |
| `17`   | 400  | Valor da alienação/cessão superior ao valor disponível para o trabalhador. |
| `37`   | 400  | Trabalhador não possui saldo suficiente para a garantia necessária.        |
| `3`    | 500  | Ocorreu um erro inesperado. Tente novamente mais tarde.                    |

> A lista acima é um recorte. Use `GET /api/v1/mock/caixa/codes` para o catálogo completo por operação (inclui manutenção, cancelamento e consulta por protocolo).

## Presets

Presets aplicam um cenário completo de uma vez — atalhos para os casos mais comuns. Aplique ao **default** (`POST /presets/{name}`) ou a um **CPF** (`POST /cpfs/{cpf}/presets/{name}`):

| Preset                             | Efeito observável                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
| `happy`                            | Tudo bem-sucedido: saldo com valor, averbação acatada, consulta encontra.                 |
| `margem_zero`                      | Consulta de saldo sem margem (`NO_BALANCE`).                                              |
| `averbacao_nok`                    | Averbação recusada (`REJECTED`).                                                          |
| `averbacao_duplicada`              | Averbação com erro **14** (identificador de solicitação duplicado).                       |
| `consulta_nao_encontrada`          | Consulta de valor reservado não encontra (`NOT_FOUND`).                                   |
| `caixa_indisponivel`               | Todas as operações retornam `503`.                                                        |
| `lentidao`                         | Todas as respostas com \~3s de latência.                                                  |
| `login_fail`                       | Falha de autenticação na Caixa.                                                           |
| `manutencao_nok`                   | Manutenção recusada (`REJECTED`).                                                         |
| `cancelamento_nok`                 | Cancelamento recusado (`REJECTED`).                                                       |
| `protocolo_nao_encontrado`         | Consulta por protocolo não encontra (`NOT_FOUND`).                                        |
| `saldo_sem_autorizacao_fiduciaria` | Consulta de saldo com erro **7** (instituição fiduciária sem autorização do trabalhador). |
| `saldo_operacao_bloqueada`         | Consulta de saldo com erro **10** (operação não permitida antes da data).                 |
| `averbacao_cpf_nao_operavel`       | Averbação com erro **11** (CPF não operável).                                             |
| `averbacao_erro_transiente`        | Averbação com erro transitório **3** (tente novamente mais tarde).                        |

```bash
# Aplicar um preset a um CPF específico:
curl -X POST 'https://ingress.gtfgts.staging.giro.tech/api/v1/mock/caixa/cpfs/12345678901/presets/averbacao_cpf_nao_operavel' \
  -H 'Authorization: Bearer {{seu_token_jwt}}'
```

## Referência de endpoints

Base: `/api/v1/mock/caixa`. Todos exigem `Authorization: Bearer {{seu_token_jwt}}`.

| Método         | Path                                 | Body                   | Resposta                                                                    |
| -------------- | ------------------------------------ | ---------------------- | --------------------------------------------------------------------------- |
| `GET`          | `/outcomes`                          | —                      | `outcome`s aceitos por operação.                                            |
| `GET`          | `/codes`                             | —                      | Catálogo de códigos de erro por operação.                                   |
| `GET`          | `/default`                           | —                      | Cenário default do seu escopo + overrides por CPF.                          |
| `PUT`          | `/default/operations/{operation}`    | `StubRequest`          | Define o desfecho default de uma operação. `200`.                           |
| `GET`          | `/cpfs/{cpf}`                        | —                      | Cenário **efetivo** de um CPF (default + override, já mesclado).            |
| `PUT`          | `/cpfs/{cpf}/operations/{operation}` | `StubRequest`          | Define o desfecho de `(CPF, operação)`. `200`.                              |
| `DELETE`       | `/cpfs/{cpf}/operations/{operation}` | —                      | Remove o stub de uma operação do CPF. `204`.                                |
| `DELETE`       | `/cpfs/{cpf}`                        | —                      | Remove todo o cenário do CPF. `204`.                                        |
| `GET`          | `/presets`                           | —                      | Lista os presets disponíveis (`name`, `label`, `description`).              |
| `POST`         | `/presets/{name}`                    | —                      | Aplica um preset ao cenário default. `200`.                                 |
| `POST`         | `/cpfs/{cpf}/presets/{name}`         | —                      | Aplica um preset a um CPF. `200`.                                           |
| `GET` / `POST` | `/rate-limit`                        | `{ "rps": n }` no POST | Consulta / define o rate-limit do seu escopo (`rps: 0` desabilita).         |
| `GET`          | `/requests?limit={n}`                | —                      | Log das últimas requisições do seu originator (`n` de 1 a 500, default 50). |
| `POST`         | `/reset`                             | —                      | Reseta **todo** o cenário do seu escopo. `204`.                             |

`operation` ∈ `balance`, `endorsement`, `query`, `maintenance`, `cancellation`, `protocol-query`. `cpf` é sempre 11 dígitos.

### Inspecionar e resetar

`GET /cpfs/{cpf}` devolve o cenário **efetivo** daquele CPF (o resultado do merge default + override), útil para confirmar o que está configurado antes de rodar a operação. `GET /requests` mostra as últimas chamadas que a sua integração fez ao mock (bom para depurar). `POST /reset` limpa tudo e volta ao happy-path.

## Exemplos ponta a ponta

### A) Saldo disponível

**1. Configure** o saldo do CPF:

```bash
curl -X PUT 'https://ingress.gtfgts.staging.giro.tech/api/v1/mock/caixa/cpfs/12345678901/operations/balance' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' -H 'Content-Type: application/json' \
  -d '{ "outcome": "AVAILABLE", "balanceAmount": 5000.00, "periodCount": 8 }'
```

**2. Execute** a consulta de saldo:

```bash
curl -X POST 'https://ingress.gtfgts.staging.giro.tech/api/v1/fgts/balance-queries' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' -H 'Content-Type: application/json' \
  -d '{ "cpf": "12345678901" }'
```

**3. Observe** o resultado. Saldo é a única operação com fast-path de cache: pode voltar `200` inline, ou `202 { "requestId": "...", "status": "QUEUED" }` e o desfecho chega no webhook `BALANCE_QUERY_COMPLETED` (ou por `GET /api/v1/fgts/operations/{requestId}`). O `result` tem o formato:

```json
{
  "workerCpf": "12345678901",
  "balanceDate": "2026-05-20",
  "hasDisregardedBalance": false,
  "activeRequestCount": 2,
  "periods": [
    { "transferDate": "2026-05-01", "amount": 1250.50 }
  ]
}
```

Detalhes do contrato de saldo em [Submeter consulta de saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md).

### B) Averbação com erro (código 11)

**1. Configure** o erro (via stub ou preset):

```bash
curl -X PUT 'https://ingress.gtfgts.staging.giro.tech/api/v1/mock/caixa/cpfs/12345678901/operations/endorsement' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' -H 'Content-Type: application/json' \
  -d '{ "outcome": "ERROR", "errorCode": 11 }'
# equivalente: POST .../cpfs/12345678901/presets/averbacao_cpf_nao_operavel
```

**2. Execute** a averbação:

```bash
curl -X POST 'https://ingress.gtfgts.staging.giro.tech/api/v1/fgts/endorsements' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' -H 'Content-Type: application/json' \
  -d '{ "cpf": "12345678901", "operationKind": "FIDUCIARY_ASSIGNMENT",
        "periods": [ { "transferDate": "2030-09-01", "amount": 1234.56 } ] }'
```

A resposta imediata é sempre `202 { "requestId": "...", "status": "QUEUED" }`.

**3. Observe** o desfecho — que é **assíncrono**. Via webhook `ENDORSEMENT_FAILED` ou `GET /api/v1/fgts/operations/{requestId}`, com `status: FAILED` e o erro no campo `error`. O **código da Caixa que você configurou** aparece em `error.originalErrors[].code`:

```json
{
  "requestId": "...",
  "status": "FAILED",
  "error": {
    "code": "ENDORSEMENT_DENIED",
    "message": "Averbação negada pelo provedor Caixa",
    "originalErrors": [
      { "provider": "CAIXA", "code": "11",
        "description": "Não é possível realizar a operação para o CPF informado.",
        "httpStatus": 400 }
    ]
  }
}
```

O `error.code` é um rótulo canônico e estável da GTLab; o **código cru da Caixa** (`11`) fica em `originalErrors[].code`. Entenda a estrutura de erros em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#operationerror) e o modelo assíncrono em [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).

## Rate-limit do sandbox

`GET /rate-limit` mostra o limite atual do seu escopo; `POST /rate-limit` o ajusta. Use `rps: 0` para desabilitar o limite durante os testes:

```bash
curl -X POST 'https://ingress.gtfgts.staging.giro.tech/api/v1/mock/caixa/rate-limit' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' \
  -H 'Content-Type: application/json' \
  -d '{ "rps": 0 }'
```

## Erros do sandbox

Além dos erros de borda padrão (`401` sem JWT válido — veja [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md)), o sandbox pode retornar:

| `errorCode`                  | Quando                                                                                                     |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `MOCK_INVALID_OPERATION`     | `operation` ou preset fora do conjunto aceito.                                                             |
| `MOCK_INVALID_OUTCOME`       | `outcome` incompatível com a operação, campo obrigatório ausente, ou `errorCode` inválido para a operação. |
| `MOCK_SIMULATOR_UNAVAILABLE` | Sandbox temporariamente indisponível — tente novamente.                                                    |

## Coleção Postman e OpenAPI

A coleção Postman pública já inclui as requisições do sandbox, prontas para importar (ambiente de homologação):

O contrato completo está no OpenAPI da API GTFgts (tag `sandbox`):
