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

Eventos

Catálogo dos eventos de webhook do GTFgts: quais source e eventType existem e como se agrupam por desfecho. Para a estrutura do corpo entregue (data, result, error) e os exemplos JSON de cada evento, ver Payloads.

Todos os valores são extraídos do contrato de entrega (gtfgts-webhook.openapi.yaml).


Formato do envelope

Toda notificação é enviada com o corpo no formato envelope, com três campos:

{
  "source": "ENDORSEMENT",
  "eventType": "ENDORSEMENT_FAILED",
  "data": { ... }
}
  • source — categoria da operação que produziu o evento.

  • eventType — tipo do evento (combinação de operação + status + conteúdo do resultado). Use-o para rotear o tratamento e para filtrar apenas os eventos que interessam.

  • data — payload do resultado da operação. Sua estrutura está documentada em Payloads.


Valores de source

O source no envelope identifica a categoria da operação que originou o evento.

source

Operação

BALANCE_QUERY

Consulta de saldo FGTS.

ENDORSEMENT

Averbação.

MAINTAIN_GUARANTEE

Manutenção de garantia.

CANCEL_RESERVE

Cancelamento de reserva.

QUERY_RESERVED_VALUE

Consulta de valor reservado.

LIST_PROTOCOLS_BY_ID

Consulta de protocolos por reserva.

QUERY_PROTOCOL_STATUS

Consulta de status por protocolo.

CONTRACT

Saga de formalização de contrato (CCB). Eventos de milestone produzidos pelo serviço de formalização — não derivam de uma operação FGTS-Caixa. Ver Eventos de formalização de contrato.


Valores de eventType

O eventType é derivado da combinação operação + status + conteúdo do result. São 28 valores para as operações FGTS-Caixa, agrupados por operação. O sufixo indica o desfecho (a saga de formalização de contrato adiciona outros 14 eventos CONTRACT_*, com catálogo próprio — ver Eventos de formalização de contrato):

  • *_COMPLETED — operação concluída com sucesso. O payload traz result (resultado opaco da operação).

  • *_FAILED — operação negada/com erro. O payload traz error (OperationError).

  • *_NEEDS_VERIFICATION — a operação expirou sem desfecho (status = EXPIRED), ainda na fila da Giro e sem que houvesse veredito da Caixa. Verifique por polling antes de assumir um resultado.

  • *_UNDER_REVIEW — evento intermediário (não-terminal): a operação foi aceita e entrou em revisão manual da Giro. Ocorre no cancelamento de reserva (CANCEL_RESERVE_UNDER_REVIEW) e na manutenção de garantia (MAINTAIN_GUARANTEE_UNDER_REVIEW). É sempre seguido por um evento terminal (*_COMPLETED ou *_FAILED).

  • ENDORSEMENT_RETRYING — evento intermediário (não-terminal): a Caixa respondeu um código transiente à averbação e a Giro já reagendou a próxima tentativa. Nada foi decidido, e é sempre seguido por um terminal (ENDORSEMENT_COMPLETED ou ENDORSEMENT_FAILED). Em geral não é preciso agir — a exceção é o código 7 em data.retry.lastProviderError, que significa autorização pendente do trabalhador no app do FGTS e depende de uma ação dele para converter. Ver Payloads.

  • *_CANCELLED — a Giro cancelou a operação enquanto ela ainda estava na fila, antes de qualquer chamada à Caixa. Terminal; error.code = OPERATOR_CANCELLED. O cancelamento feito por você (DELETE /api/v1/fgts/operations/{requestId}) não gera este evento. Submeta de novo se ainda precisar.

  • BALANCE_QUERY_NO_BALANCE — consulta de saldo concluída, porém sem saldo FGTS disponível.

Operação

eventType

Consulta de saldo/margem FGTS

BALANCE_QUERY_COMPLETED, BALANCE_QUERY_NO_BALANCE, BALANCE_QUERY_FAILED, BALANCE_QUERY_CANCELLED

Averbação

ENDORSEMENT_COMPLETED, ENDORSEMENT_FAILED, ENDORSEMENT_NEEDS_VERIFICATION, ENDORSEMENT_RETRYING, ENDORSEMENT_CANCELLED

Manutenção de garantia

