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

# Glossário

Esta página reúne os principais termos usados na documentação e na API GTFgts — a API de operações FGTS junto à Caixa para originators. Os termos estão agrupados por domínio para facilitar a leitura. Quando um termo tem uma página dedicada, há um link para ela.

{% hint style="info" %}
Os nomes em `monospace` (ex.: `requestId`, `COMPLETED`, `CAIXA_CALL`) são valores e campos usados na API; os termos em português descrevem o conceito de negócio correspondente.
{% endhint %}

***

## Identidade e correlação

| Termo                                              | Definição                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **originator / originador**                        | O parceiro integrado à GTFgts que submete operações FGTS via API. Autentica-se por JWT; diversas configurações (permissões, cadastro de webhook, rate limit) são definidas **por originator** no onboarding.                                                                                                                                                                                                                                 |
| **`requestId`**                                    | Identificador único (UUID) da operação FGTS, atribuído pela API na admissão (`202`). É a **chave de correlação e de idempotência** de ponta a ponta: usado no polling (`GET /api/v1/fgts/operations/{requestId}`) e como chave para deduplicar reentregas de webhook.                                                                                                                                                                        |
| **`reserveIdentifier`**                            | Identificador lógico da reserva FGTS associada a uma operação. No webhook, é promovido de `result.reserveIdentifier` ao nível superior do `data` quando presente; ausente em operações sem reserva.                                                                                                                                                                                                                                          |
| **protocolo / protocolo Caixa (`protocolNumber`)** | Número gerado pela Caixa como comprovante de uma operação (averbação, manutenção, cancelamento). É o `result` das operações que geram protocolo.                                                                                                                                                                                                                                                                                             |
| **`contractNumber`**                               | Número de negócio do contrato (CCB) gerado pela Giro, **sequencial por originator** — repete entre originators diferentes; o acesso é sempre escopado pelo token. Atribuído na admissão pela saga de formalização e devolvido no `201` da submissão. Chave de correlação dos eventos de webhook `source = CONTRACT` — um mesmo contrato gera **vários** `requestId`. Não confundir com `clientReference` nem com o header `Idempotency-Key`. |
| **`clientReference`**                              | Id do cliente **no originador** (opcional), fornecido na submissão e ecoado nas respostas e nos eventos de webhook `source = CONTRACT` para correlação/exibição. **Não** é chave de deduplicação.                                                                                                                                                                                                                                            |

***

## Operações FGTS

Detalhes em [Operações FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md).

| Termo                                  | Definição                                                                                                                                                                                                                                                                    |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **consulta de saldo**                  | Operação que consulta o saldo/margem FGTS de um trabalhador (`POST /api/v1/fgts/balance-queries`). Única operação com resposta em cache: havendo valor recente em cache, responde `200` síncrono; caso contrário, responde `202`.                                            |
| **consulta de saldo em lote**          | Mesma consulta de saldo com prioridade `DEFERRED` (`POST /api/v1/fgts/batch/balance-queries`). Indicada para processamento fora do tempo real (ex.: sincronização noturna), sem competir com o tráfego em tempo real.                                                        |
| **valor reservado**                    | Consulta do valor reservado de uma reserva FGTS (`POST /api/v1/fgts/reserve-value-queries`); o `result` é uma `ReservedValueResult` com os períodos da reserva.                                                                                                              |
| **consulta de protocolos por reserva** | Lista todos os protocolos associados a uma reserva FGTS (`POST /api/v1/fgts/reserve-protocol-queries`); o `result` é uma `ProtocolListResult` com a lista de protocolos e seus status.                                                                                       |
| **averbação (endorsement)**            | Operação que averba a operação FGTS junto à Caixa (`POST /api/v1/fgts/endorsements`); gera um `ProtocolResult` quando concluída.                                                                                                                                             |
| **manutenção de garantia**             | Operação de amortização ou quitação da garantia FGTS (`POST /api/v1/fgts/guarantee-maintenances`); gera um `ProtocolResult`.                                                                                                                                                 |
| **cancelamento de reserva**            | Operação que cancela uma reserva FGTS (`POST /api/v1/fgts/reserve-cancellations`); gera um `ProtocolResult` como comprovante do cancelamento.                                                                                                                                |
| **cancelamento de contrato**           | Operação que cancela um **contrato FGTS já ativo** por desistência ou quitação antecipada (`POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations`), levando à desaverbação da garantia na Caixa; passa por análise interna da Giro e gera um `ProtocolResult`. |

