Consignado Público: Consulta de Margem
A consulta de margem pergunta ao ente consignante quais vínculos um CPF tem e quanta margem há em cada um. É o primeiro passo de qualquer operação: uma averbação só é aceita sobre um vínculo que uma consulta já observou.
Esta API está em fase de desenvolvimento, sendo assim, esta página está sujeita a alterações.
A consulta é assíncrona. A criação devolve 202 com a chave da consulta, o resultado chega por webhook e o documento fica disponível na consulta por chave.
Criar uma consulta
entity_level e consignment_entity identificam o ente. Ver Entes Consignantes.
Request
Request Body
{
"employee_document_number": "12345678901",
...
}
Request Body Details
| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| employee_document_number | string | CPF do servidor, apenas dígitos | Sim |
O restante do corpo depende do perfil de consignação do ente, porque cada plataforma possui um escopo e esquema de autorização próprio para a consulta:
- Perfil 1
Request Body
{
"employee_document_number": "12345678901",
"authorization": {
"granted_at": "2026-08-26",
"channel": "app"
}
}
Request Body Details
| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| authorization | object | Evidência da anuência do servidor para a consulta | Não |
| authorization.granted_at | string | Data em que o servidor autorizou a consulta, YYYY-MM-DD | Sim, se authorization |
| authorization.channel | string | Canal em que a autorização foi colhida. Enum: Canais de autorização | Sim, se authorization |
A consulta de margem no perfil 1 ocorre a nível de ente, retornando todas as matrículas deste servidor em todos os órgãos do ente.
Essa consulta depende da autorização do servidor no ente. Quando o parceiro já colheu essa autorização, authorization permite registrá-la antes da consulta; quando não é enviado, a consulta é feita direto e o próprio ente informa se está autorizada.
Se o ente aceita o registro da anuência por esse caminho, e quais valores de channel reconhece, é informado na secção de entes.
Response
Response Body
{
"balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
"status": "pending",
"created_at": "2026-08-26T10:02:11-03:00"
}
Response Body Details
| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | Chave da consulta. É por ela que o resultado é recuperado |
| status | string | Situação da consulta. Enum: Status da consulta |
| created_at | string | Momento da criação da consulta |
Consultar o resultado
Response
Response Body
{
"balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
"status": "completed",
"reason": null,
"observed_at": "2026-08-26T10:02:40-03:00",
"valid_until": "2026-08-31",
"consignment_entity": {
"code": "46379400",
"enumerator": "sp",
"name": "Governo do Estado de São Paulo"
},
"employee": {
"document_number": "12345678901",
"name": "Nome do Servidor"
},
"employment_relationships": [
...
]
}
Response Body Details
| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | Chave da consulta |
| status | string | Situação da consulta. Enum: Status da consulta |
| reason | object | Motivo, quando a consulta falha. null nos demais casos. Ver Motivos |
| observed_at | string | Momento da resposta do ente. É a idade real do dado |
| valid_until | string | Último dia em que uma averbação pode se apoiar nesta consulta |
| consignment_entity | object | Ente consultado, no formato {code, enumerator, name} |
| employee | object | Dados do servidor observados pelo ente |
| employment_relationships | array | Os vínculos encontrados. Vazio quando a consulta falha |
O conteúdo de employment_relationships é o que muda com o perfil, porque é a plataforma do ente que define como a margem é estruturada:
- Perfil 1
Um item por matrícula, com a margem já consolidada.
Response Body
{
"employee": {
"document_number": "12345678901",
"name": "Nome do Servidor",
"has_inquiry_authorization": true
},
"employment_relationships": [
{
"agency": {
"code": "20065",
"enumerator": "spprev",
"name": "SPPREV"
},
"registration_number": "1234567890123",
"next_payroll_date": "2026-09-05",
"has_inflight_operation": false,
"margins": [
{
"product": {
"code": 2,
"enumerator": "credit_card",
"name": "Cartão de Crédito"
},
"available_value": 1400.00,
"situation": {
"code": 1,
"enumerator": "available",
"translation": "Margem disponível"
},
"rule": "largest_appointment"
}
]
}
]
}
Response Body Details
| Campo | Tipo | Descrição |
|---|---|---|
| employee.has_inquiry_authorization | boolean | Se o servidor autorizou a consulta de margem no ente |
| employment_relationships[].agency | object | Órgão da matrícula, no formato {code, enumerator, name}. Enum: Órgãos |
| employment_relationships[].registration_number | string | Matrícula, exatamente como o órgão a emite |
| employment_relationships[].next_payroll_date | string | Próxima data de processamento da folha |
| employment_relationships[].has_inflight_operation | boolean | Indica que há operação em andamento sobre a matrícula |
| employment_relationships[].margins | array | Margem por produto, consolidada no nível da matrícula |
| margins[].product | object | Produto — o "balde" de margem consumido. Enum: Produtos |
| margins[].available_value | number | Margem disponível, em reais, sem nenhuma reserva de segurança aplicada |
| margins[].situation | object | Situação da margem. Enum: Situação da margem |
| margins[].rule | string | Regra usada para consolidar os provimentos: largest_appointment ou summed |
Detalhar por provimento
Por padrão o documento vai até o nível da matrícula, com a margem já consolidada pela regra do ente. Esse é o nível em que a averbação acontece e, portanto, o nível que interessa para ofertar.
Query Params
| Campo | Tipo | Descrição |
|---|---|---|
| expand | string | appointments — acrescenta os provimentos de cada matrícula |
Os valores por provimento existem para conferência. Quando o ente consolida pela regra do maior provimento, somar os provimentos produz uma margem que não existe — e a averbação será recusada. Use sempre o valor consolidado da matrícula.
Response Body
{
"registration_number": "1234567890123",
"appointments": [
{
"appointment_number": "01",
"relationship_type": {
"code": 1,
"enumerator": "statutory",
"translation": "Estatutário"
},
"margins": [
{
"product": {
"code": 2,
"enumerator": "credit_card",
"name": "Cartão de Crédito"
},
"gross_value": 1800.00,
"available_value": 1400.00,
"situation": {
"code": 1,
"enumerator": "available",
"translation": "Margem disponível"
},
"history": [
{ "reference_month": "2026-07", "available_value": 1350.00 }
]
}
]
}
]
}
Response Body Details
| Campo | Tipo | Descrição |
|---|---|---|
| appointments[].appointment_number | string | Número do provimento |
| appointments[].relationship_type | object | Tipo de vínculo. Enum: Tipo de vínculo |
| margins[].gross_value | number | Margem bruta do provimento, antes dos descontos já consignados |
| margins[].history | array | Margem disponível nas competências que vieram nesta resposta |
Consulta estática
Os dados retornados como resultado de uma consulta são estáticos: consultar a mesma chave no futuro devolve exatamente o mesmo conteúdo, com o mesmo observed_at, independente de alterações na margem e novas consultas que possam ter ocorrido no meio tempo.
Não existe endpoint que devolva "a margem mais recente consultada" de um CPF. Para dados atualizados, crie e referencie uma nova consulta.
O campo valid_until é o último dia do mês da observação. Depois dele, a consulta continua legível, mas não serve mais de base para uma averbação. Ver Pré-requisitos da reserva.
A margem é indicativa
Dentro do prazo de validade, a margem informada ainda assim é indicativa: ela muda sempre que qualquer instituição averba ou desaverba naquele servidor, inclusive entre a consulta e a averbação. Nenhuma política de validade torna uma consulta segura para contratar às cegas.
A margem só é garantida no momento da averbação. A API devolve o valor bruto informado pelo ente, sem descontar nenhuma reserva de segurança — a margem de segurança que o parceiro deduz antes de ofertar é uma regra do parceiro, aplicada sobre o valor que recebe.
A regra de validade que a QI Tech aplica é única e não configurável: a averbação exige uma consulta do mês corrente para aquele vínculo. Ver Pré-requisitos da reserva.
Quando a consulta falha
Uma consulta termina em failed quando o ente não pôde respondê-la — tipicamente porque o servidor não autorizou a consulta de margem. O corpo vem com o mesmo envelope, employment_relationships vazio e o motivo preenchido:
{
"status": "failed",
"reason": {
"enumerator": "employee_not_authorized",
"code": "...",
"description": "...",
"translation": "O servidor não autorizou a consulta de margem"
},
"employment_relationships": []
}
Os motivos possíveis são definidos pela plataforma do ente. Ver Motivos.
Margem zerada não é falha. Um vínculo sem margem disponível, ou com margem insuficiente, produz uma consulta completed com o valor que o ente informou — o vínculo e os seus dados continuam válidos e utilizáveis.