MAINTAIN_GUARANTEE_UNDER_REVIEW, MAINTAIN_GUARANTEE_COMPLETED, MAINTAIN_GUARANTEE_FAILED, MAINTAIN_GUARANTEE_NEEDS_VERIFICATION, MAINTAIN_GUARANTEE_CANCELLED

Cancelamento de reserva — avulso ou encerramento de contrato

CANCEL_RESERVE_UNDER_REVIEW, CANCEL_RESERVE_COMPLETED, CANCEL_RESERVE_FAILED, CANCEL_RESERVE_NEEDS_VERIFICATION, CANCEL_RESERVE_CANCELLED

Consulta de valor reservado

QUERY_RESERVED_VALUE_COMPLETED, QUERY_RESERVED_VALUE_FAILED, QUERY_RESERVED_VALUE_CANCELLED

Consulta de protocolos por reserva

LIST_PROTOCOLS_COMPLETED, LIST_PROTOCOLS_FAILED, LIST_PROTOCOLS_CANCELLED

Consulta de status por protocolo

QUERY_PROTOCOL_STATUS_COMPLETED, QUERY_PROTOCOL_STATUS_FAILED, QUERY_PROTOCOL_STATUS_CANCELLED


A subscription recebe todos os eventType automaticamente — não há seleção nem filtro de eventos no cadastro. Ver Configuração via API.


Agrupamento por desfecho

A regra é direta: use o eventType para saber qual forma de data esperar. A estrutura do data é a mesma dentro de cada grupo de desfecho (o sufixo do eventType), independentemente da operação. Em vez de decorar 28 formatos diferentes, você lida com sete grupos:

Grupo (sufixo do eventType)

status

Significado

*_COMPLETED

COMPLETED

Operação concluída com sucesso. O resultado vem em result.

BALANCE_QUERY_NO_BALANCE

COMPLETED

Consulta de saldo concluída, mas sem saldo FGTS disponível. Caso especial do COMPLETED.

*_FAILED

FAILED ou EXPIRED

Operação negada/com erro. Não há result. Nas consultas (BALANCE_QUERY, QUERY_RESERVED_VALUE), a expiração também é entregue aqui, com status = EXPIRED.

*_NEEDS_VERIFICATION

EXPIRED

A operação expirou sem desfecho, ainda na fila da Giro. Não há result; o error traz apenas code = EXPIRED_TTL, que marca a expiração e não é veredito da Caixa — verifique por polling antes de assumir um resultado.

*_UNDER_REVIEW

UNDER_REVIEW

Intermediário (não-terminal): o cancelamento de reserva ou a manutenção de garantia entrou em revisão manual da Giro. Não há result nem error — a operação ainda não foi à Caixa. Sempre seguido por um terminal (*_COMPLETED ou *_FAILED).

ENDORSEMENT_RETRYING

RETRYING

Intermediário (não-terminal): a averbação está em retentativa automática da Giro. Não há result; o error traz o código transiente da Caixa que motivou a espera, e retry traz o progresso da janela. Sempre seguido por um terminal.

*_CANCELLED

CANCELLED

Terminal: a Giro cancelou a operação na fila. error.code = OPERATOR_CANCELLED, sem result.

As consultas (BALANCE_QUERY, QUERY_RESERVED_VALUE) não têm desfecho *_NEEDS_VERIFICATION: quando expiram, são entregues como *_FAILED (com status = EXPIRED e error). As operações que alteram estado na Caixa (averbação, manutenção de garantia, cancelamento de reserva) têm o desfecho *_NEEDS_VERIFICATION justamente porque, ao expirar, o resultado real ainda pode ter sido aplicado e precisa ser confirmado.


Eventos de formalização de contrato

Os eventos CONTRACT_* (todos com source = CONTRACT) narram a saga de formalização de um contrato (CCB) e são produzidos pelo serviço de formalização — não derivam de uma operação FGTS-Caixa nem seguem os grupos de desfecho acima. Cada evento marca um milestone do ciclo de vida do contrato.

Diferente dos eventos FGTS, a correlação é feita pelo par data.contractNumber (número de negócio do contrato, sequencial por originator) + data.clientReference (id do cliente que você forneceu): um mesmo contrato gera vários requestId ao longo da saga. Esses eventos são sempre em inglês e não carregam PII crua (sem CPF em claro). A forma do data está em Payloads; o mesmo andamento também pode ser consultado por polling em Consultar contrato.

