Pular para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.


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.

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 e Contratos (Formalização).

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.

Não confunda contractNumber (número do contrato, sequencial por originator — ver Identidade e correlação) 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.


Status e ciclo de vida

Detalhes em Fluxo assíncrono e polling.

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.

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 e Payloads.

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.

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.

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.

Atualizado