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.
Identidade e correlaçã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.
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).
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.
Status e ciclo de vida
Detalhes em Fluxo assíncrono e polling.
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
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
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
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.
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.
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.
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.
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