eventType

Quando

CONTRACT_RECEIVED

Contrato (CCB) recebido e validado pela saga (ack).

CONTRACT_ENDORSED

Averbação/reserva confirmada na Caixa.

CONTRACT_PAYMENT_APPROVAL_REQUIRED

Gate de aprovação de pagamento ativo: o contrato aguarda POST .../payment-approval antes de prosseguir ao GTBanker.

CONTRACT_ENDORSEMENT_REJECTED

A Caixa recusou a averbação. O motivo vem em data.error.

CONTRACT_ENDORSEMENT_RETRYING

Averbação em retentativa automática; o contrato segue em PENDING_ENDORSEMENT. Não é preciso agir.

CONTRACT_SENT_TO_GTBANKER

Payload e documento enviados ao GTBanker.

CONTRACT_FORMALIZED

O GTBanker confirmou o recebimento da CCB.

CONTRACT_PAID

Desembolso confirmado. data.paymentReceiptUrl, quando presente, é o link do comprovante — trate como credencial (ver Payloads).

CONTRACT_FORMALIZATION_FAILED

Falha/recusa no GTBanker. Nem sempre é terminal: o contrato pode seguir retido para nova tentativa — acompanhe o próximo evento.

CONTRACT_PAYMENT_FAILED

Falha no desembolso — informativo (em resolução pela Giro). O motivo vem em data.error.

CONTRACT_PAYMENT_REVISION

Pagamento em revisão: reenvie a conta de desembolso até data.dueAt via PUT .../disbursement-account. data.availableActions diz se só uma conta nova é aceita (NEW_ACCOUNT) ou se a mesma conta pode ser reenviada (RETRY).

CONTRACT_CANCELLATION_REJECTED

Cancelamento pedido via DELETE .../contracts/{contractNumber} interrompido porque o provedor bancário já pagou a CCB. data.status = CANCELLATION_REJECTED, data.error.code = CONTRACT_ALREADY_DISBURSED. O contrato segue para DISBURSED (CONTRACT_PAID). Para desfazer a operação, envie a desistência (SEVEN_DAYS_REGRET).

CONTRACT_CANCELLED

Contrato cancelado. data.reason.code diz por quê: CANCELLED_BY_ORIGINATOR (pedido via DELETE .../contracts/{contractNumber}), ENDORSEMENT_DENIED_NOT_RETRYABLE (recusa da Caixa que não adianta retentar — código 52), ENDORSEMENT_RETRY_WINDOW_EXPIRED (averbação recusada e não retentada dentro da janela) ou DISBURSEMENT_REVISION_EXPIRED (revisão de conta de desembolso expirada sem nova conta; reserva desaverbada).

CONTRACT_DOCUMENT_GENERATED

Documento (PDF) do contrato gerado.

CONTRACT_DOCUMENT_GENERATION_FAILED

A geração da CCB falhou; o contrato fica em DOCUMENT_GENERATION_FAILED. Causa em data.error.message. Acione o suporte. Não é terminal: se a geração for concluída depois (resultado atrasado ou geração refeita pelo suporte), chega CONTRACT_DOCUMENT_GENERATED e o contrato volta a AWAITING_SIGNED_DOCUMENT — siga o fluxo normal do Modo B.

Os eventos CONTRACT_* não seguem os sufixos de desfecho (*_COMPLETED / *_FAILED / *_NEEDS_VERIFICATION / *_UNDER_REVIEW) das operações FGTS-Caixa, e o data.status deles é o marco do contrato (ENDORSED, PAID, CANCELLED…), não COMPLETED/FAILED. Os campos da saga (contractNumber, clientReference e, na revisão, dueDate/dueAt/availableActions/reason) vêm no nível raiz de data. Eles não trazem um result de operação Caixa; quando há um nó de milestone do serviço de formalização, ele vem em data.result (ContractMilestoneResult — presente em CONTRACT_PAYMENT_REVISION/CONTRACT_PAYMENT_FAILED). Ver Payloads.


A forma de cada data por grupo — a tabela de campos, a seção error/OperationError/originalErrors[], o mapeamento eventType → result e os exemplos JSON na íntegra de cada evento — está em Payloads.

Atualizado