Consignado Público - Reserva de Margem

A reserva é a averbação: o registro da operação no ente consignante, que compromete a margem do servidor e ordena o desconto em folha. É o que transforma uma proposta em garantia.

API em desenvolvimento

Esta API está em fase de desenvolvimento, sendo assim, esta página está sujeita a alterações.

A reserva não é criada diretamente

Esta página é o que o parceiro precisa para acompanhar essa reserva: as regras que ela obedece, o que cada status significa, como consultá-la e como obter o comprovante.

Para mais informações sobre a emissão de uma dívida com consignação no Consignado Público, acessar as páginas referentes ao produto: cartão consignado, crédito novo e portabilidade.

Pré-requisitos

Uma averbação só é aceita quando as duas condições abaixo são verdadeiras. Uma contratação que as viole é recusada antes de chegar ao ente:

1. O vínculo consta na sua consulta de margem mais recente. A QI Tech lê a última consulta completed que o próprio parceiro fez daquele CPF naquele ente, e o vínculo informado precisa constar nela. Consultas de outros parceiros não contam, e uma consulta mais nova que não traga o vínculo o torna inelegível. A averbação nunca espera por uma consulta: se o vínculo não consta, a operação é recusada na hora.
2. A consulta ainda é válida. A margem muda a qualquer momento, então uma averbação só se apoia em uma consulta recente. A consulta vale até o fim do dia valid_until: a data de observed_at no horário de Brasília, mais 30 dias. O prazo cobre a contratação inteira, inclusive a assinatura.

A margem enviada é a que o parceiro ofertou

O valor averbado é o que o parceiro decidiu ofertar, já com a sua própria margem de segurança aplicada. A QI Tech não relê a margem antes de averbar: envia o valor e trata a recusa do ente, se houver. É assim porque a margem muda a qualquer momento, e só a averbação garante o valor. Ver A margem é indicativa.

Validar um vínculo

POST

/public_payroll/{entity_level}/{consignment_entity}/reservation/validation

Confere, sem criar nada, o que a contratação conferiria: as duas condições de Pré-requisitos, e se o órgão aceita novas operações e oferece o tipo de reserva.

Request

Request Body

{
  "employee_document_number": "12345678901",
  "employment_relationship": { ... },
  "reservation": {
    "type": "payroll_card"
  }
}

Request Body Details

Campo	Tipo	Descrição	Obrigatório
employee_document_number	string	CPF do servidor, apenas dígitos	Sim
employment_relationship	object	Identificação do vínculo, conforme o perfil do ente	Sim
reservation.type	string	Tipo de reserva da operação: payroll_card ou benefit_card. Enum: Tipos de reserva	Sim

Perfil 1

Request Body

{
  "employee_document_number": "12345678901",
  "employment_relationship": {
    "agency": "spprev",
    "registration_number": "1234567890123"
  },
  "reservation": {
    "type": "payroll_card"
  }
}

Request Body Details

Campo	Tipo	Descrição	Obrigatório
employment_relationship.agency	string	Enumerador do órgão do servidor. Enum: Órgãos	Sim
employment_relationship.registration_number	string	Matrícula do servidor no órgão, exatamente como o órgão a emite	Sim

Response

STATUS

200 (OK)

Response Body

{
  "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "observed_at": "2026-08-26T13:02:40Z",
  "valid_until": "2026-09-25"
}

Response Body Details

Campo	Tipo	Descrição
balance_inquiry_key	string	A consulta em que o vínculo foi observado
observed_at	string	Momento em que a QI Tech recebeu a resposta do ente, em UTC
valid_until	string	Último dia em que uma averbação pode se apoiar nessa consulta, até o fim do dia no horário de Brasília: a data de observed_at nesse horário, mais 30 dias. Formato YYYY-MM-DD

Erros

As verificações seguem a ordem da tabela, e a primeira que falha define a resposta.

Status	Código	Quando ocorre
400	QIT000400	O corpo não segue o esquema: campo obrigatório ausente, campo não previsto ou formato inválido. description indica o campo
404	SCC000202	O ente da rota não existe
422	SCC000204	O parceiro não está configurado para o Consignado Público
400	SCC000003	employee_document_number não é um CPF válido: dígitos verificadores incorretos, ou um único dígito repetido
404	SCC000201	O órgão informado em employment_relationship.agency não existe no ente
422	SCC000203	O órgão não está habilitado para novas operações
422	SCC000401	O vínculo não está elegível: não consta na última consulta de margem completed do parceiro para aquele CPF, ou uma consulta posterior deixou de retorná-lo como ativo. Ver Pré-requisitos
422	SCC000402	A consulta que trouxe o vínculo passou de valid_until. Ver Pré-requisitos
422	SCC000403	O órgão não oferece o tipo de reserva informado em reservation.type

