# QI Tech — Crédito Consignado › Consignado Público

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
10 página(s).

Índice:
- Consignado Público - Consulta de Margem (/documentation/guides/publico/consulta-de-margem)
- Consignado Público - Emissão (/documentation/guides/publico/credito-novo/emissao)
- Consignado Público - Formalização (/documentation/guides/publico/credito-novo/formalizacao)
- Consignado Público - Simulação (/documentation/guides/publico/credito-novo/simulacao)
- Consignado Público - Entes Consignantes (/documentation/guides/publico/entes)
- Consignado Público - Enumeradores (/documentation/guides/publico/enumeradores)
- Consignado Público - Portabilidade (/documentation/guides/publico/portabilidade)
- Consignado Público - Refinanciamento (/documentation/guides/publico/refinanciamento)
- Consignado Público - Reserva de Margem (/documentation/guides/publico/reserva)
- Consignado Público - Webhooks (/documentation/guides/publico/webhooks)

---

# Consignado Público - Consulta de Margem

URL: /documentation/guides/publico/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.

:::caution API em desenvolvimento
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](/documentation/guides/publico/webhooks#balance_inquiry_status_change) e o documento fica disponível na consulta por chave.

## Criar uma consulta

**POST**
/public_payroll/{entity_level}/{consignment_entity}/balance_inquiry

`entity_level` e `consignment_entity` identificam o ente. Ver [Entes Consignantes](/documentation/guides/publico/entes#entes-disponiveis).

### Request

**Request Body**

```json
{
  "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](/documentation/guides/publico/entes#perfis-de-consignacao) do ente, porque cada plataforma possui um escopo e esquema de autorização próprio para a consulta:

**Perfil 1**

**Request Body**

```json
{
  "employee_document_number": "12345678901",
  "authorization_term": {
    "signature": {
      "signer": {
        "name": "Nome do Servidor",
        "document_number": "12345678901",
        "email": "servidor@email.com",
        "phone": {
          "country_code": "55",
          "area_code": "11",
          "number": "999999999"
        }
      },
      "authentication_type": "opt_in",
      "authenticity": {
        "timestamp": "2026-08-26T13:00:00Z",
        "ip_address": "200.100.50.25",
        "session_id": "0b73fdb9-1b3b-4f09-9cf2-b775a1ce58d2",
        "fingerprint": {},
        "geolocation": {
          "latitude": -23.55,
          "longitude": -46.63
        }
      }
    }
  }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| authorization_term | object | Termo de autorização: a evidência da anuência do servidor para a consulta | Não |
| authorization_term.signature.signer.name | string | Nome de quem assinou o termo, até 200 caracteres | Sim, se `authorization_term` |
| authorization_term.signature.signer.document_number | string | CPF de quem assinou. Deve ser o CPF do servidor | Sim, se `authorization_term` |
| authorization_term.signature.signer.email | string | Email de quem assinou, até 200 caracteres | Não |
| authorization_term.signature.signer.phone | object | Telefone de quem assinou, `{country_code, area_code, number}`: código do país com 2 ou 3 caracteres, DDD com 2 e número com 8 ou 9 | Não |
| authorization_term.signature.signer.contact_type | string | Canal de contato: `sms`, `email` ou `whatsapp` | Não |
| authorization_term.signature.authentication_type | string | Obrigatoriamente `opt_in` | Sim, se `authorization_term` |
| authorization_term.signature.authenticity.timestamp | string | Momento do aceite, em UTC, exatamente no formato `AAAA-MM-DDTHH:MM:SSZ` (`2026-08-26T13:00:00Z`), sem milissegundos e sem fuso. Não pode ser posterior ao momento atual | Sim, se `authorization_term` |
| authorization_term.signature.authenticity.ip_address | string | IP da sessão do servidor, IPv4 ou IPv6 | Sim, se `authorization_term` |
| authorization_term.signature.authenticity.session_id | string | Identificador da sessão do servidor, de 10 a 50 caracteres | Sim, se `authorization_term` |
| authorization_term.signature.authenticity.fingerprint | object | Evidências adicionais do aceite, como dispositivo e navegador. Pode ser um objeto vazio | Sim, se `authorization_term` |
| authorization_term.signature.authenticity.geolocation | object | Localização do aceite, `{latitude, longitude}` | Não |

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, envie-a em `authorization_term`: a QI Tech registra a anuência no ente antes de consultar. O ente recebe apenas a data do aceite, no horário de São Paulo, e o canal digital; o restante do termo fica com a QI Tech como evidência. Sem `authorization_term`, a consulta é feita direto, e o próprio ente informa se o servidor a autorizou.

Com `authorization_term`, a resposta do ente ao registro decide se a consulta segue:

| Resposta do ente ao registro | Resultado |
|---|---|
| Registra a anuência | A consulta segue |
| A anuência já estava registrada (`ESCC0580`) | A consulta segue |
| A anuência aguarda a aprovação do próprio servidor (`ESCC0579`) | A consulta segue |
| O ente não aceita anuência registrada pelo consignatário (`ESCC0581`) | A consulta segue |
| Qualquer outra recusa | A consulta termina em `failed`, com o motivo da recusa |

Quando a consulta segue, o ente ainda pode responder que o servidor não autorizou, e ela termina em `failed` com `employee_not_authorized`. Ver [Quando a consulta falha](#quando-a-consulta-falha).

### Response

STATUS
**202** (Accepted)

**Response Body**

```json
{
  "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "status": "pending",
  "created_at": "2026-08-26T13:02:11Z"
}
```

**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](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| created_at | string | Momento da criação da consulta, em UTC |

### Erros

| Status | Código | Quando ocorre |
|---|---|---|
| 400 | `SCC000003` | `employee_document_number` não é um CPF válido: dígitos verificadores incorretos, ou um único dígito repetido |
| 400 | `SCC000003` | `authorization_term.signature.signer.document_number` não é um CPF válido |
| 400 | `QIT000400` | O corpo não segue o esquema: campo obrigatório ausente, campo não previsto ou formato inválido, como um `timestamp` com milissegundos. `description` indica o campo. Também quando `timestamp` não é uma data existente, como `2026-02-30T10:00:00Z` |
| 404 | `SCC000202` | O ente da rota não existe |
| 422 | `SCC000204` | O parceiro não está configurado para o Consignado Público |
| 422 | `SCC000302` | `authorization_term.signature.authenticity.timestamp` é posterior ao momento atual |
| 422 | `SCC000303` | O CPF do assinante não é o CPF do servidor |

## Consultar o resultado

**GET**
/public_payroll/{entity_level}/{consignment_entity}/balance_inquiry/{balance_inquiry_key}

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
  "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "requester_key": "4d1e8c2a-7b3f-4e9a-8c5d-2f6a1b0e9c3d",
  "status": "completed",
  "observed_at": "2026-08-26T13:02:40Z",
  "consignment_entity": {
    "code": "39467292",
    "enumerator": "sp",
    "name": "Governo do Estado de São Paulo"
  },
  "employee": {
    "document_number": "12345678901",
    "name": "Nome do Servidor"
  },
  "authorization_term": {
    "signed_at": "2026-08-26T13:00:00Z",
    "authentication_type": "opt_in",
    "signer": {
      "name": "Nome do Servidor",
      "document_number": "12345678901"
    }
  },
  "employment_relationships": [
    ...
  ]
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | Chave da consulta |
| requester_key | string | Chave do parceiro que criou a consulta |
| status | string | Situação da consulta. Enum: [Status da consulta](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| reason | object | Motivo da falha. Presente apenas em uma consulta `failed`. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |
| observed_at | string | Momento em que a QI Tech recebeu a resposta do ente, em UTC. É a idade real do dado. `null` enquanto a consulta está `pending` |
| consignment_entity | object | Ente consultado, no formato `{code, enumerator, name}` |
| employee.document_number | string | CPF consultado |
| employee.name | string | Nome do servidor, como o ente o informa. `null` enquanto a consulta está `pending` e quando o ente não reconhece o CPF |
| authorization_term | object | Resumo do termo enviado na criação: `signed_at` (o `timestamp` do aceite), `authentication_type`, e `signer` (`name`, `document_number`). As evidências de autenticidade não são devolvidas. `null` quando a consulta foi criada sem termo |
| employment_relationships | array | Os vínculos encontrados. Vazio quando a consulta falha |

O conteúdo de `employment_relationships` é o que muda com o [perfil](/documentation/guides/publico/entes#perfis-de-consignacao), 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**

```json
{
  "employment_relationships": [
    {
      "agency": {
        "code": "20065",
        "enumerator": "spprev",
        "name": "SPPREV"
      },
      "registration_number": "1234567890123",
      "next_payroll_date": "2026-09-05",
      "has_inflight_operation": false,
      "margin_rule": "largest_appointment",
      "margins": [
        {
          "product": {
            "code": 2,
            "enumerator": "credit_card",
            "name": "Cartão de Crédito"
          },
          "available_value": 1400.00
        }
      ]
    }
  ]
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| employment_relationships[].agency | object | Órgão da matrícula, no formato `{code, enumerator, name}`. Enum: [Órgãos](/documentation/guides/publico/entes#sp-orgaos) |
| 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[].margin_rule | string | Regra usada para consolidar os provimentos: `largest_appointment` (o maior provimento) ou `summed` (a soma dos provimentos) |
| 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](/documentation/guides/publico/enumeradores#product) |
| margins[].available_value | number | Margem disponível, em reais, **sem nenhuma reserva de segurança aplicada** |

#### Detalhar por provimento {#expansoes}

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. `history` — acrescenta os provimentos e, em cada margem, o histórico de margem bruta |

`expand` recebe **um valor**: `history` já inclui os provimentos, então `?expand=history` devolve tudo o que `?expand=appointments` devolve e mais o histórico. Uma lista separada por vírgula (`appointments,history`) é recusada com `400 SCC000002`.

Com qualquer uma das expansões, cada margem da matrícula ganha `appointment_numbers`: os provimentos que compõem o valor consolidado — o maior provimento, na regra `largest_appointment`, ou todos os provimentos somados, na regra `summed`.

:::caution Não some as margens dos provimentos
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 ( ?expand=history )**

```json
{
  "registration_number": "1234567890123",
  "margins": [
    {
      "product": {
        "code": 2,
        "enumerator": "credit_card",
        "name": "Cartão de Crédito"
      },
      "available_value": 1400.00,
      "appointment_numbers": ["01"]
    }
  ],
  "appointments": [
    {
      "appointment_number": "01",
      "relationship_type": {
        "code": 16,
        "enumerator": "statutory",
        "translation": "Estatutário"
      },
      "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"
          },
          "average_gross_value": 1775.25,
          "history": [
            { "reference_month": "2026-07", "gross_value": 1800.00 },
            { "reference_month": "2026-06", "gross_value": 1750.00 },
            { "reference_month": "2026-05", "gross_value": 1775.75 }
          ]
        }
      ]
    }
  ]
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| margins[].appointment_numbers | array | Provimentos que compõem a margem consolidada da matrícula |
| appointments[].appointment_number | string | Número do provimento |
| appointments[].relationship_type | object | Tipo de vínculo. Enum: [Tipo de vínculo](/documentation/guides/publico/enumeradores#relationship_type) |
| appointments[].margins[].available_value | number | Margem disponível no provimento |
| appointments[].margins[].situation | object | Situação da margem no provimento. Enum: [Situação da margem](/documentation/guides/publico/enumeradores#margin_situation) |
| appointments[].margins[].average_gross_value | number | Média da margem bruta no histórico informado. Apenas com `expand=history` |
| appointments[].margins[].history | array | Margem bruta das competências anteriores que o ente informou, `{reference_month, gross_value}`. Apenas com `expand=history` |

### Erros

| Status | Código | Quando ocorre |
|---|---|---|
| 400 | `SCC000002` | `expand` traz um valor diferente de `appointments` ou `history`, ou uma lista separada por vírgula |
| 404 | `SCC000202` | O ente da rota não existe |
| 404 | `SCC000301` | A consulta não existe neste ente |

## 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**.

Uma consulta serve de base para uma averbação **até o fim do 30º dia depois da data de `observed_at`**, no horário de Brasília. Depois disso, a consulta continua legível, mas não serve mais de base para uma averbação. Ver [Pré-requisitos da reserva](/documentation/guides/publico/reserva#pre-requisitos).

## A margem é indicativa {#a-margem-e-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 que a última consulta `completed` do próprio parceiro traga o vínculo e ainda esteja válida**. Ver [Pré-requisitos da reserva](/documentation/guides/publico/reserva#pre-requisitos).

## Quando a consulta falha {#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, ou porque o ente não reconhece o CPF. O corpo vem com o mesmo envelope, `employment_relationships` vazio e o motivo preenchido:

```json
{
  "status": "failed",
  "reason": {
    "code": "LSCC0001",
    "enumerator": "employee_not_authorized",
    "description": "The employee did not authorize the margin inquiry",
    "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](/documentation/guides/publico/enumeradores#reason).

**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.

## Testes em sandbox {#sandbox}

Em sandbox, os mesmos [entes](/documentation/guides/publico/entes#entes-disponiveis) de produção respondem a partir de cenários fixos, escolhidos pelo **CPF** consultado. Qualquer CPF válido recebe a resposta de sucesso, exceto os CPFs de falha listados abaixo: os que começam com `2`. O mesmo CPF recebe sempre a mesma resposta.

```text
POST /public_payroll/state/sp/balance_inquiry
```

### Resposta de sucesso

A consulta termina em `completed`, com ou sem `authorization_term`, e traz seis matrículas, todas em um órgão ativo do ente — em São Paulo, `spprev`:

| Matrícula | Margem |
|---|---|
| `<CPF>0001` | Disponível: `1000.00` em `optional_consignment`, `500.00` em `credit_card` e `500.00` em `benefit_card` |
| `<CPF>0003` | Insuficiente: `0.00` nos três produtos |
| `<CPF>0008`, `<CPF>0023`, `<CPF>0024`, `<CPF>0025` | Disponível, com os mesmos valores de `<CPF>0001` |

Cada matrícula leva a um resultado diferente na reserva: ver [Testes em sandbox da reserva](/documentation/guides/publico/reserva#sandbox).

- A matrícula ` 0001` tem os provimentos `01` (`statutory`) e `02` (`permanent`). A margem consolidada é a do provimento `01`, pela regra `largest_appointment`, e só ele traz histórico (`expand=history`).
- O nome do servidor é sempre `SERVIDOR SANDBOX`, e a próxima data de folha é o dia 5 do mês seguinte.

### CPFs de falha

| CPF | Resultado, com ou sem `authorization_term` |
|---|---|
| `20000000108` | `failed`, motivo `LSCC0001` (`employee_not_authorized`): o servidor não autorizou a consulta. Com `authorization_term`, o ente registra o termo, e a consulta falha mesmo assim |
| Qualquer outro CPF que comece com `2`, como `20000000299` | `failed`, motivo `ESCC0187` (`employee_not_found`): o CPF não consta na base do ente. Com `authorization_term`, o ente já recusa o registro do termo |

A consulta muda de status em poucos segundos, e o [webhook](/documentation/guides/publico/webhooks#balance_inquiry_status_change) é enviado como em produção.

---

# Consignado Público - Emissão

URL: /documentation/guides/publico/credito-novo/emissao

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de criação da operação e do instrumento de crédito será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Formalização

URL: /documentation/guides/publico/credito-novo/formalizacao

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de envio de documentos e assinatura do servidor será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Simulação

URL: /documentation/guides/publico/credito-novo/simulacao

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de cálculo das condições de uma operação a partir da margem consignável do servidor será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Entes Consignantes

URL: /documentation/guides/publico/entes

Esta é a página de referência dos **entes consignantes** atendidos pelo Consignado Público: quais existem, como nomeá-los nas rotas, qual [perfil de consignação](#perfis-de-consignacao) cada um usa e o que cada um exige de diferente. As demais páginas desta seção — e o [Manual Cartão Consignado](/documentation/manual_cartao_beneficio/visao_geral), na fonte `public_payroll` — apontam para as âncoras daqui.

## Entes atendidos {#entes-disponiveis}

| Ente | `consignment_entity` | `entity_level` | Quem atende | Perfil | |
|---|---|---|---|---|---|
| Governo do Estado de São Paulo | `sp` | `state` | Servidores estaduais de São Paulo, ativos e inativos | [Perfil 1](#perfis-de-consignacao) | |
| Município de São Paulo | `sao_paulo_sp` | `municipal` | Servidores municipais de São Paulo | [Perfil 1](#perfis-de-consignacao) | Em desenvolvimento |

Em sandbox, os mesmos entes respondem a partir de cenários fixos, escolhidos pelo CPF. Ver [Testes em sandbox](/documentation/guides/publico/consulta-de-margem#sandbox).

O par (`entity_level`, `consignment_entity`) identifica o ente em toda a API:

```text
POST /public_payroll/state/sp/balance_inquiry
```

## Perfis de consignação {#perfis-de-consignacao}

Cada ente mantém a sua folha em uma plataforma de consignação, e as plataformas diferem em três coisas: **como identificam o servidor**, **como informam a margem** e **quais enumeradores usam**. O conjunto dessas três é o que chamamos de **perfil**.

Entes na mesma plataforma compartilham o perfil e, portanto, os mesmos payloads — o perfil é documentado uma vez, aqui, e a [tabela de entes](#entes-disponiveis) diz qual perfil cada ente usa.

**Perfil 1**

O servidor é identificado pelo **órgão** em que trabalha e pela **matrícula** que tem nesse órgão. A margem é apurada por cargo e consolidada no nível da matrícula.

#### Identificação do servidor

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| agency | string | Enumerador do órgão do servidor — a unidade pagadora dentro do ente: secretaria, autarquia, instituto de previdência | Sim |
| registration_number | string | Matrícula do servidor no órgão. Um mesmo CPF pode ter mais de uma | Sim |

```json
{
  "employment_relationship": {
    "agency": "spprev",
    "registration_number": "1234567890123"
  }
}
```

Os dois valores vêm da [Consulta de Margem](/documentation/guides/publico/consulta-de-margem).

**A averbação é registrada no nível da matrícula**, e o órgão é o que determina o calendário de folha e os limites comerciais da operação.

#### Estrutura da margem

Abaixo da matrícula existe o **provimento**: cada cargo concorrente que o servidor ocupa sob a mesma matrícula. A margem é apurada por provimento e por **produto** — o "balde" de margem que cada tipo de operação consome.

A consulta entrega a margem já **consolidada no nível da matrícula**, aplicando a regra do ente: somar os provimentos, ou considerar apenas o maior. A regra usada vem no campo `margin_rule`. Os valores por provimento ficam disponíveis sob demanda, com `expand=appointments` ou `expand=history`.

#### Enumeradores deste perfil

- [Produtos](/documentation/guides/publico/enumeradores#product)
- [Situação da margem](/documentation/guides/publico/enumeradores#margin_situation)
- [Tipo de vínculo](/documentation/guides/publico/enumeradores#relationship_type)

## Particularidades por ente {#particularidades}

**São Paulo (Estado)**

| Item | Valor |
|---|---|
| `consignment_entity` | `sp` |
| `entity_level` | `state` |
| Perfil | [Perfil 1](#perfis-de-consignacao) |
| Regra de margem entre provimentos | Maior provimento — os provimentos **não** somam |
| Aprovação do servidor | **Obrigatória** em toda averbação nova |

#### Aprovação do servidor {#sp-aprovacao}

Desde 05/01/2026, o Governo do Estado de São Paulo exige que o próprio servidor aprove cada nova averbação no **aplicativo do ente** (SOU.SP), com validação biométrica. A aprovação acontece depois que a averbação é registrada e vale **até o fim do mesmo dia**: o que não for aprovado nesse prazo é cancelado pelo ente por decurso de prazo.

Duas consequências para a integração:

- A averbação passa por um período de confirmação antes de ser considerada efetiva. Ver [Confirmação](/documentation/guides/publico/reserva#confirmacao).
- Averbações enviadas a partir das 22h (horário de Brasília) são retidas pela QI Tech e submetidas a partir das 00h10 do dia seguinte, para não nascerem sem tempo hábil de aprovação.

#### Margem entre provimentos

Quando um servidor tem mais de um provimento na mesma matrícula, a margem considerada é a do **maior provimento**, não a soma. A [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) já entrega o valor consolidado com essa regra aplicada, e informa no campo `margin_rule` qual regra usou.

#### Órgãos {#sp-orgaos}

O enumerador do órgão é o valor enviado em `agency`, e a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) o devolve em cada vínculo do servidor.

| Órgão | `agency` |
|---|---|
| Agência Metropolitana da Baixada Santista | `agem` |
| Agência Metropolitana de Campinas | `agemcamp` |
| Agência Reguladora de Saneamento e Energia do Estado de São Paulo | `arsesp` |
| Agência Reguladora de Serviços Públicos Delegados de Transporte do Estado de São Paulo | `artesp` |
| Departamento de Estradas de Rodagem | `der` |
| Departamento Estadual de Trânsito de São Paulo | `detran` |
| Hospital das Clínicas da Faculdade de Medicina da Universidade de São Paulo | `hcfmusp` |
| Hospital das Clínicas da Faculdade de Medicina de Ribeirão Preto da Universidade de São Paulo | `hcrp` |
| Hospital das Clínicas Faculdade de Medicina de Botucatu | `hcfmb` |
| Instituto de Assistência Médica ao Servidor Público Estadual | `iamspe` |
| Instituto de Medicina Social e Criminologia de São Paulo | `imesc` |
| Junta Comercial do Estado de São Paulo | `jucesp` |
| São Paulo Previdência | `spprev` |
| Secretaria de Gestão e Governo Digital | `sggd` |
| SP Águas - Agência de Águas do Estado de São Paulo | `daee` |

Somente os órgãos acima estão habilitados para novas operações. Um vínculo em outro órgão do ente é recusado na [validação da reserva](/documentation/guides/publico/reserva).

Os exemplos desta seção usam `spprev`.

#### Calendário de folha {#sp-calendario}

Cada órgão segue o calendário de folha definido pelo ente. Em cada competência, a margem é carregada no Cadastro de Margem e a folha fecha na Data de Corte. Os órgãos antecipam as datas de dezembro todos os anos.

#### Tipos de reserva e produtos {#sp-tipos-de-reserva}

Cada [tipo de reserva](/documentation/guides/publico/enumeradores#reservation_type) oferecido pelo ente consome a margem de um [produto](/documentation/guides/publico/enumeradores#product).

| Tipo de reserva | Produto |
|---|---|
| `payroll_card` | `credit_card` (`2`) |
| `benefit_card` | `benefit_card` (`3`). *Em desenvolvimento.* |

#### Limites comerciais

Prazo máximo e carência máxima da operação são definidos por órgão e por tipo de reserva. Para o cartão consignado, o [Manual Cartão Consignado](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao) descreve como esses limites são aplicados na contratação.

**São Paulo (Município)**

Em desenvolvimento. Órgãos, tipos de reserva, produtos e canais de autorização deste ente são publicados aqui quando ele for habilitado.

---

# Consignado Público - Enumeradores

URL: /documentation/guides/publico/enumeradores

Tabelas de referência do Consignado Público. Esta é a única página onde estes enumeradores são definidos; as demais páginas linkam para as âncoras daqui.

Os enumeradores estão em dois grupos. Os **gerais** são do contrato da QI Tech e valem em todo ente. Os **por perfil** são definidos pela plataforma de consignação do ente, e por isso mudam com o [perfil](/documentation/guides/publico/entes#perfis-de-consignacao).

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

## Enumeradores gerais

### Status da reserva {#reservation_status}

| Status | Significado |
|---|---|
| `pending_reservation` | A reserva foi criada e aguarda o registro no ente |
| `reserved` | **A averbação está ativa e a margem está comprometida.** É o único status em que a operação é garantida |
| `suspended` | *Em desenvolvimento.* A averbação existe, mas está bloqueada no ente. Pode voltar a `reserved` no desbloqueio. Não ocorre em reservas de cartão |
| `canceled` | A operação **nunca existiu** no ente: o ente recusou o registro, ou a reserva foi cancelada antes de o ente registrá-la |
| `deleted` | A operação **existiu** no ente e foi removida — pela QI Tech, pelo servidor, pelo órgão ou pelo decurso de um prazo |
| `settled` | *Em desenvolvimento.* A operação existiu no ente e chegou ao fim: todas as parcelas foram processadas. Não ocorre em reservas de cartão |

Os três status finais se distinguem pelo que aconteceu **no ente**: `canceled` nunca chegou lá, `deleted` chegou e saiu, `settled` (em desenvolvimento) chegou e terminou.

Entre `pending_reservation` e `reserved` pode haver status intermediários, conforme o número de etapas que o ente exige para registrar uma averbação. Ver [Status adicionais do Perfil 1](#reservation_status_perfil_1).

Cada mudança de status depois da criação gera um [webhook](/documentation/guides/publico/webhooks#reservation_status_change).

### Status da consulta de margem {#balance_inquiry_status}

| Status | Significado |
|---|---|
| `pending` | A consulta foi criada e ainda não foi respondida pelo ente |
| `completed` | O ente respondeu. O documento com os vínculos e as margens está disponível |
| `failed` | A consulta não pôde ser respondida pelo ente |

Margem zerada ou insuficiente produz `completed`, não `failed`.

### Tipos de reserva {#reservation_type}

O tipo de reserva é a modalidade comercial da operação, e determina de qual produto a margem é consumida.

| Enumerador | Modalidade |
|---|---|
| `payroll_loan` | *Em desenvolvimento.* Empréstimo consignado |
| `payroll_card` | Cartão consignado |
| `benefit_card` | Cartão de benefício |

Quais tipos cada ente oferece está em [Entes Consignantes](/documentation/guides/publico/entes#particularidades).

### Esferas do ente {#entity_level}

| Enumerador | Esfera |
|---|---|
| `state` | Ente estadual |
| `municipal` | Ente municipal |

É o primeiro segmento da rota, antes do enumerador do ente. Ver [Entes Consignantes](/documentation/guides/publico/entes#entes-disponiveis).

### Motivos {#reason}

Sempre que um status precisa ser explicado — uma consulta que falhou, uma averbação recusada ou removida — a resposta traz um objeto `reason`. **A estrutura é geral; os valores são do ente**, e vêm da plataforma em que a folha é consignada.

| Campo | Descrição |
|---|---|
| enumerator | O motivo, em forma estável. É por ele que a integração deve ramificar |
| code | O código do retorno |
| description | Descrição do código, em inglês |
| translation | Descrição do código, em português |

```json
{
  "enumerator": "employee_not_authorized",
  "code": "LSCC0001",
  "description": "The employee did not authorize the margin inquiry",
  "translation": "O servidor não autorizou a consulta de margem"
}
```

Quando o status não precisa de explicação, a reserva traz `reason` como `null`, e a consulta de margem omite o campo — uma consulta `completed`, por exemplo.

## Enumeradores por perfil de consignação

**Perfil 1**

### Status adicionais da reserva {#reservation_status_perfil_1}

Neste perfil o registro da averbação tem até duas etapas, e a situação da averbação precisa ser confirmada depois do registro. Daí dois status além dos [gerais](#reservation_status):

| Status | Significado |
|---|---|
| `pending_finalization` | *Em desenvolvimento.* O ente aceitou a reserva e aguarda a finalização da operação. Ocorre apenas nas modalidades registradas em duas etapas. Não ocorre em reservas de cartão |
| `pending_confirmation` | A averbação foi registrada e a QI Tech aguarda o ente definir a sua situação — inclusive a aprovação do servidor, onde ela é exigida. Ver [Confirmação](/documentation/guides/publico/reserva#confirmacao) |

### Produtos {#product}

O produto é o "balde" de margem consumido pela operação. O servidor tem um saldo de margem por produto, e tipos de reserva diferentes consomem produtos diferentes. Devolvido como `{code, enumerator, name}`.

| Código | Enumerador | Nome |
|---|---|---|
| `1` | `optional_consignment` | Consignações Facultativas |
| `2` | `credit_card` | Cartão de Crédito |
| `3` | `benefit_card` | Cartão de Benefício |
| `4` | `additional_margin` | Margem adicional 5% — LF 14.131/2021 |
| `5` | `compulsory_consignment` | Consignação Compulsória |
| `6` | `debt_settlement` | Quitação de Dívidas |
| `999` | `total` | Somatória |

Quais produtos existem em cada ente está em [Entes Consignantes](/documentation/guides/publico/entes#particularidades).

### Situação da margem {#margin_situation}

Acompanha cada margem de provimento na [consulta de margem](/documentation/guides/publico/consulta-de-margem#expansoes), e é devolvida como `{code, enumerator, translation}`.

| Código | Enumerador | Situação | Efeito na consulta |
|---|---|---|---|
| `1` | `available` | Margem disponível | `completed`, com o valor informado |
| `2` | `not_authorized` | Consulta de margem não autorizada pelo servidor | `failed`, motivo `employee_not_authorized`, quando é a situação de todos os provimentos |
| `3` | `unavailable` | Margem indisponível | `completed`, com margem zerada |
| `4` | `insufficient` | Margem insuficiente | `completed`, com o valor informado |

Os códigos `3` e `4` **não são erro**: a consulta foi respondida, e os vínculos descobertos continuam válidos para operações futuras.

### Tipo de vínculo {#relationship_type}

Acompanha cada provimento quando a consulta é feita com `expand=appointments` ou `expand=history`, e é devolvido como `{code, enumerator, translation}`.

| Código | Enumerador | Tradução |
|---|---|---|
| `1` | `retired` | Aposentado |
| `2` | `public_exam_hire` | Concursado |
| `3` | `intern` | Estagiário |
| `4` | `clt_employee` | Celetista |
| `5` | `temporary` | Temporário |
| `6` | `pensioner` | Pensionista |
| `7` | `permanent` | Efetivo |
| `8` | `constitutionally_tenured` | Estab. Constit |
| `9` | `special_pension` | Pensão Especial |
| `10` | `elected_office` | Emp. em Cargo Elet. |
| `11` | `appointed_councillor` | Nomeada Conselheiro |
| `13` | `commissioned_only` | Exclusivamente Comissão |
| `14` | `provisional` | Provisório |
| `15` | `scholarship_holder` | Bolsista |
| `16` | `statutory` | Estatutário |
| `17` | `permanent_in_commission` | Efetivo/CLT Permanente em Comissão/Confiança |
| `18` | `health_commissioned` | Comissionados Saúde |
| `19` | `health` | Saúde |
| `20` | `health_inspector` | Fiscais Saúde |
| `21` | `health_production` | Produção Saúde |
| `22` | `inspector` | Fiscais |
| `23` | `selective_process_hire` | Seletivos |
| `24` | `family_health_program` | PSF |
| `25` | `unified_health_system` | SUS |
| `26` | `commissioned_pressem` | Comissionados / Pressem |
| `27` | `health_statutory` | Estatutário Saúde |
| `28` | `no_employment_bond` | Sem Vínculo Empregatício |
| `29` | `retirement_supplement` | Complementação de Aposentadoria |
| `30` | `pension_supplement` | Complementação de Pensão |
| `99001` | `not_authorized_by_entity` | Consulta não autorizada pelo Ente |
| `99002` | `not_authorized_by_employee` | Consulta não autorizada pelo Servidor |
| `99003` | `not_registered` | Dados não registrados na base |

### Motivos {#reason_perfil_1}

Motivos devolvidos por este perfil, na estrutura descrita em [Motivos](#reason).

#### Consulta de margem

| Código | Enumerador | Quando ocorre |
|---|---|---|
| `LSCC0001` | `employee_not_authorized` | O servidor não autorizou a consulta de margem no ente: todos os provimentos vieram com a situação `not_authorized` |
| `ESCC0187` | `employee_not_found` | O CPF não consta no cadastro de servidores do ente |
| `ESCC0018` | `employee_registration_not_found` | Os dados de cadastro do servidor não foram localizados no SCC |

Um motivo fora desta tabela pode indicar um problema no cadastro da instituição no ente, e o `translation` traz a causa entre parênteses.

#### Reserva

| Código | Enumerador | Status | Quando ocorre |
|---|---|---|---|
| `ESCC0049` | `margin_unavailable` | `canceled` | A margem consignável do servidor não está disponível |
| `ESCC0050` | `insufficient_margin` | `canceled` | A margem consignável do servidor é menor que o valor da parcela |
| `ESCC0117` | `consignee_reservation_limit_exceeded` | `canceled` | O servidor atingiu o número máximo de averbações com a instituição |
| `ESCC0118` | `registration_number_reservation_limit_reached` | `canceled` | A matrícula atingiu o número máximo de averbações |
| `ESCC0158` | `disbursement_date_too_late` | `canceled` | A data de início do contrato passa do limite de dias aceito pelo ente |
| `ESCC0187` | `employee_not_found` | `canceled` | O CPF não consta no cadastro de servidores do ente |
| `ESCC0188` | `registration_number_not_found` | `canceled` | A matrícula informada não existe no órgão |
| `ESCC0189` | `registration_number_mismatch` | `canceled` | A matrícula informada não confere com a cadastrada no órgão |
| `ESCC0202` | `registration_number_not_registered` | `canceled` | A matrícula informada não existe no órgão |
| `ESCC0291` | `consignment_type_not_allowed_for_registration_number` | `canceled` | A matrícula do servidor não permite contratar este produto |
| `ESCC0463` | `reservation_not_authorized_by_agency` | `canceled` | O órgão não autorizou o registro da averbação |
| `ESCC0583` | `consignment_type_not_allowed_for_relationship_type` | `canceled` | O tipo de vínculo do servidor não permite contratar este produto |
| `ESCC0593` | `benefit_card_active_at_another_consignee` | `canceled` | O servidor já tem um cartão benefício ativo em outra instituição |
| `ESCC0594` | `no_active_registration_number` | `canceled` | O servidor não tem matrícula ativa |
| `LSCC0002` | `employee_refused_reservation` | `deleted` | O servidor recusou a averbação no aplicativo do ente |
| `LSCC0003` | `employee_approval_expired` | `deleted` | O servidor não aprovou a averbação dentro do prazo |
| `LSCC0004` | `deletion_requested` | `canceled` ou `deleted` | A instituição solicitou a exclusão da averbação |

Uma reserva pode terminar em `canceled` com outro código de recusa do ente: o primeiro código da recusa vira o motivo.

---

# Consignado Público - Portabilidade

URL: /documentation/guides/publico/portabilidade

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de transferência de uma operação consignada de outra instituição para a QI Tech será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Refinanciamento

URL: /documentation/guides/publico/refinanciamento

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de renegociação de uma operação consignada ativa será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Reserva de Margem

URL: /documentation/guides/publico/reserva

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.

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

:::info 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](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao), [crédito novo](/documentation/guides/publico/credito-novo/simulacao) e [portabilidade](/documentation/guides/publico/portabilidade).

:::

## Pré-requisitos {#pre-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](/documentation/guides/publico/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.

:::caution 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](/documentation/guides/publico/consulta-de-margem#a-margem-e-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](#pre-requisitos), e se o órgão aceita novas operações e oferece o tipo de reserva.

### Request

**Request Body**

```json
{
  "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](/documentation/guides/publico/entes#perfis-de-consignacao) | Sim |
| reservation.type | string | Tipo de reserva da operação: `payroll_card` ou `benefit_card`. Enum: [Tipos de reserva](/documentation/guides/publico/enumeradores#reservation_type) | Sim |

**Perfil 1**

**Request Body**

```json
{
  "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](/documentation/guides/publico/entes#sp-orgaos) | 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**

```json
{
  "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](#pre-requisitos) |
| 422 | `SCC000402` | A consulta que trouxe o vínculo passou de `valid_until`. Ver [Pré-requisitos](#pre-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](/documentation/guides/publico/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**

```json
{
  "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](/documentation/guides/publico/enumeradores#reservation_status) |
| reason | object | Motivo do status atual, ou `null` quando o status não tem motivo. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |
| 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](/documentation/guides/publico/entes#perfis-de-consignacao):

**Perfil 1**

**Response Body**

```json
{
  "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](/documentation/guides/publico/entes#sp-orgaos) |
| employment_relationship.registration_number | string | Matrícula, exatamente como o órgão a emite |
| reservation.type | object | Tipo de reserva. Enum: [Tipos de reserva](/documentation/guides/publico/enumeradores#reservation_type) |
| 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](/documentation/guides/publico/webhooks#reservation_status_change), 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 {#confirmacao}

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](/documentation/guides/publico/entes#particularidades).

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](/documentation/guides/publico/enumeradores#reason_perfil_1).

## 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**

```json
[
  {
    "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](/documentation/guides/publico/enumeradores#reservation_status).

## Testes em sandbox {#sandbox}

Em sandbox, a reserva se apoia em uma [consulta de margem de sandbox](/documentation/guides/publico/consulta-de-margem#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](#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](/documentation/guides/publico/webhooks#reservation_status_change), como em produção.

---

# Consignado Público - Webhooks

URL: /documentation/guides/publico/webhooks

Os fluxos do Consignado Público são assíncronos: a requisição registra a intenção e devolve `202`, e o resultado chega por webhook. Esta página lista as notificações publicadas hoje.

:::caution API em desenvolvimento
Esta API está em fase de desenvolvimento, sendo assim, esta página está sujeita a alterações. Os webhooks das etapas de crédito — simulação, emissão, formalização e desembolso — são publicados junto com aquelas modalidades.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Notificações

| `webhook_type` | Quando é enviado |
|---|---|
| `laas.public_payroll.balance_inquiry_status_change` | A [consulta de margem](/documentation/guides/publico/consulta-de-margem) termina, em `completed` ou `failed` |
| `laas.public_payroll.reservation_status_change` | A [reserva](/documentation/guides/publico/reserva) muda de status |

Cada parceiro recebe apenas as suas operações. O webhook da reserva traz também a chave da operação que a originou (`data.origin_key`) — a mesma chave que o parceiro já usa para acompanhar o cartão ou a operação de crédito.

## Consulta de margem {#balance_inquiry_status_change}

Enviado uma vez por consulta, quando ela termina em `completed` ou `failed`.

| Campo | Tipo | Descrição |
|---|---|---|
| webhook_type | string | `laas.public_payroll.balance_inquiry_status_change` |
| key | string | Chave da consulta (`balance_inquiry_key`) |
| status | string | Situação final. Enum: [Status da consulta](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| event_datetime | string | Momento do envio, em UTC |
| data | object | Em `completed`, a consulta exatamente como o [`GET` da consulta](/documentation/guides/publico/consulta-de-margem#consultar-o-resultado) a devolve, sem expansões. Em `failed`, o motivo, `{reason}`. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |

**completed**

```json
{
  "webhook_type": "laas.public_payroll.balance_inquiry_status_change",
  "key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "status": "completed",
  "event_datetime": "2026-08-26T13:02:41Z",
  "data": {
    "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
    "requester_key": "4d1e8c2a-7b3f-4e9a-8c5d-2f6a1b0e9c3d",
    "status": "completed",
    "observed_at": "2026-08-26T13:02:40Z",
    "consignment_entity": { ... },
    "employee": { ... },
    "authorization_term": null,
    "employment_relationships": [ ... ]
  }
}
```

**failed**

```json
{
  "webhook_type": "laas.public_payroll.balance_inquiry_status_change",
  "key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "status": "failed",
  "event_datetime": "2026-08-26T13:02:41Z",
  "data": {
    "reason": {
      "code": "LSCC0001",
      "enumerator": "employee_not_authorized",
      "description": "The employee did not authorize the margin inquiry",
      "translation": "O servidor não autorizou a consulta de margem"
    }
  }
}
```

As expansões (`expand=appointments`, `expand=history`) ficam apenas no `GET` da consulta. Ver [Detalhar por provimento](/documentation/guides/publico/consulta-de-margem#expansoes).

## Reserva de margem {#reservation_status_change}

Enviado a cada mudança de status da reserva depois da criação.

:::info `pending_confirmation`
O webhook também é enviado em `pending_confirmation`, quando o ente registra a averbação. Nos órgãos que exigem a [aprovação do servidor](/documentation/guides/publico/entes#sp-aprovacao), é o momento de orientá-lo a aprovar no aplicativo do ente, ainda no mesmo dia.
:::

| Campo | Tipo | Descrição |
|---|---|---|
| webhook_type | string | `laas.public_payroll.reservation_status_change` |
| key | string | Chave da reserva (`reservation_key`) |
| status | string | Novo status. Enum: [Status da reserva](/documentation/guides/publico/enumeradores#reservation_status) |
| event_datetime | string | Momento do envio, em UTC |
| data | object | A mudança de status, nos campos abaixo |

| Campo | Tipo | Descrição |
|---|---|---|
| data.reservation_key | string | Chave da reserva |
| data.origin_key | string | Chave da operação que originou a reserva — o cartão ou a operação de crédito |
| data.status | string | Novo status, o mesmo de `status` |
| data.reason | object | Motivo da mudança, ou `null` quando o status não tem motivo. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |

**reserved**

```json
{
  "webhook_type": "laas.public_payroll.reservation_status_change",
  "key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
  "status": "reserved",
  "event_datetime": "2026-08-18T12:15:03Z",
  "data": {
    "reservation_key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
    "origin_key": "a7c3e1f0-4b2d-4c8e-9f11-5d6a7b8c9d0e",
    "status": "reserved",
    "reason": null
  }
}
```

**canceled**

```json
{
  "webhook_type": "laas.public_payroll.reservation_status_change",
  "key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
  "status": "canceled",
  "event_datetime": "2026-08-17T17:05:12Z",
  "data": {
    "reservation_key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
    "origin_key": "a7c3e1f0-4b2d-4c8e-9f11-5d6a7b8c9d0e",
    "status": "canceled",
    "reason": {
      "code": "ESCC0050",
      "enumerator": "insufficient_margin",
      "description": "The employee's payroll margin is lower than the installment amount",
      "translation": "A margem consignável do servidor é menor que o valor da parcela"
    }
  }
}
```

Os status que encerram a contratação são **`reserved`** — margem comprometida, operação garantida — e **`deleted`** ou **`canceled`**, quando a averbação não existe mais ou nunca chegou a existir. O `data.reason` é o que distingue os motivos, e em particular identifica a falta de aprovação do servidor, o único caso em que refazer a contratação é o caminho. Ver [Confirmação](/documentation/guides/publico/reserva#confirmacao).