FGTS — Eventos e notificações

Dado pessoal ou sensível deve ser mascarado em outputs, logs e exemplos. Todos os valores desta página são fictícios.

O que é

O ciclo de vida completo de uma operação de FGTS, evento por evento: o que acontece, quando, o que aquilo significa e o que exige ação sua.

Esta página existe para que você não descubra os eventos por tentativa e erro. Depois do submitapproval, a operação percorre a esteira sozinha — e cada parada dela é um estado que você precisa saber ler.

O que é um "evento" aqui. É uma transição de status da operação. Não há, hoje, um canal de notificação que empurre esses eventos para o seu sistema: você os observa consultando. A seção Webhook de saída no fim da página trata disso explicitamente.

Quando usar

• Ao desenhar a máquina de estados do seu lado, antes de escrever o acompanhamento.
• Quando uma operação parou em um status e você não sabe se deve agir ou esperar.
• Ao definir alertas operacionais: quais estados são normais e quais pedem intervenção.

Pré-requisitos

• id da operação — devolvido em 3. Operação.
• Token válido — ver Autenticação.

Eventos do ciclo de vida

Eventos do consentimento

Não existem. No FGTS o consentimento é um documento, não um registro com ciclo de vida: ele não tem status, não emite evento e não é recusado por prazo.

Essa é uma diferença deliberada em relação ao Consignado privado, onde a autorização de margem tem três estados (Pending, Approved, Refused) e bloqueia a consulta de margem quando não vale mais. A razão: lá existe um registro de autorização junto ao Crédito do Trabalhador; aqui, não.

Consequência prática: a ausência ou a inadequação do termo não aparece cedo. Ela aparece na etapa de garantia, como WarrantyRevision, quando a operação já existe. O controle é do seu lado — ver a seção de duração em 2.1 Consentimento de consulta.

Eventos da operação de crédito

Em ordem de percurso. A coluna Ação sua é a que importa: só quatro estados exigem que você faça algo.

Como ler o evento

Não há corpo de evento a receber: o "payload do evento" é a própria operação, lida por GET /v1/CreditNote/{id}. Os campos relevantes para o acompanhamento:

Como processar

O padrão recomendado, e as armadilhas de cada parte. É o mesmo do Consignado privado — o que muda são os estados a observar, não a mecânica.

1. Guarde id, creditNoteNo e o último status conhecido de cada operação, no seu banco. Sem o último status conhecido não existe "mudou de estado", só "está neste estado".
2. Varra por status e por janela de data. GET /v1/CreditNote com status e initialDate/finalDate, com paginação. Varra os estados em que você tem operações abertas, não todos.
3. Compare com o último status conhecido. Só reaja quando houver diferença. Reagir a cada leitura gera ação repetida — por exemplo, reentregar a URL de assinatura ao titular todo dia.
4. Trate o seu handler como idempotente. A consulta devolve estado, não evento: ler duas vezes o mesmo Signatures é o comportamento normal, não uma duplicidade da API. A proteção contra ação repetida é do seu lado.
5. Não confie na ordem das leituras para reconstruir o caminho. Entre duas varreduras a operação pode ter passado por vários estados. Se você precisa do histórico, guarde cada transição que observar — a API devolve o estado atual, não a trilha.
6. Reaja apenas aos quatro estados que exigem ação: Draft, WarrantyRevision, Signatures, PaymentRevision. Some Revision e Disapproved se o seu processo trata devolução e reprovação. Todo o resto é espera.
7. Defina alerta operacional por tempo em estado, não por estado. Neste produto o Warranty merece tolerância maior que no consignado: a janela de manutenção do órgão pode manter a operação parada legitimamente por mais tempo. Calibre o alerta com a UY3.

Intervalo de varredura: comece em 15 a 30 minutos para operações abertas e ajuste pelo seu volume. Varredura de minuto em minuto sobre carteira inteira consome limite de chamadas sem ganho — os estados que dependem de terceiros (órgão, provedor de assinatura) não mudam nessa velocidade.

Webhook de saída

Não disponível hoje. O contrato da API não expõe webhook de saída para o FGTS. Não existe endpoint para você registrar uma URL de callback, e nenhum evento desta página é entregue ativamente ao seu sistema.

As rotas de webhook que existem no contrato de Crédito (/v1/WebhookAutovist, /v1/WebhookWarehouse) são o contrário do que se procura aqui: são endpoints da UY3 que recebem callbacks de prestadores externos, em fluxos de outros produtos. Não são endereçadas ao parceiro e não notificam nada sobre FGTS.

Portanto: o acompanhamento por consulta descrito acima não é uma alternativa ao webhook — é o mecanismo. Implemente a varredura.

Estrutura prevista

Quando o recurso existir, a intenção é entregar os mesmos eventos desta página, com um envelope estável. O desenho previsto — sujeito a mudança até a publicação, não implemente contra ele:

• Registro da URL de callback por ambiente do parceiro, e não por operação.
• Envelope com identificador do evento, tipo do evento, momento em UTC, e o identificador da operação — sem dado pessoal no corpo.
• O corpo da notificação não substitui a consulta: ele diz "a operação X mudou", e você busca o estado por GET /v1/CreditNote/{id}. Isso mantém uma fonte de verdade só.
• Reenvio em caso de falha de entrega, com o mesmo identificador de evento — o que torna a deduplicação pelo identificador obrigatória do seu lado.

Duas consequências para quem está desenhando a integração agora:

• Construa a varredura de qualquer forma. Ela continua necessária como rede de segurança mesmo depois do webhook, para o caso de entrega perdida.
• Guarde o identificador do evento quando ele existir. Se o seu handler já é idempotente por operação e estado, a migração para webhook é de transporte, não de lógica.

Para acompanhar a disponibilidade, fale com a equipe de tecnologia da UY3.

O que acontece depois

Com a máquina de estados montada e a varredura rodando, o acompanhamento deixa de ser manual: o seu sistema sabe quando pedir assinatura, quando corrigir conta e quando avisar o titular de que o dinheiro saiu.

Antes desta etapa

• 4. Consultas e acompanhamento — as rotas usadas na varredura.
• 3. Operação — as ações que cada evento pode pedir.

Próxima etapa

• 5. Erros e troubleshooting — o que fazer quando o evento é Disapproved, Revision ou Error.
• Consignado privado — Eventos e notificações — o mesmo ciclo no outro módulo, com as diferenças marcadas.

Downloads

• Contexto para LLM deste módulo: llms-fgts.txt
• Collection Postman do módulo: uy3-fgts.postman_collection.json
• Documentação consolidada para LLM: llms.txt