> 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.md). # API GTFgts API pública do GTFgts para parceiros (originators) operarem o crédito com **garantia FGTS** de forma programática e segura — submissão assíncrona de operações FGTS junto à Caixa, simulação de empréstimo, cadastro de webhook e recebimento dos resultados por notificação. Os contratos completos em formato OpenAPI estão disponíveis nos links abaixo: {% file src="/files/MbsNIH6BxXc3dsN0FszR" %} API REST — submissão de operações, simulações e cadastro de webhook. {% endfile %} {% file src="/files/GPUK6EysPAyT5TXeDdEd" %} Contrato de entrega de webhook — o que o originator recebe a cada resultado de operação. {% endfile %} Coleções Postman prontas para importar (ambiente de homologação): {% file src="/files/OaLcSyEbJ9ibwMnkwdkI" %} GTFgts — coleção Postman (API REST do originator, todos os endpoints). {% endfile %} {% file src="/files/7z2BSLdDWJHwOLgnprij" %} GTFgts — exemplos de payload de webhook (todos os eventos de operação FGTS e formalização). {% endfile %} Para testar o receptor de webhook, use a coleção de eventos em [Webhooks](/desenvolvedores/api-gtfgts/webhooks.md#collection-postman). *** ## Visão geral O GTFgts é a API de operações FGTS da Giro.Tech. O originator autentica-se por **JWT**, submete operações FGTS (averbação, manutenção de garantia, cancelamento de reserva, consultas de saldo, valor reservado e protocolos) e recebe o resultado de forma **assíncrona**. A plataforma processa cada operação junto à Caixa e devolve o desfecho ao originator por **webhook** e/ou por **polling**. A integração é composta por **dois contratos**: | Contrato | O que é | Quem chama | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------- | | **API REST** | Endpoints `/api/v1/**` para submeter operações, consultar status, simular e gerenciar o cadastro de webhook. | O originator chama a Giro.Tech. | | **Entrega de webhook** | Notificações HTTP `POST` que a Giro.Tech envia ao originator com o resultado de cada operação. | A Giro.Tech chama o originator. | ### Principais capacidades * Submissão assíncrona de operações FGTS junto à Caixa (averbação, manutenção de garantia, cancelamento de reserva, consultas) * **Formalização de contrato CCB** — submissão síncrona (`POST /api/v1/fgts/contracts`) com saga assíncrona até desembolso * Consulta de saldo FGTS com **resposta oportunista em cache** (`200` quando disponível; `202` é o caminho padrão) * Consulta em **lote** (prioridade `DEFERRED`) para grandes volumes * Acompanhamento do desfecho por **polling** (`requestId` / `contractNumber`) e por **consulta de protocolo** Caixa * Recebimento dos resultados por **webhook** (entrega *at-least-once* com retry) * Simulação de empréstimo com garantia FGTS * CRUD do **cadastro de webhook** escopado ao originator *** ## Modelo assíncrono Toda operação FGTS segue o mesmo ciclo: o originator **submete** a operação, recebe um `202 Accepted` com um `requestId`, e acompanha o desfecho por **webhook** (recomendado) ou por **polling**. ```mermaid sequenceDiagram participant O as Originator participant G as GTFgts API participant C as Caixa O->>G: POST /api/v1/fgts/endorsements G-->>O: 202 Accepted { requestId, status: QUEUED } G->>C: processa a operação (assíncrono) C-->>G: resultado (protocolo / saldo / erro) G-->>O: POST webhook { source, eventType, data } Note over O,G: alternativa: GET /api/v1/fgts/operations/{requestId} (polling) ``` | Etapa | Endpoint | Resultado | | --------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------- | | **1. Submeter** | `POST /api/v1/fgts/{operação}` | `202 Accepted` com `requestId` e `status: QUEUED` (ou `200` com resposta em cache de saldo) | | **2a. Webhook** | entrega para a URL cadastrada | `WebhookEnvelope` com `source`, `eventType` e `data` | | **2b. Polling** | `GET /api/v1/fgts/operations/{requestId}` | `status` atual e, em estado terminal, `result` ou `error` | {% hint style="info" %} O `requestId` é a **chave de correlação e de idempotência** de ponta a ponta: use-o para casar a notificação de webhook com a submissão e para deduplicar reentregas. Ver [Idempotência](/desenvolvedores/api-gtfgts/guias/idempotencia.md). {% endhint %} Detalhes completos do fluxo, dos estados (`QUEUED → … → COMPLETED/FAILED/EXPIRED`) e do polling em [Fluxo assíncrono e polling](/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md). *** ## Operações FGTS Cada tipo de operação é um endpoint dedicado. Todas seguem o mesmo corpo de entrada (`cpf` + `payload` específico da Caixa) e o mesmo retorno `202`. | Operação | Endpoint | Prioridade | | ---------------------------------- | -------------------------------------------- | ---------------------------- | | Consulta de saldo FGTS | `POST /api/v1/fgts/balance-queries` | `NORMAL` (resposta em cache) | | Consulta de saldo em lote | `POST /api/v1/fgts/batch/balance-queries` | `DEFERRED` | | Averbação | `POST /api/v1/fgts/endorsements` | `NORMAL` | | Manutenção de garantia | `POST /api/v1/fgts/guarantee-maintenances` | `NORMAL` | | Cancelamento de reserva | `POST /api/v1/fgts/reserve-cancellations` | `NORMAL` | | Consulta de valor reservado | `POST /api/v1/fgts/reserve-value-queries` | `NORMAL` | | Consulta de protocolos por reserva | `POST /api/v1/fgts/reserve-protocol-queries` | `NORMAL` | Visão detalhada de cada operação em [Operações FGTS](/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md) e na [API Reference](/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts.md). *** ## Prioridades e rate limit A API aplica rate limit por originator. Acima da cota normal, a operação ainda pode ser admitida com prioridade `DEFERRED` (`202`); acima do limite, a requisição é rejeitada com `429` e o header `Retry-After`. Ver [Prioridades e rate limit](/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md). *** ## Webhooks A cada resultado de operação, a Giro.Tech envia um `POST` para a URL cadastrada com um `WebhookEnvelope` (`source`, `eventType`, `data`). A entrega é *at-least-once* com retry e back-off exponencial; um header estático `{authKey}: {authValue}` autentica a chamada. Consulte: * [Eventos](/desenvolvedores/api-gtfgts/webhooks/eventos.md) — catálogo de `source`/`eventType` e agrupamento por desfecho * [Payloads](/desenvolvedores/api-gtfgts/webhooks/payloads.md) — estrutura do `data`, `OperationError` e exemplos JSON * [Configuração via API](/desenvolvedores/api-gtfgts/webhooks/configuracao-via-api.md) — como cadastrar a URL e filtrar eventos * [Segurança e exemplos](/desenvolvedores/api-gtfgts/webhooks/seguranca-e-exemplos.md) — header de autenticação e validação no seu endpoint * [Retry e garantias de entrega](/desenvolvedores/api-gtfgts/webhooks/retry-e-garantias.md) — semântica `2xx/4xx/5xx` e back-off *** ## Próximos passos 1. [Configurar ambientes e autenticação](/desenvolvedores/api-gtfgts/guias/ambientes-e-autenticacao.md) 2. [Entender o fluxo assíncrono e o polling](/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md) 3. [Cadastrar o webhook do originator](/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/criar-cadastro-webhook.md) 4. [Submeter uma averbação FGTS](/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md) 5. [Consultar o status da operação](/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) 6. [Glossário](/desenvolvedores/api-gtfgts/guias/glossario.md)
{% embed url="" %}