Nos casos SCC000401 e SCC000402, o caminho é criar uma nova consulta de margem.

Acompanhar a reserva

GET

/public_payroll/{entity_level}/{consignment_entity}/reservation/{reservation_key}

GET

/public_payroll/{entity_level}/{consignment_entity}/reservation/external_key/{origin_key}

A segunda forma endereça a reserva pela chave da operação de origem — a chave do cartão ou da operação de crédito que a originou.

Response

STATUS

200 (OK)

Response Body

{
  "reservation_key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
  "requester_key": "4d1e8c2a-7b3f-4e9a-8c5d-2f6a1b0e9c3d",
  "origin": {
    "type": "payroll_card_reservation",
    "key": "a7c3e1f0-4b2d-4c8e-9f11-5d6a7b8c9d0e"
  },
  "status": "reserved",
  "reason": null,
  "created_at": "2026-08-17T17:03:00Z",
  "consignment_entity": {
    "code": "39467292",
    "enumerator": "sp",
    "name": "Governo do Estado de São Paulo"
  },
  "employee_document_number": "12345678901",
  "employment_relationship": { ... },
  "reservation": { ... }
}

Response Body Details

Campo	Tipo	Descrição
reservation_key	string	Chave da reserva
requester_key	string	Chave do parceiro que contratou a operação
origin	object	A operação que originou a reserva, {type, key}
status	string	Situação da reserva. Enum: Status da reserva
reason	object	Motivo do status atual, ou null quando o status não tem motivo. Ver Motivos
created_at	string	Momento da criação da reserva, em UTC
consignment_entity	object	Ente, no formato {code, enumerator, name}
employee_document_number	string	CPF do servidor
employment_relationship	object	O vínculo averbado
reservation	object	Dados da averbação no ente

O conteúdo de employment_relationship e de reservation muda com o perfil:

Perfil 1

Response Body

{
  "employment_relationship": {
    "agency": {
      "code": "20065",
      "enumerator": "spprev",
      "name": "SPPREV"
    },
    "registration_number": "1234567890123"
  },
  "reservation": {
    "type": {
      "enumerator": "payroll_card",
      "name": "Cartão consignado"
    },
    "contract_number": "PCR0001234567",
    "amount": 180.00,
    "disbursement_date": "2026-08-17",
    "inclusion_date": "2026-08-17",
    "external_reservation_number": "202608170000000012345",
    "approval_deadline": "2026-08-18T02:59:59Z",
    "next_payroll_date": "2026-09-05"
  }
}

Response Body Details

Campo	Tipo	Descrição
employment_relationship.agency	object	Órgão da matrícula, no formato {code, enumerator, name}. Enum: Órgãos
employment_relationship.registration_number	string	Matrícula, exatamente como o órgão a emite
reservation.type	object	Tipo de reserva. Enum: Tipos de reserva
reservation.contract_number	string	Número do contrato no ente. Identifica a averbação para sempre, e não é reaproveitável
reservation.amount	number	Valor mensal reservado, em reais
reservation.disbursement_date	string	Data de início do contrato, YYYY-MM-DD. No cartão, a data da assinatura no horário de Brasília
reservation.inclusion_date	string	Data em que o ente registrou a averbação, YYYY-MM-DD. null até o ente aceitar a reserva
reservation.external_reservation_number	string	Número da averbação no ente. null até o ente aceitar a reserva
reservation.approval_deadline	string	Prazo para a aprovação do servidor: o fim do dia, no horário de Brasília, do último dia do prazo do ente, em UTC. Preenchido em toda reserva que o ente aceita, e só tem efeito nos órgãos que exigem a aprovação. null até o ente aceitar a reserva
reservation.next_payroll_date	string	Próxima data de processamento da folha, YYYY-MM-DD, como o ente a informou ao aceitar a reserva. Pode ser null

Cada mudança de status também é notificada por webhook, o que dispensa consultar em laço.

Erros

Status	Código	Quando ocorre
404	SCC000404	Não existe reserva do parceiro com esse reservation_key no ente
404	SCC000405	Não existe reserva do parceiro com esse origin_key no ente

Uma reserva de outro parceiro responde como inexistente.

Confirmação

