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

Consultar Protocolos por Reserva

Admite uma consulta da lista de protocolos associados a um ID de reserva FGTS, de forma assíncrona com prioridade NORMAL. Quando concluída com sucesso, o resultado conterá todos os protocolos vinculados à reserva.

Esta operação é assíncrona: a resposta 202 confirma apenas a admissão. O resultado chega depois via webhook ou por polling do requestId.

Request

POST /api/v1/fgts/reserve-protocol-queries

Autenticado: Authorization: Bearer {originatorToken}.

Parâmetros

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

Idempotency-Key

header

string (max 100)

Não

Chave de idempotência de negócio. Reenviar a mesma chave retorna o requestId existente sem publicar novamente. Ver Idempotência.

Corpo

Campo
Tipo
Obrigatório
Descrição

cpf

string (11 dígitos, ^\d{11}$)

Sim

CPF do trabalhador, 11 dígitos numéricos sem pontuação.

reserveIdentifier

string (1–50)

Sim

Identificador da reserva FGTS cujos protocolos serão listados.

Response

Campo
Tipo
Descrição

requestId

string (uuid)

Identificador único da requisição admitida, gerado pela API. Use no polling em GET /api/v1/fgts/operations/{requestId}.

status

string

QUEUED — operação enfileirada para processamento assíncrono.

  • 202 Accepted — consulta de protocolos de reserva admitida para processamento assíncrono. Quando concluída, o result do polling conterá a lista de protocolos.

Exemplo

Próximo passo

Acompanhe o resultado em Consultar status da operação usando o requestId retornado, ou aguarde o callback no webhook cadastrado.

Erros

Código
Situação

400

Validação de payload (campo obrigatório ausente, CPF fora do padrão ^\d{11}$, reserveIdentifier inválido, etc.) — errorCode = VALIDATION_ERROR

401

Token ausente, inválido ou expirado — errorCode = UNAUTHORIZED

422

Idempotency-Key já usada nesta rota com outro corpo — errorCode = IDEMPOTENCY_KEY_PAYLOAD_MISMATCH. Nada é enfileirado; para uma operação nova, use uma chave nova. Ver Idempotência

429

Hard ceiling de rate limit de ingresso excedido — errorCode = INGRESS_RATE_LIMIT_EXCEEDED (header Retry-After: 1, sem X-RateLimit-*). Ver Prioridades e rate limit

503

Indisponibilidade momentânea; nada foi registrado — errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE (header Retry-After: 5). Repita com o mesmo corpo e a mesma Idempotency-Key

500

Erro interno inesperado — errorCode = INTERNAL_ERROR

Os erros seguem o formato ProblemDetail (RFC 7807), com o campo errorCode. Ver Erros da API.

Esses são os erros da requisição. O desfecho da operação chega depois, no error.code do polling e do webhook — ver error.code de operação e Códigos da Caixa. Desfechos de falha: RESERVE_NOT_FOUND (o reserveIdentifier não é seu; a Caixa não é chamada), PROVIDER_ERROR com o código cru 30 quando a reserva não tem protocolos, PROVIDER_UNAVAILABLE e TRANSIENT_PROVIDER_EDGE_UNAVAILABLE.

Submete consulta de protocolos por ID de reserva FGTS

post
/api/v1/fgts/reserve-protocol-queries

Admite uma consulta de lista de protocolos por ID de reserva de forma assíncrona com prioridade NORMAL. O resultado é entregue via webhook cadastrado ou via polling em GET /api/v1/fgts/operations/{requestId}. Quando concluída com sucesso, o result do polling conterá uma ProtocolListResult com todos os protocolos associados à reserva. O header Idempotency-Key é aceito para deduplicação de negócio.

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 cabeçalho
Idempotency-Keystring · máx: 255Opcional

Chave de idempotência de negócio. Reenviar a mesma chave retorna o requestId existente sem reprocessar.

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479
Corpo

Corpo para consultas de reserva: consulta de valor reservado (/reserve-value-queries) e consulta de protocolos por ID de reserva (/reserve-protocol-queries). Ambas com prioridade NORMAL. Para cancelamento de reserva use ReserveCancellationRequest.

