Fila prioritária (fixed rate)

Marca a reserva INSS como fixed_rate, respeitando o limite de reservas prioritárias ativas.

Quando usar

• Desbloqueio: o benefício está em liberação.
• Concorrência por margem: operações concorridas e críticas (ex.: novo entrante).

Antes de priorizar múltiplas reservas: GET /social_security/priority_reservation_configuration mostra uso atual e limite.

Não confunda com o “fura fila”

Este guia trata do endpoint /priority_reservation (fila prioritária). Sendo diferente da requisição síncrona com balde de fichas (fura-fila).

Status da reserva permitidos

Só é possível definir ou remover prioridade fixed_rate quando a reserva está em um destes status:

Status	Descrição resumida
pending_reservation	Reserva pendente
in_queue_pending_reservation	Na fila, aguardando reserva
pending_balance_request	Aguardando consulta de saldo
in_queue_pending_balance_request	Na fila, aguardando consulta de saldo
pending_authorization	Aguardando autorização

Fora desses status, a API retorna erro indicando status não permitido.

Limite simultâneo

Se o número de reservas já marcadas como prioritárias atingir o máximo configurado, um novo PATCH retorna erro de limite excedido. Use o GET de configuração para acompanhar o uso atual sem priorizar outra reserva.

---

Definir prioridade

Request

ENDPOINT

/social_security/reservation/external_key/EXTERNAL_KEY/priority_reservation

MÉTODO

PATCH

Path params

external_keystringobrigatórioIdentificador externo da reserva no seu fluxo (mesmo conceito de DEBT-KEY nos roteiros de crédito consignado INSS).

Python

ENDPOINT

PATCH /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation

curl

ENDPOINT

curl -X PATCH \
  'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation' \
  -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

external_keystringChave externa da reserva.reservation_priority_typestringTipo de prioridade; em sucesso, fixed_rate.current_number_of_priority_reservationsintegerQuantidade atual de reservas prioritárias do requester após a operação.max_number_of_priority_reservationsintegerLimite máximo configurado.

RESPONSE BODY

{
  "external_key": "550e8400-e29b-41d4-a716-446655440000",
  "reservation_priority_type": "fixed_rate",
  "current_number_of_priority_reservations": 1,
  "max_number_of_priority_reservations": 10
}

---

Remover prioridade

Request

ENDPOINT

/social_security/reservation/external_key/EXTERNAL_KEY/priority_reservation

MÉTODO

DELETE

Path params

external_keystringobrigatórioIdentificador externo da reserva.

Remove a prioridade da reserva (reservation_priority_type passa a null). Exige que a prioridade atual seja fixed_rate (se houver outro tipo, a API retorna erro). Status da reserva deve continuar na lista permitida.

Python

ENDPOINT

DELETE /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation

curl

ENDPOINT

curl -X DELETE \
  'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation' \
  -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

external_keystringChave externa da reserva.reservation_priority_typenullSem prioridade após a remoção.current_number_of_priority_reservationsintegerContagem após a remoção.max_number_of_priority_reservationsintegerLimite máximo configurado.

RESPONSE BODY

{
  "external_key": "550e8400-e29b-41d4-a716-446655440000",
  "reservation_priority_type": null,
  "current_number_of_priority_reservations": 0,
  "max_number_of_priority_reservations": 10
}

---

Consultar limite e uso atual

Request

ENDPOINT

/social_security/priority_reservation_configuration

MÉTODO

GET

Retorna o resumo de quantas reservas prioritárias o requester tem no momento e o máximo permitido. Não recebe path params nem query obrigatória.

Python

ENDPOINT

GET /social_security/priority_reservation_configuration

curl

ENDPOINT

curl -X GET \
  'https://api-auth.sandbox.qitech.app/social_security/priority_reservation_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

current_number_of_priority_reservationsintegerReservas prioritárias ativas no momento.max_number_of_priority_reservationsintegerTeto configurado para o requester.

RESPONSE BODY

{
  "current_number_of_priority_reservations": 2,
  "max_number_of_priority_reservations": 10
}

---

Erros

PATCH — definir prioridade

HTTP	Código	Título (exemplo)	Quando ocorre
400	QIT000006	Priority reservation configuration not set	Requester sem configuração de prioridade de reserva
400	QIT000006	Reservation status not allowed	Status da reserva fora da lista permitida
400	QIT000006	Priority reservation limit exceeded	Limite simultâneo atingido
404	SSC000035	Reservation not Found	Reserva inexistente para requester + external_key
409	QIT000008	Priority reservation already fixed_rate	Já está fixed_rate

DELETE — remover prioridade

HTTP	Código	Título (exemplo)	Quando ocorre
400	QIT000006	Reservation priority type not fixed_rate	Há prioridade, mas não é fixed_rate
400	QIT000006	Reservation status not allowed	Status não permitido
404	SSC000035	Reservation not Found	Reserva não encontrada

GET — configuração

HTTP	Código	Título (exemplo)	Quando ocorre
404	QIT000007	Priority reservation configuration not found	Sem configuração para o requester

Exemplos de corpo de erro (JSON)

{
  "title": "Reservation not Found",
  "description": "...",
  "translation": "...",
  "code": "SSC000035"
}

{
  "title": "Priority reservation already fixed_rate",
  "description": "...",
  "translation": "...",
  "code": "QIT000008"
}