***

## Formalização (contratos)

Detalhes em [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md) e [Contratos (Formalização)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md).

| Termo                                          | Definição                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **contrato (formalização)**                    | Proposta de empréstimo com garantia FGTS, submetida pelo originador (uma CCB) para a Giro **formalizar**: averbar na Caixa, enviar ao provedor bancário (GTBanker) e acompanhar o pagamento ao tomador. Submetido em `POST /api/v1/fgts/contracts`.                                                                                                                                                                                                                                  |
| **Modo A / Modo B**                            | Define se o **PDF assinado da CCB** vai junto na submissão. **Modo A**: PDF assinado no próprio submit (`signedDocumentBase64`) → status inicial `RECEIVED`. **Modo B**: contrato submetido **sem** o PDF → status inicial `AWAITING_SIGNED_DOCUMENT`; o documento é anexado depois via `POST .../documents`.                                                                                                                                                                        |
| **conta de desembolso (disbursement account)** | Conta (PIX ou bancária) que recebe o valor desembolsado ao tomador. Pode exigir revisão quando o provedor recusa a conta — sinalizado pelo evento `CONTRACT_PAYMENT_REVISION`; corrija via `PUT .../disbursement-account`.                                                                                                                                                                                                                                                           |
| **CCB**                                        | Cédula de Crédito Bancário — o documento (PDF) do contrato. Dois artefatos distintos ficam disponíveis para download: o **PDF assinado enviado pelo originador** em `GET .../documents/signed` (disponível assim que anexado), e o **documento gerado pela Giro** ao final da formalização em `GET .../documents/template` (disponível após o contrato chegar a `PENDING_DISBURSEMENT`). Ambos retornam uma URL temporária (presigned).                                              |
| **status do contrato**                         | Ciclo de vida da formalização: `RECEIVED`, `AWAITING_SIGNED_DOCUMENT`, `PENDING_ENDORSEMENT`, `ENDORSED`, `ENDORSEMENT_REJECTED`, `PENDING_FORMALIZATION`, `PENDING_CCB_CONFIRMATION`, `PENDING_DISBURSEMENT`, `DISBURSED`, `REVERSING_ENDORSEMENT`, `FORMALIZATION_FAILED`, `REVERSAL_FAILED`, `CANCELLED`. Distinto do `status` assíncrono das operações FGTS. Detalhes em [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md). |