Alguns entes exigem uma etapa de confirmação como parte da averbação: o registro é aceito, mas a operação só passa a valer depois que o ente confirma a sua situação. Enquanto isso a reserva fica em um status intermediário, e a QI Tech acompanha o ente até a situação se definir.

Se o ente exige essa etapa, e o que decide o seu desfecho, depende do perfil:

Perfil 1

A confirmação acontece em toda reserva, de qualquer modalidade: a resposta do registro não informa se a averbação ficou ativa, então a reserva passa por pending_confirmation até o ente responder.

O que muda é quem decide o desfecho, e isso é definido pelo órgão:

• Onde o órgão não exige aprovação do servidor, a confirmação se resolve na primeira leitura da situação no ente.
• Onde o órgão exige aprovação do servidor, a averbação só fica ativa depois que o servidor aprova, dentro de approval_deadline. Ver Entes Consignantes.

Nos dois casos há dois desfechos possíveis:

• reserved — a averbação está ativa e a margem está comprometida.
• deleted — a averbação foi removida antes de se efetivar: o servidor recusou a operação (LSCC0002) ou não a aprovou dentro do prazo do ente (LSCC0003). Ver Motivos.

Cancelamento

O cancelamento também parte da operação de origem: cancelar o cartão ou a operação de crédito é o que faz a QI Tech desaverbar a margem no ente.

O status final depende de até onde a reserva chegou no ente:

Perfil 1

• canceled — nenhum registro enviado ao ente aguarda resposta: o registro ainda não foi enviado, ou o ente recusou cada tentativa. A reserva termina sem nenhuma chamada ao ente.
• deleted — o ente registrou a averbação: a QI Tech a exclui no ente, inclusive uma averbação que ainda aguarda a aprovação do servidor.

Se um registro enviado ainda aguarda resposta, a QI Tech espera a resposta antes de decidir.

Nos dois casos o motivo é LSCC0004 (deletion_requested). Uma reserva que já terminou não muda.

Comprovante

Em desenvolvimento. Estes endpoints ainda não estão disponíveis.

GET

/public_payroll/{entity_level}/{consignment_entity}/reservation/{reservation_key}/protocol

GET

/public_payroll/{entity_level}/{consignment_entity}/reservation/external_key/{origin_key}/protocol

Devolve os comprovantes da reserva — a evidência de que a operação foi executada no ente. Um comprovante de averbação é emitido quando a reserva é confirmada; um de desaverbação, quando o cancelamento é concluído. Uma reserva que nunca chegou a ser confirmada não gera comprovante.

Response

STATUS

200 (OK)

Response Body

[
  {
    "protocol_key": "3c9d1e2f-7a8b-4c5d-9e0f-1a2b3c4d5e6f",
    "type": "reservation",
    "created_at": "2026-08-18T09:12:00-03:00",
    "receipt_url": "https://...",
    "receipt": { }
  }
]

Response Body Details

Campo	Tipo	Descrição
protocol_key	string	Chave do comprovante
type	string	reservation (averbação) ou deletion (desaverbação)
created_at	string	Momento em que a operação foi comprovada
receipt_url	string	O documento renderizado
receipt	object	A mesma evidência em campos

Ciclo de vida

A sequência completa de status, com o que provoca cada transição, está em Enumeradores.

Testes em sandbox

Em sandbox, a reserva se apoia em uma consulta de margem de sandbox completed, como em produção: um CPF que comece com 2 não tem consulta completed, e não chega à reserva. O resultado é escolhido pela matrícula reservada e pelo primeiro dígito do CPF: a primeira regra da tabela que se aplica decide.

Regra	Resultado
Matrícula <CPF>0003	canceled, motivo ESCC0050 (insufficient_margin)
CPF que começa com 3	canceled, motivo ESCC0050 (insufficient_margin)
CPF que começa com 8	Permanece em pending_reservation: o ente recusa o registro temporariamente, e a QI Tech tenta de novo a cada hora
Matrícula <CPF>0023	Permanece em pending_confirmation: o servidor nunca responde
Matrícula <CPF>0024	deleted, motivo LSCC0002 (employee_refused_reservation)
Matrícula <CPF>0025	deleted, motivo LSCC0003 (employee_approval_expired)
Qualquer outro caso	reserved

O ente sempre aceita o cancelamento: uma reserva em pending_confirmation ou reserved termina em deleted, e uma do dígito 8, cujo registro o ente recusou, termina em canceled na hora. Nos dois casos o motivo é LSCC0004.

Cada mudança de status é enviada por webhook, como em produção.