cpfstring · mín: 11 · máx: 11Obrigatório

CPF do trabalhador — 11 dígitos numéricos sem pontuação. Campo PII. Formato e dígitos verificadores (mód-11) validados na entrada; sequências de dígitos repetidos são rejeitadas com 400.

Example: 12345678909Pattern: ^\d{11}$
reserveIdentifierstring · mín: 1 · máx: 50Obrigatório

Identificador da reserva FGTS.

Example: RES-20240901-001
Respostas
202

Consulta de protocolos de reserva admitida para processamento assíncrono. Quando concluída, o result do polling conterá uma ProtocolListResult.

application/json

Confirmação de admissão assíncrona da operação FGTS (202 Accepted). O processamento ocorre em background; acompanhe pelo requestId via polling (GET /api/v1/fgts/operations/{requestId}) ou pelo webhook cadastrado. Exceção para balance-queries: quando o saldo já está disponível, a resposta é 200 OK com status: COMPLETED, source: CAIXA_CALL e result com o saldo — não é necessário polling, e o webhook é enviado também. Caso contrário, retorna 202.

requestIdstring · uuidObrigatório

Identificador único (UUID) gerado pelo serviço para esta chamada. Em resposta 202 a requisição foi admitida no processamento assíncrono e este é o identificador de polling: use-o em GET /api/v1/fgts/operations/{requestId}. Em resposta 200 de balance-queries o resultado já vem inline em result, e a operação também é admitida com este requestId: é o mesmo do webhook e é consultável em GET /api/v1/fgts/operations/{requestId}. Só é preciso fazer polling quando o status for QUEUED.

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

Status da operação no momento da admissão. QUEUED: operação enfileirada para processamento assíncrono (resposta 202). COMPLETED: resultado disponível inline no campo result — ocorre apenas quando o saldo de balance-queries já está disponível (resposta 200).

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

Origem do resultado. Presente apenas em resposta 200 de balance-queries. CAIXA_CALL: saldo apurado na Caixa. Nulo em respostas 202.

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

Resultado da operação. Presente apenas em resposta 200 de balance-queries. Nulo em respostas 202.

ou
reserveIdentifierstring · mín: 13 · máx: 14 · anulávelOpcional

Identificador determinístico de 13 ou 14 caracteres (GTD{contractNumber:8}{code:2..3}) gerado no momento da submissão de averbação — o código do originador tem 2 ou 3 caracteres. Presente apenas em respostas 202 de POST /endorsements. Nulo para todos os outros tipos de operação.

Example: GTD00000001NSPattern: ^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$
post/api/v1/fgts/reserve-protocol-queries
POST /api/v1/fgts/reserve-protocol-queries HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "cpf": "12345678909",
  "reserveIdentifier": "RES-20240901-001"
}
{
  "requestId": "f6a7b8c9-58cc-4372-a567-0e02b2c3d479",
  "status": "QUEUED"
}

Resultado no webhook

Concluída a consulta, a Giro.Tech envia ao webhook cadastrado um envelope { source, eventType, data }. Para esta operação o source é LIST_PROTOCOLS_BY_ID e os eventType possíveis são (consulta não tem desfecho *_NEEDS_VERIFICATION):

eventType

Quando

data

LIST_PROTOCOLS_COMPLETED

consulta concluída

result = ProtocolListResult (protocols[]; a lista pode vir vazia)

LIST_PROTOCOLS_FAILED

erro na consulta

error (OperationError)

LIST_PROTOCOLS_COMPLETED

Listagem de protocolos por reserva — result é um ProtocolListResult com protocols[].

LIST_PROTOCOLS_COMPLETED (lista vazia)

Listagem concluída sem protocolos encontrados — protocols é uma lista vazia. Quando a Caixa responde "nenhum resultado" (código cru 30), o desfecho é LIST_PROTOCOLS_FAILED com error.code = PROVIDER_ERROR: trate os dois casos como reserva sem protocolos.

LIST_PROTOCOLS_FAILED

Falha na listagem de protocolos.

Catálogo completo de eventos e payloads em Eventos e Payloads.

Atualizado