Consultar Status da Operação
Retorna o status atual e o resultado (quando disponível) de uma operação FGTS identificada pelo requestId retornado na admissão (202). Use este endpoint para polling quando não usar webhook.
Request
GET /api/v1/fgts/operations/{requestId}
Autenticado: Authorization: Bearer {originatorToken}.
Parâmetros
requestId
path
string (uuid)
Sim
Identificador único da operação retornado na admissão (202). Formato UUID v4 (ex.: f47ac10b-58cc-4372-a567-0e02b2c3d479).
Response
requestId
string
Identificador único da requisição (UUID gerado pela API).
status
string
Status atual da operação no processamento. Enum: QUEUED, DISPATCHING, IN_FLIGHT, AWAITING_PROVIDER, NEEDS_VERIFICATION, RETRYING, PENDING_MANUAL_APPROVAL, COMPLETED, FAILED, FAILED_NEEDS_MANUAL, EXPIRED, CANCELLED. PENDING_MANUAL_APPROVAL indica cancelamento de reserva ou manutenção de garantia retido para revisão manual antes do envio à Caixa. Significado e ação de cada valor em Status da operação.
source
string
Origem do resultado quando status = COMPLETED: CAIXA_CALL (saldo apurado na Caixa) ou NA. Pode ser null.
result
object
Resultado da operação — presente apenas em COMPLETED. A forma varia por tipo de operação (ver abaixo). Pode ser null.
error
object (OperationError)
Erro da operação — presente em FAILED, FAILED_NEEDS_MANUAL e EXPIRED, e também em NEEDS_VERIFICATION, onde descreve a verificação em curso e não um desfecho. null em QUEUED, COMPLETED e CANCELLED. Catálogo de error.code em Erros da API.
estimatedWaitSeconds
integer
Estimativa best-effort de segundos até a conclusão (não é garantia). null em estados terminais ou quando indisponível.
reserveIdentifier
string
Identificador da reserva associada à operação, quando aplicável (ENDORSEMENT, CANCEL_RESERVE, MAINTAIN_GUARANTEE) e conhecido — o mesmo valor entregue nos eventos de webhook. Use-o para retentar a averbação, cancelar ou consultar a garantia. null para operações sem reserva associada.
retry
object (RetryProgress)
Progresso da janela de retentativa automática — presente apenas enquanto status = RETRYING. Ver detalhamento abaixo. null fora da janela.
Formas de result (por tipo de operação)
Averbação / manutenção de garantia / cancelamento de reserva → protocolo:
protocolNumber,protocolStatus,detail.Consulta de valor reservado → reserva atualizada:
reserveIdentifier,periods[](periodStatus,transferDate,originalAmount,updatedAmount).Consulta de protocolos por reserva → lista de protocolos:
protocols[](protocolNumber,protocolStatus).Consulta de saldo → objeto livre com o saldo.
Campo error (OperationError)
code
string
Código de erro canônico estável da API (não é o código cru da Caixa).
message
string
Mensagem legível em português descrevendo o erro.
originalErrors
array
Erros crus do provedor (Caixa) — presente apenas quando houve chamada à Caixa com erro. Cada item: provider, code, description, httpStatus, requestIdentifier, occurredAt. Pode ser null.
originalRequestId
string
Presente apenas quando code ∈ {ENDORSEMENT_ALREADY_SUBMITTED, GUARANTEE_OPERATION_DUPLICATE, GUARANTEE_APPROVAL_ALREADY_PENDING}: o requestId da operação que de fato está em andamento (ou concluída). Consulte-o para acompanhar o desfecho real. Ver Erros da API.
Campo retry (RetryProgress)
Presente apenas enquanto status = RETRYING. A Caixa devolveu um código transitório e a mesma reserva é reenviada automaticamente a cada 15 minutos, por até 72 horas.
providerAttempt
integer
Tentativas automáticas nossas já feitas nesta janela. Não é o seu orçamento de retentativas manuais, que é de 3 por reserva.
nextAttemptAt
string (date-time)
Quando será a próxima tentativa automática.
windowExpiresAt
string (date-time)
Fim da janela. Depois disso a operação encerra com error.code = TRANSIENT_PROVIDER_RETRY_EXHAUSTED e a retentativa manual passa a ser aceita.
eligible
boolean
Sempre false durante a janela: Retentar averbação responderia 409 ENDORSEMENT_NOT_RETRYABLE.
lastProviderError
object
O que a Caixa respondeu na tentativa que colocou a operação na janela. Mesma forma de um item de error.originalErrors: provider, code, description, httpStatus, requestIdentifier. Pode ser null.
200 OK — status atual da operação (em qualquer estado do enum).
Exemplo
Em processamento — QUEUED
Concluída — COMPLETED (averbação)
Em janela de retentativa — RETRYING (autorização pendente do trabalhador)
Repare que error é null: a averbação está viva. Neste caso — código 7 — a ação é do trabalhador, no app do FGTS; assim que ele autorizar, a próxima tentativa automática conclui a operação sem que você precise reenviar nada.
Falhada — FAILED (erro da Caixa repassado)
Recusada — FAILED com originalRequestId (averbação duplicada)
Recusa na admissão do processamento: resposta 200 com status = FAILED já na primeira consulta, sem originalErrors[] (a Caixa não foi chamada). O error.originalRequestId aponta a operação original — acompanhe o desfecho real por ele.
Erros
400
requestId não é um UUID — errorCode = VALIDATION_ERROR
401
Token ausente, inválido ou expirado — errorCode = UNAUTHORIZED
403
A operação não pertence ao originator autenticado (acesso cruzado) — errorCode = ORIGINATOR_OWNERSHIP_VIOLATION
404
requestId inexistente ou ainda não registrado — errorCode = OPERATION_NOT_FOUND. Logo após o 202 de averbação, cancelamento ou manutenção, o 404 pode durar alguns segundos; consulte de novo antes de concluir. Operação recusada não retorna 404: responde 200 com status = FAILED (ver acima)
500
Erro interno inesperado — errorCode = INTERNAL_ERROR
4xx
A plataforma não conseguiu concluir a consulta — errorCode = GUARANTEE_LEDGER_CLIENT_ERROR. Um 401/403 com este código não se refere ao seu token. Acione o suporte com o requestId
503
Serviço temporariamente indisponível. Aguarde Retry-After segundos (30) — errorCode = DISPATCHER_UNAVAILABLE
503
Indisponibilidade temporária na consulta de averbação, cancelamento de reserva ou manutenção de garantia — errorCode = GUARANTEE_LEDGER_UNAVAILABLE. Aguarde Retry-After
Estes erros seguem o formato ProblemDetail (RFC 7807), com o campo errorCode. Ver Erros da API.
A falha da operação em si (quando status ∈ {FAILED, FAILED_NEEDS_MANUAL, EXPIRED}) não é um ProblemDetail: vem no campo error da resposta 200 como um OperationError (code, message, originalErrors[]). Ver Erros da API.
Consulta o status de uma operação FGTS por requestId (polling)
Retorna o status atual e o resultado (quando disponível) de uma operação FGTS identificada pelo requestId retornado na admissão (202). Escopo por originator: apenas o originator dono da operação pode consultá-la. Acesso cruzado resulta em 403. Status completo: o enum de status inclui CANCELLED, NEEDS_VERIFICATION, FAILED_NEEDS_MANUAL e PENDING_MANUAL_APPROVAL (que podem exigir intervenção manual). PENDING_MANUAL_APPROVAL: estado intermediário das operações retidas no gate de aprovação manual — CANCEL_RESERVE e MAINTAIN_GUARANTEE — antes do envio à Caixa; não é terminal. O webhook CANCEL_RESERVE_UNDER_REVIEW é emitido pelo serviço fgts-webhook neste estado. Rejeitada a aprovação, a operação passa a FAILED com error.code = GUARANTEE_APPROVAL_REJECTED — o mesmo código do webhook, para que polling e webhook não se contradigam. Recusada na entrada do gate — garantia inexistente, fora de estado elegível, gate já pendente ou operação inválida — a operação nunca chega a PENDING_MANUAL_APPROVAL: responde FAILED já na primeira consulta, com o mesmo error.code do evento FAILED entregue por webhook. GUARANTEE_OPERATION_DUPLICATE indica submissão absorvida por uma operação já em andamento sob a mesma Idempotency-Key — acompanhe o requestId original. Programe pelo error.code; o error.message é texto de apresentação. Campo error: presente apenas quando status ∈ {FAILED, FAILED_NEEDS_MANUAL, EXPIRED}. Contém o código canônico GTLab e, quando aplicável, os erros originais retornados pelo provedor. Distinto dos erros de validação e autenticação (400/401/403), que usam ProblemDetail. estimatedWaitSeconds: estimativa best-effort de conclusão; não é garantia de prazo. Indisponibilidade temporária: 503 Retry-After.
JWT de originator fornecido pela GTLab no cadastro do originator. Identifica e autoriza o originator em todos os endpoints /api/v1/**.
Inclua no header: Authorization: Bearer <token>.
Identificador único da operação FGTS retornado na admissão (202). Sempre um UUID canônico gerado pelo servidor (RFC 4122). O cliente nunca o cria — apenas o recebe na resposta de admissão e o devolve no GET / DELETE. Validado contra o padrão UUID estrito para prevenção de path traversal.
f47ac10b-58cc-4372-a567-0e02b2c3d479Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$Status atual da operação FGTS.
Status corrente de uma operação FGTS, retornado por GET /api/v1/fgts/operations/{requestId}. O campo error está presente quando status ∈ {FAILED, FAILED_NEEDS_MANUAL, EXPIRED}, e também em NEEDS_VERIFICATION, onde descreve a verificação em curso e não um desfecho. O campo result só está presente quando status = COMPLETED. O estado PENDING_MANUAL_APPROVAL é intermediário e vale para as operações retidas no gate de aprovação manual (CANCEL_RESERVE e MAINTAIN_GUARANTEE) antes do envio à Caixa; o webhook CANCEL_RESERVE_UNDER_REVIEW é emitido neste estado. Rejeitada a aprovação, o status passa a FAILED com error.code = GUARANTEE_APPROVAL_REJECTED. Recusada na entrada do gate — garantia inexistente, fora de estado elegível, gate já pendente ou operação inválida —, ou recusada uma retentativa de averbação, a operação nunca chega a PENDING_MANUAL_APPROVAL: responde FAILED já na primeira consulta, com o mesmo error.code do evento FAILED entregue por webhook: GUARANTEE_NOT_FOUND, GUARANTEE_REFERENCE_MISSING, GUARANTEE_NOT_GATEABLE, GUARANTEE_ALREADY_CANCELLED, GUARANTEE_APPROVAL_ALREADY_PENDING, GUARANTEE_OPERATION_DUPLICATE, INSTALLMENT_NOT_FOUND, INVALID_ADJUSTMENT_AMOUNT, ADJUSTMENT_EXCEEDS_RESIDUAL_AMOUNT, ENDORSEMENT_ALREADY_SUBMITTED, ENDORSEMENT_RETRY_LIMIT_EXCEEDED, ENDORSEMENT_NOT_RETRYABLE, ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD e GUARANTEE_OPERATION_REFUSED (fallback quando o ledger não informa um código mais específico). GUARANTEE_OPERATION_DUPLICATE indica que a submissão foi absorvida por uma operação já em andamento com a mesma Idempotency-Key — o resultado sai no requestId original, não neste; esse requestId vem em error.originalRequestId. GUARANTEE_APPROVAL_ALREADY_PENDING indica que já existe uma operação desta garantia aguardando aprovação manual — o requestId dessa operação pendente também vem em error.originalRequestId. ENDORSEMENT_ALREADY_SUBMITTED indica que esta averbação já foi enviada antes — o requestId da submissão que de fato virou garantia vem em error.originalRequestId. Já em ENDORSEMENT_RETRY_LIMIT_EXCEEDED, ENDORSEMENT_NOT_RETRYABLE e ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD esta própria operação já é o desfecho terminal — error.originalRequestId, quando presente, é apenas correlação com o requestId da averbação original da reserva, não uma indicação de que o desfecho real está em outro lugar. Programe sempre pelo error.code: o error.message é texto de apresentação e pode mudar sem aviso.
Identificador único da requisição (UUID).
f47ac10b-58cc-4372-a567-0e02b2c3d479Status atual da operação. Retorna o status completo da operação, incluindo estados intermediários como NEEDS_VERIFICATION, FAILED_NEEDS_MANUAL e PENDING_MANUAL_APPROVAL que podem exigir intervenção manual. PENDING_MANUAL_APPROVAL: cancelamento de reserva (CANCEL_RESERVE) ou manutenção de garantia (MAINTAIN_GUARANTEE) retido aguardando aprovação manual antes do envio à Caixa; não é terminal. AWAITING_PROVIDER: averbação aceita pela Caixa e ainda em processamento do lado dela; não é terminal, não reenvie. Significado e ação de cada valor em https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#catalogo-status
QUEUEDValores possíveis: Origem do resultado quando status = COMPLETED. Presente e não-nulo apenas em terminal. CAIXA_CALL: resultado obtido via consulta ao provedor. NA: não aplicável ou ainda não determinado.
CAIXA_CALLValores possíveis: Resultado da operação quando status = COMPLETED. A forma varia por operationType: ENDORSE / MAINTAIN_GUARANTEE / CANCEL_RESERVE → ProtocolResult; QUERY_RESERVED_VALUE → ReservedValueResult; LIST_PROTOCOLS_BY_ID → ProtocolListResult; BALANCE_QUERY → BalanceResult (ou BalanceNoResult quando não há saldo).
Estimativa best-effort de segundos até a conclusão. Não é garantia de prazo. null quando não disponível ou em estados terminais.
18Identificador da reserva associada à operação, quando aplicável (ENDORSEMENT, CANCEL_RESERVE, MAINTAIN_GUARANTEE). Use este valor para retentar a averbação (POST /endorsements/{reserveIdentifier}/retries), cancelar ou consultar a garantia. null para operações sem reserva associada.
GTD00000001NSNão autenticado — JWT ausente, inválido ou expirado. Autentique-se e inclua o token no header Authorization: Bearer <token>.
Acesso negado — a operação não pertence ao originator autenticado (acesso cruzado entre originators).
Operação não encontrada — requestId inexistente ou ainda não registrado.
Erro interno inesperado no servidor.
Consulta temporariamente indisponível. DISPATCHER_UNAVAILABLE (Retry-After: 30) quando o processamento de operações está indisponível; GUARANTEE_LEDGER_UNAVAILABLE quando a operação depende do serviço de garantias (averbação, cancelamento de reserva, manutenção de garantia).
GET /api/v1/fgts/operations/{requestId} HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "QUEUED",
"source": "NA",
"estimatedWaitSeconds": 18
}Atualizado