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 consta na sua consulta de margem mais recente. A QI Tech lê a última consulta
completedque 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. - 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 deobserved_atno horário de Brasília, mais 30 dias. O prazo cobre a contratação inteira, inclusive a assinatura.
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, 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
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
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
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.
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.
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.