Fura-fila (priority request)

Mecanismo para tentar uma averbação de forma síncrona, sem esperar a fila assíncrona da Dataprev, usando um balde de fichas por requester. Cada chamada consome uma ficha; em caso de sucesso na averbação a ficha pode ser devolvida; em falha, a ficha é perdida até a próxima reposição periódica.

Não confunda com reserva prioritária (fixed rate)

Este guia trata de POST …/priority_request e GET /social_security/bucket_configuration (balde de fichas / fura-fila). É diferente da marcação de reserva fixed_rate em Reserva prioritária (fixed rate) (PATCH / DELETE em /priority_reservation).

Contexto

A Dataprev limita o throughput (ordem de 25 requisições por segundo). Por isso as tentativas de averbação costumam ser processadas em fila. O endpoint priority_request permite pular essa fila quando há ficha disponível no balde.

Resumo do balde:

Cada requisição consome uma ficha.
Averbação bem-sucedida → a ficha pode ser devolvida ao balde.
Averbação com erro → a ficha é perdida até a reposição.
Existe capacidade máxima e intervalo de reposição configurados para o seu requester.
Sem fichas → nova tentativa falha até a próxima reposição.

Exemplo ilustrativo do balde

Configuração de exemplo: 10 fichas máximas, 30 minutos entre reposições.

Hora 0: balde criado na capacidade máxima.

9 min: uma requisição falha na averbação → perde 1 ficha.

17 min: uma requisição tem sucesso → número de fichas inalterado.

30 min: primeira reposição → balde volta ao máximo.

47 min: dez requisições com sucesso → nenhuma ficha perdida.

1 h: segunda reposição; se o balde já estiver cheio, nada muda.

1 h 12 min: cinco falhas → perda de 5 fichas.

1 h 30 min: terceira reposição → ex.: 6 fichas disponíveis.

1 h 38 min: seis falhas → balde esgota.

1 h 51 min: tentativa sem fichas → barrada.

2 h: quarta reposição → novas tentativas liberadas.

Para o passo a passo completo da operação (validação de reserva, webhooks de sucesso, correção de dados), veja o Fluxo completo — crédito novo e refinanciamento.

Disparar requisição prioritária

Request

ENDPOINT

/social_security/reservation/external_key/EXTERNAL_KEY/priority_request

MÉTODO

POST

Path params

external_keystringobrigatórioChave da operação no fluxo (mesmo conceito de DEBT-KEY nos roteiros INSS).

Body: não há corpo na requisição.

Testar no Playground

Python
curl

ENDPOINT
POST /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_request

ENDPOINT
curl -X POST \
  'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_request' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \
  -H 'Content-Type: application/json'

Response (sucesso)

STATUS

200

Atributos

max_bucket_capacityintegerCapacidade máxima do balde (fichas).bucket_fill_rate_minutesintegerIntervalo de reposição, em minutos.available_tokensintegerFichas disponíveis após a operação.statusstringStatus da reserva após a tentativa (ex.: pending_document_submission).next_refill_atstringPróximo instante de reposição do balde (ISO 8601).

Webhook de sucesso

Se a averbação for concluída com sucesso, o parceiro recebe o webhook credit_operation.collateral com status de sucesso. Detalhes no mesmo capítulo do fluxo completo.

RESPONSE BODY
{
  "max_bucket_capacity": 10,
  "bucket_fill_rate_minutes": 30,
  "available_tokens": 7,
  "status": "pending_document_submission",
  "next_refill_at": "2025-02-04T20:28:35Z"
}

Consultar configuração do balde

Permite ver capacidade, fichas disponíveis e próxima reposição sem disparar uma requisição prioritária.

Request

ENDPOINT

/social_security/bucket_configuration

MÉTODO

GET

Sem path params nem query obrigatórios.

Testar no Playground

Python
curl

ENDPOINT
GET /social_security/bucket_configuration

ENDPOINT
curl -X GET \
  'https://api-auth.sandbox.qitech.app/social_security/bucket_configuration' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \
  -H 'Content-Type: application/json'

Response

STATUS

200

Atributos

max_bucket_capacityintegerCapacidade máxima do balde.bucket_fill_rate_minutesintegerIntervalo de reposição, em minutos.available_tokensintegerFichas disponíveis no momento.next_refill_atstringPróxima reposição (ISO 8601).

RESPONSE BODY
{
  "max_bucket_capacity": 10,
  "bucket_fill_rate_minutes": 30,
  "available_tokens": 7,
  "next_refill_at": "2025-02-04T20:08:35Z"
}

Erros

HTTP	Código	Título (exemplo)	Quando ocorre
400 / 4xx	SSC000083	Reservation Failed	Tentativa prioritária executada, mas a averbação falhou (mensagem costuma citar última resposta da Dataprev, fichas restantes e próxima reposição).
429 / 4xx	SSC000080	Rate limit exceeded	Nenhuma ficha disponível; aguardar a próxima reposição do balde.

Exemplos de corpo de erro (JSON)

{
  "title": "Reservation Failed",
  "description": "Last Response: consignable_margin_excceded, Tokens Available: 9, Next Refill At: 2025-02-04T20:18:35Z",
  "translation": "Ultima resposta: consignable_margin_excceded, Fichas disponiveis: 9, Proxima Recarga: 2025-02-04T20:18:35Z",
  "extra_fields": {},
  "code": "SSC000083"
}

{
  "title": "Rate limit exceeded",
  "description": "Request limit exceeded. No tokens available, next refill in 8 minutes.",
  "translation": "Limite de solicitacoes excedido. Nenhuma ficha disponivel, proxima recarga em 8 minutos.",
  "extra_fields": {},
  "code": "SSC000080"
}

Aviso importante!

Não utilize dados reais de pessoas (CPF, CNPJ etc.) em ambiente de sandbox.