{% hint style="info" %}
Não confunda **`contractNumber`** (número do contrato, sequencial por originator — ver [Identidade e correlação](#identidade-e-correlacao)) com **`clientReference`** (id do cliente que você fornece, opcional) nem com o **`Idempotency-Key`** (header de deduplicação da submissão). São três identificadores distintos; o acesso é sempre escopado pelo token.
{% endhint %}

***

## Status e ciclo de vida

Detalhes em [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).

| Termo                     | Definição                                                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **`COMPLETED`**           | Estado terminal de sucesso. O campo `result` está presente.                                                       |
| **`FAILED`**              | Estado terminal de falha — operação negada ou com erro. O campo `error` (`OperationError`) está presente.         |
| **`FAILED_NEEDS_MANUAL`** | Estado terminal de falha que requer **intervenção manual** da operação. O campo `error` está presente.            |
| **`EXPIRED`**             | Estado terminal — a operação expirou aguardando resposta da Caixa. O campo `error` está presente.                 |
| **`NEEDS_VERIFICATION`**  | Estado intermediário (não-terminal) — o desfecho é incerto e pode exigir verificação adicional antes de concluir. |
| **`source`**              | Origem do resultado de uma operação concluída: `CAIXA_CALL` (saldo apurado na Caixa) ou `NA` (não aplicável).     |

***

## Enums e status (de-para Caixa)

A API entrega os valores de status/tipo como **string em inglês** (legível); a Caixa usa internamente códigos inteiros. As tabelas abaixo mostram a correspondência (útil para suporte/depuração). A API **nunca** expõe o código inteiro nesses campos.

**`protocolStatus`**

| Valor (API)    | Código Caixa | Significado                    |
| -------------- | ------------ | ------------------------------ |
| `ENDORSED`     | 1            | Garantida                      |
| `PROCESSING`   | 2            | Em processamento               |
| `REJECTED`     | 3            | Não acatado                    |
| `NOT_FOUND`    | 4            | Não encontrado                 |
| `RATE_LIMITED` | 5            | Limite de requisições atingido |

**`periodStatus`**

| Valor (API)                         | Código Caixa | Significado                             |
| ----------------------------------- | ------------ | --------------------------------------- |
| `GUARANTEED`                        | 1            | Garantida                               |
| `REPAID`                            | 2            | Quitada                                 |
| `CANCELLED`                         | 3            | Cancelada                               |
| `PAID`                              | 4            | Pago                                    |
| `PAYMENT_IN_PROGRESS`               | 5            | Em processo de pagamento                |
| `PROCESSING`                        | 6            | Em processamento                        |
| `REJECTED`                          | 7            | Não acatado                             |
| `CANCELLATION_IN_PROGRESS`          | 8            | Em processo de cancelamento             |
| `PAYMENT_CANCELLED_FRAUD_SUSPECTED` | 9            | Pagamento cancelado — indício de fraude |

**`operationKind`** (o significado depende do contexto da operação)

* Reserva/averbação: `FIDUCIARY_ASSIGNMENT` (1, Cessão Fiduciária), `FIDUCIARY_ALIENATION` (2, Alienação Fiduciária)
* Manutenção de garantia: `AMORTIZATION` (1, Amortização), `SETTLEMENT` (2, Quitação)

**`requestType`**

| Valor (API)                             | Código Caixa | Significado                            |
| --------------------------------------- | ------------ | -------------------------------------- |
| `RESERVE_REQUEST`                       | 1            | Solicitação de Reserva                 |
| `RESERVE_CANCELLATION_REQUEST`          | 2            | Cancelamento da Solicitação de Reserva |
| `RESERVE_GUARANTEE_MAINTENANCE_REQUEST` | 3            | Manutenção da Garantia da Reserva      |

***

## Prioridades e rate limit

Detalhes em [Prioridades e rate limit](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md).

| Termo          | Definição                                                                                                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`NORMAL`**   | Prioridade de tempo real das operações individuais admitidas dentro da cota normal.                                                                                                                                           |
| **`DEFERRED`** | Prioridade rebaixada — aplicada à consulta em **lote** (`/batch/balance-queries`) e a operações admitidas acima da cota normal. Processada sem competir com o tráfego em tempo real.                                          |
| **rate limit** | Controle de volume de requisições por originator. Acima da cota normal, a operação pode ser **admitida** (`202`) com prioridade `DEFERRED`; acima do limite, a requisição é **rejeitada** com `429` e o header `Retry-After`. |

***

## Webhooks

Detalhes em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) e [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

| Termo                 | Definição                                                                                                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **webhook**           | Notificação HTTP `POST` que a Giro.Tech envia à URL cadastrada do originator a cada resultado de operação, evitando polling. Entrega *at-least-once* com retry e back-off exponencial.       |
| **`WebhookEnvelope`** | Estrutura do corpo do webhook, com `source` (categoria da operação), `eventType` (evento derivado) e `data` (payload de negócio com `requestId`, `status`, `source`, e `result` ou `error`). |

***

## Erros

Detalhes em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

| Termo                | Definição                                                                                                                                                                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`ProblemDetail`**  | Estrutura de **erro de borda** (RFC 7807, `application/problem+json`) das falhas de requisição HTTP (validação, auth, rate limit, indisponibilidade). Traz `errorCode` (código canônico GTLab) e `timestamp`.                                                         |
| **`OperationError`** | Estrutura do **erro de operação** Caixa — aparece apenas no campo `error` do polling e do webhook quando a operação falhou. Tem `code` (código GTLab mapeado), `message` e `originalErrors[]` (erros crus da Caixa, ex.: `code: "14"`). **Não** é um `ProblemDetail`. |

***

## Integração

Detalhes em [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).

| Termo                 | Definição                                                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`Idempotency-Key`** | Header opcional na submissão de operações (máx. 100 caracteres, escopo por originator). Reenviar a mesma chave devolve o `requestId` existente, sem republicar nem reprocessar a operação. |

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