# 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": {
    "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](/documentation/guides/publico/entes#sp-canais-de-autorizacao) | 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](/documentation/guides/publico/entes#particularidades).

### Response

STATUS
**202** (Accepted)

**Response Body**

```json
{
  "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](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| created_at | string | Momento da criação da consulta |

## 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",
  "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](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| reason | object | Motivo, quando a consulta falha. `null` nos demais casos. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |
| 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](/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
{
  "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](/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[].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** |
| margins[].situation | object | Situação da margem. Enum: [Situação da margem](/documentation/guides/publico/enumeradores#margin_situation) |
| margins[].rule | string | Regra usada para consolidar os provimentos: `largest_appointment` ou `summed` |

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

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

```json
{
  "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](/documentation/guides/publico/enumeradores#relationship_type) |
| 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](/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 uma consulta do mês corrente** para aquele vínculo. 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. O corpo vem com o mesmo envelope, `employment_relationships` vazio e o motivo preenchido:

```json
{
  "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](/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.

---

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

:::caution API em desenvolvimento
Os enumeradores de ente e de esfera ainda estão em definição e podem mudar até o lançamento.
:::

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

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

```
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 `rule`. Os valores por provimento ficam disponíveis sob demanda, com `expand=appointments`.

#### 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 01.05.2026, o Governo do Estado de São Paulo exige que o próprio servidor aprove cada nova averbação no **aplicativo do ente**, 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 perto do fim do dia são retidas pela QI Tech e submetidas na janela 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 `rule` qual regra usou.

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

O enumerador do órgão é o valor enviado em `agency`.

| Órgão | `agency` | Calendário de folha |
|---|---|---|
| São Paulo Previdência | `spprev` | Em construção |
| *Demais órgãos* | Em construção | Em construção |

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

#### 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` | Em construção |
| `payroll_loan` | Em construção |

#### Canais de autorização {#sp-canais-de-autorizacao}

Valores aceitos em `authorization.channel` na [consulta de margem](/documentation/guides/publico/consulta-de-margem#criar-uma-consulta).

| `channel` | Onde a anuência é colhida |
|---|---|
| *Em construção* | Em construção |

#### 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` | A averbação existe, mas está bloqueada no ente. Pode voltar a `reserved` no desbloqueio |
| `canceled` | A operação **nunca existiu** no ente: foi desistida antes do registro, ou as tentativas de registro se esgotaram |
| `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` | A operação existiu no ente e chegou ao fim: todas as parcelas foram processadas |

Os três status finais se distinguem pelo que aconteceu **no ente**: `canceled` nunca chegou lá, `deleted` chegou e saiu, `settled` 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 transiçã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` | Empréstimo consignado |
| `payroll_card` | Cartão consignado |
| `benefit_card` | Cartão 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 devolvido pelo ente consignante |
| description | Texto operacional, para diagnóstico |
| translation | Texto em português, apresentável ao usuário final |

```json
{
  "enumerator": "employee_not_authorized",
  "code": "...",
  "description": "...",
  "translation": "O servidor não autorizou a consulta de margem"
}
```

`reason` é `null` quando o status não precisa de explicação — uma consulta `completed`, uma reserva `reserved`.

## 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` | O ente aceitou a reserva e aguarda a finalização da operação. Ocorre apenas nas modalidades registradas em duas etapas |
| `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 |
| *Demais códigos* | Em construção | Em construção |

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

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

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

| Código | Situação | Efeito na consulta |
|---|---|---|
| `1` | Margem disponível | `completed`, com o valor informado |
| `2` | Consulta não autorizada pelo servidor | `failed` quando é a situação de todos os itens |
| `3` | Margem indisponível | `completed`, com margem zerada |
| `4` | 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`, e é devolvido como `{code, enumerator, translation}`.

| Código | Enumerador | Tradução |
|---|---|---|
| `1` | `statutory` | Estatutário |
| *Demais códigos* | Em construção | Em construção |

### Motivos {#reason_perfil_1}

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

| Enumerador | Quando ocorre |
|---|---|
| `employee_not_authorized` | O servidor não autorizou a consulta de margem no ente |
| *Demais motivos* | Em construção |

---

# 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 já foi observado por uma [consulta de margem](/documentation/guides/publico/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.
2. **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_until` da consulta é o último dia do mês em que ela foi observada.

:::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 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](#pre-requisitos).

### Request

**Request Body**

```json
{
  "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](/documentation/guides/publico/entes#perfis-de-consignacao) | Sim |

**Perfil 1**

**Request Body**

```json
{
  "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](/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-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 |

STATUS
**422** (Unprocessable Entity)

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](/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.

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

STATUS
**200** (OK)

**Response Body**

```json
{
  "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](/documentation/guides/publico/enumeradores#reservation_status) |
| reason | object | Motivo do status atual, quando há. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |
| 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](/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": "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](/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.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](/documentation/guides/publico/webhooks#reservation_status_change), o que dispensa consultar em laço.

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

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

---

# 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, e a reserva é endereçada pela chave da operação que a originou (`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}

| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | Chave da consulta |
| status | string | Situação final. Enum: [Status da consulta](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| reason | object | Motivo, quando a consulta falha. `null` em `completed`. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |

```json
{
  "webhook_type": "laas.public_payroll.balance_inquiry_status_change",
  "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "status": "completed",
  "reason": null
}
```

:::info A margem não vem no webhook
A notificação carrega apenas a chave, o status e o motivo. Os dados da consulta — matrículas, órgãos e margens — ficam no `GET` da consulta, que é autenticado e devolve o documento completo. Ver [Consultar o resultado](/documentation/guides/publico/consulta-de-margem#consultar-o-resultado).
:::

## Reserva de margem {#reservation_status_change}

| Campo | Tipo | Descrição |
|---|---|---|
| reservation_key | string | Chave da reserva |
| origin_key | string | Chave da operação que originou a reserva — o cartão ou a operação de crédito |
| status | string | Novo status. Enum: [Status da reserva](/documentation/guides/publico/enumeradores#reservation_status) |
| reason | object | Motivo da mudança, quando há. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |

```json
{
  "webhook_type": "laas.public_payroll.reservation_status_change",
  "reservation_key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
  "origin_key": "a7c3e1f0-4b2d-4c8e-9f11-5d6a7b8c9d0e",
  "status": "reserved",
  "reason": null
}
```

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 `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).