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

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.

Apenas o originator dono da operação pode consultá-la. O enum de status inclui estados que podem exigir intervenção manual (NEEDS_VERIFICATION, FAILED_NEEDS_MANUAL). Ver Fluxo assíncrono e polling.

Request

GET /api/v1/fgts/operations/{requestId}

Autenticado: Authorization: Bearer {originatorToken}.

Parâmetros

Parâmetro
Local
Tipo
Obrigatório
Descrição

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

Campo
Tipo
Descrição

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)

Campo
Tipo
Descrição

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.

Campo
Tipo
Descrição

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).

Recusas são consultáveis. Uma operação recusada na admissão do processamento — averbação duplicada, recusa no gate de cancelamento/manutenção (garantia inexistente, fora de estado elegível, aprovação já pendente, operação inválida) — responde 200 com status = FAILED já na primeira consulta, com o mesmo error.code do evento FAILED entregue por webhook (ex.: GUARANTEE_NOT_FOUND, GUARANTEE_NOT_GATEABLE, GUARANTEE_ALREADY_CANCELLED, GUARANTEE_APPROVAL_ALREADY_PENDING, GUARANTEE_OPERATION_DUPLICATE, ENDORSEMENT_ALREADY_SUBMITTED). O 404 significa apenas requestId inexistente — não o trate como "ainda processando" nem como sinal de recusa; programe pelo error.code.

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

Código
Situação

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)

get
/api/v1/fgts/operations/{requestId}

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.

Autorizações
AuthorizationstringObrigatório

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

Parâmetros de rota
requestIdstring · uuidObrigatório

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.

Example: 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}$
Respostas
200

Status atual da operação FGTS.

application/json

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.

requestIdstringObrigatório

Identificador único da requisição (UUID).

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479
statusstring · enumObrigatório

Status 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

Example: QUEUEDValores possíveis:
sourcestring · enum · anulávelOpcional

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.

Example: CAIXA_CALLValores possíveis:
resultone of · anulávelOpcional

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).

ou
ou
ou
ou
estimatedWaitSecondsinteger · int32 · anulávelOpcional

Estimativa best-effort de segundos até a conclusão. Não é garantia de prazo. null quando não disponível ou em estados terminais.

Example: 18
reserveIdentifierstring · anulávelOpcional

Identificador 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.

Example: GTD00000001NS
get/api/v1/fgts/operations/{requestId}
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