跳到主要内容

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.

Status da reserva permitidos​

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

StatusDescrição resumida
pending_reservationReserva pendente
in_queue_pending_reservationNa fila, aguardando reserva
pending_balance_requestAguardando consulta de saldo
in_queue_pending_balance_requestNa fila, aguardando consulta de saldo

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).
ENDPOINT
PATCH /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation

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.

ENDPOINT
DELETE /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation

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, o máximo permitido e a lista completa das reservas atualmente na fila prioritária.

ENDPOINT
GET /social_security/priority_reservation_configuration

Response

STATUS
200

Atributos

current_number_of_priority_reservationsintegerReservas prioritárias ativas no momento.max_number_of_priority_reservationsintegerTeto configurado para o requester.reservationsarray of objectsLista das reservas atualmente na fila prioritária, ordenadas por fixed_rate_set_at crescente. Máximo de 100 itens.
Atributos de reservations
credit_operation_keystringChave externa da reserva.contract_numberstringNúmero do contrato.statusstringStatus atual da reserva. Valores possíveis: pending_reservation, in_queue_pending_reservation, pending_balance_request, in_queue_pending_balance_request.typestringEnumerador do tipo da reserva.fixed_rate_set_atstring (ISO 8601)Data e hora em que a reserva foi adicionada à fila prioritária.
RESPONSE BODY
{
  "current_number_of_priority_reservations": 2,
  "max_number_of_priority_reservations": 10,
  "reservations": [
    {
      "credit_operation_key": "550e8400-e29b-41d4-a716-446655440000",
      "contract_number": "BYX2000013373",
      "status": "pending_reservation",
      "type": "new",
      "fixed_rate_set_at": "2026-04-13T14:00:00Z"
    }
  ]
}

Erros​

PATCH — definir prioridade​

HTTPCódigoTítulo (exemplo)Quando ocorre
400QIT000006Priority reservation configuration not setRequester sem configuração de prioridade de reserva
400QIT000006Reservation status not allowedStatus da reserva fora da lista permitida
400QIT000006Priority reservation limit exceededLimite simultâneo atingido
404SSC000035Reservation not FoundReserva inexistente para requester + external_key
409QIT000008Priority reservation already fixed_rateJá está fixed_rate

DELETE — remover prioridade​

HTTPCódigoTítulo (exemplo)Quando ocorre
400QIT000006Reservation priority type not fixed_rateHá prioridade, mas não é fixed_rate
400QIT000006Reservation status not allowedStatus não permitido
404SSC000035Reservation not FoundReserva não encontrada

GET — configuração​

HTTPCódigoTítulo (exemplo)Quando ocorre
404QIT000007Priority reservation configuration not foundSem 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"
}