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.
Esta API está em fase de desenvolvimento, sendo assim, esta página está sujeita a alterações.
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:
- O vínculo já foi observado por uma consulta de margem. O vínculo informado precisa ter sido descoberto em uma consulta daquele CPF naquele ente. A averbação nunca espera por uma consulta: se o vínculo é desconhecido, a operação é recusada na hora.
- A observação é do mês corrente. O ente informa a margem por competência e a folha fecha mensalmente, então uma consulta de um mês anterior não sustenta uma averbação. O
valid_untilda consulta é o último dia do mês em que ela foi observada.
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
Confere se o CPF e o vínculo digitados resolvem para um vínculo conhecido e observado no mês corrente — as duas condições de Pré-requisitos.
Request
Request Body
{
"employee_document_number": "12345678901",
"employment_relationship": { ... }
}
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 |
- Perfil 1
Request Body
{
"employee_document_number": "12345678901",
"employment_relationship": {
"agency": "spprev",
"registration_number": "1234567890123"
}
}
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
Response Body
{
"balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
"observed_at": "2026-08-26T10:02:40-03:00",
"valid_until": "2026-08-31"
}
Response Body Details
| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | A consulta em que o vínculo foi observado |
| observed_at | string | Momento da observação |
| valid_until | string | Último dia em que uma averbação pode se apoiar nessa consulta |
Quando o vínculo não existe no registro, ou quando a observação é de um mês anterior. O corpo nomeia qual dos dois casos ocorreu. A saída é a mesma nos dois: criar uma nova consulta de margem.
Acompanhar a reserva
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.
Query Params
Query Params
| Campo | Tipo | Descrição |
|---|---|---|
| expand | string | events (histórico de status) · contract_data (condições da operação) · protocols (comprovantes) |
Response
Response Body
{
"reservation_key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
"origin": {
"type": "payroll_card_reservation",
"key": "a7c3e1f0-4b2d-4c8e-9f11-5d6a7b8c9d0e"
},
"status": "reserved",
"reason": null,
"created_at": "2026-08-17T14:03:00-03:00",
"consignment_entity": {
"code": "46379400",
"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 |
| 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, quando há. Ver Motivos |
| created_at | string | Momento da criação da reserva |
| 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": "PCR0001234567890",
"amount": 180.00,
"contract_start_date": "2026-08-17",
"external_reservation_number": "...",
"approval_deadline": "2026-08-18",
"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.contract_start_date | string | Data de início do contrato |
| reservation.external_reservation_number | string | Número da averbação no ente |
| reservation.approval_deadline | string | Prazo para a aprovação do servidor, quando o órgão a exige |
| reservation.next_payroll_date | string | Próxima data de processamento da folha |
Cada mudança de status também é notificada por webhook, o que dispensa consultar em laço.
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 caso mais comum é o servidor não ter aprovado a operação dentro do prazo do ente.
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.
Comprovante
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
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.