# QI Tech — Investment-as-a-Service › Boletador de Títulos Públicos

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

Índice:
- Boletador de Títulos Públicos (/documentation/iaas/boletador/boletador_titulos_publicos)
- Consulta de Título Público (/documentation/iaas/boletador/consulta_titulo_publico)
- Listagem de Títulos Públicos (/documentation/iaas/boletador/listagem_titulos_publicos)

---

# Boletador de Títulos Públicos

URL: /documentation/iaas/boletador/boletador_titulos_publicos

Registra uma boleta de compra ou venda definitiva, ou de compra compromissada, de título público federal (LFT, LTN, NTN-B, NTN-F) para o fundo. A boleta é registrada no SELIC depois que a gestora a aprova.

:::info Disponível em

| Perfil  | Host          | Permissão exigida |
| ------- | ------------- | ----------------- |
| Gestora | `manager-api` | Escrita           |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

:::caution A aprovação é feita no portal

Toda boleta nasce em `pending_manager_approval`, e a API de integração **não expõe** a aprovação. Para aprovar, acesse o portal da gestora em **Ativos › Negociações › Títulos Públicos**, abra a operação e clique em **Aprovar operação**. Na mesma tela é possível cancelar a operação ou, depois do horário de corte, pedir a liberação de horário. Acompanhe o andamento pela [consulta da operação](/documentation/iaas/boletador/consulta_titulo_publico) ou pela [listagem](/documentation/iaas/boletador/listagem_titulos_publicos).

:::

:::info Horário de corte: 16:55 (horário de Brasília)

A partir das 16:55 (America/Sao_Paulo, inclusive), nada entra no SELIC no mesmo dia:

- o POST só é aceito com `time_exception_reason` preenchido (sem ele, `TTR000054`);
- a aprovação no portal também é recusada depois do corte. A gestora pode, então, pedir a liberação de horário, e a boleta fica em `pending_time_exception_approval` até a equipe QI Tech analisar a justificativa e liberar (ou cancelar).

Antes das 16:55, `time_exception_reason` é ignorado.

:::

## Request

ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operation
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
| :---- | :---- | :---- |
| `fund_class_key` | string | Identificador único do fundo. |

```json title="Request Body"
{
    "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b",
    "operation_date": "2025-12-04",
    "payment_date": "2025-12-04",
    "operation_part": "assignee",
    "operation_type": "outright_operation",
    "counterparty": {
        "iselic_number": "33444555",
        "selic_account_number": "123456789",
        "document_number": "33.444.555/0001-81"
    },
    "treasury_type": "ntn_b",
    "unit_price": 1234.567891,
    "units": 10,
    "maturity_date": "2035-05-15"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
| :---- | :---- | :---- | :---- |
| `external_id` | string | opcional | Seu identificador da boleta, único por fundo. Se não informado, será gerado automaticamente (UUID). Máximo de 36 caracteres. Veja [Reenvio e duplicidade](#reenvio-e-duplicidade). |
| `operation_date` | string (date) | obrigatório | Data da operação no formato `YYYY-MM-DD`. Deve ser um dia útil e igual à `accounting_date` do fundo. |
| `payment_date` | string (date) | obrigatório | Data de liquidação no formato `YYYY-MM-DD`. Deve ser `>= operation_date`. Em operações não-a-prazo (`outright_operation`, `buyback_operation`), deve ser igual à `operation_date`. |
| `operation_part` | string | obrigatório | Papel do fundo na operação: `assignee` (comprador) ou `assignor` (vendedor). Em `assignor`, `units` não pode passar das unidades deste título na carteira do fundo. |
| `operation_type` | string | obrigatório | Tipo de operação: `outright_operation` (definitiva) ou `buyback_operation` (compromissada). `buyback_operation` exige `operation_part == "assignee"` e que o fundo esteja habilitado para compromissadas. `term_outright_operation` ainda não está disponível (`TTR000042`). |
| `counterparty` | object | obrigatório | Dados da contraparte. Ver objeto abaixo. |
| `treasury_type` | string | obrigatório | Tipo de título: `lft`, `ltn`, `ntn_b` ou `ntn_f`. |
| `unit_price` | number | obrigatório | Preço unitário do título. Aceita qualquer precisão decimal; o servidor trunca para baixo conforme o tipo: `buyback_operation` → 8 casas decimais; demais → 6 casas decimais. |
| `units` | integer | obrigatório | Quantidade de títulos (inteiro positivo). |
| `maturity_date` | string (date) | obrigatório | Data de vencimento do título (`YYYY-MM-DD`). Deve ser estritamente posterior à `operation_date`. |
| `yearly_negotiated_rate` | number | condicional | Taxa negociada anual, em forma decimal (`0.144` = 14,4% a.a.). **Obrigatório para** `buyback_operation`. |
| `return_date` | string (date) | condicional | Data de retorno (`YYYY-MM-DD`). **Obrigatório para** `buyback_operation`. Deve ser `> operation_date`. |
| `time_exception_reason` | string | condicional | Justificativa para boletar fora do horário. **Obrigatório a partir das 16:55** (horário de Brasília); ignorado antes disso. Máximo de 500 caracteres. |

#### Objeto `counterparty`

| Campo | Tipo | Obrigatoriedade | Descrição |
| :---- | :---- | :---- | :---- |
| `iselic_number` | string | obrigatório | Número iSELIC da contraparte (8 dígitos). |
| `selic_account_number` | string | obrigatório | Conta SELIC da contraparte (9 dígitos). |
| `document_number` | string | obrigatório | CNPJ da contraparte com pontuação (formato `XX.XXX.XXX/XXXX-XX`), com dígito verificador válido. |

## Response

STATUS 201

```json title="Response Body"
{
    "operation_key": "85cfd700-54a4-40f4-bc61-2ece992864ea",
    "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b",
    "fund_class": {
        "fund_class_key": "5122bf31-660a-4f61-a447-38e5e17162dd",
        "manager_key": "bea7581a-f901-4995-a486-46e18ae61aab",
        "name": "FUNDO EXEMPLO DTVM",
        "document_number": "11.222.333/0001-81",
        "accounting_date": "2025-12-04"
    },
    "status": "pending_manager_approval",
    "operation_part": "assignee",
    "operation_type": {
        "enumerator": "outright_operation",
        "code": 1052
    },
    "treasury": {
        "enumerator": "ntn_b",
        "code": 760199
    },
    "operation_date": "2025-12-04",
    "payment_date": "2025-12-04",
    "maturity_date": "2035-05-15",
    "total_operation_value": 12345.67,
    "units": 10,
    "unit_price": 1234.567891,
    "counterparty": {
        "iselic_number": "33444555",
        "document_number": "33.444.555/0001-81",
        "selic_account_number": "123456789"
    },
    "isin_code": "BRSTNCNTB633",
    "issue_date": "2025-11-04",
    "operation_data": {}
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `operation_key` | string | Identificador único da operação gerado pela QI Tech (UUID). |
| `external_id` | string | Identificador externo fornecido ou gerado automaticamente. |
| `fund_class` | object | Dados do fundo associado à operação. |
| `status` | string | Status inicial da operação: sempre `pending_manager_approval`. Veja os [status da operação](/documentation/iaas/boletador/listagem_titulos_publicos#status-da-operacao). |
| `operation_part` | string | `assignee` (comprador) ou `assignor` (vendedor). |
| `operation_type` | object | `{ enumerator, code }` — tipo de operação e código SELIC correspondente. |
| `treasury` | object | `{ enumerator, code }` — tipo de título e código SELIC correspondente. |
| `operation_date` | string | Data da operação (`YYYY-MM-DD`). |
| `payment_date` | string | Data de liquidação (`YYYY-MM-DD`). |
| `maturity_date` | string | Data de vencimento do título (`YYYY-MM-DD`). |
| `total_operation_value` | decimal | Valor total da operação (units × unit_price). |
| `units` | integer | Quantidade de títulos. |
| `unit_price` | number | Preço unitário do título. |
| `counterparty` | object | Dados da contraparte (`iselic_number`, `document_number`, `selic_account_number`). |
| `isin_code` | string | Código ISIN do título. |
| `issue_date` | string | Data de emissão do título (`YYYY-MM-DD`). |
| `operation_data` | object | Metadados internos adicionais da operação. |
| `yearly_negotiated_rate`, `return_date`, `return_unit_price`, `total_return_value` | number / string | Dados do retorno. Presentes em `buyback_operation`. |
| `time_exception_reason` | string | Justificativa de horário. Presente quando a boleta foi enviada depois do corte. |

## Reenvio e duplicidade

Em caso de erro, reenvie a requisição. Duplicidade (`TTR000044`) significa que a boleta já existe: localize-a na [listagem](/documentation/iaas/boletador/listagem_titulos_publicos) filtrando por `operation_date` e procurando o seu `external_id` nos itens de `data`. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).

## Erros

| Status | Código | Quando acontece |
|---|---|---|
| 409 | `TTR000044` | Já existe boleta com este `external_id` no fundo. |
| 400 | `TTR000054` | Envio a partir das 16:55 (horário de Brasília) sem `time_exception_reason`. |
| 400 | `TTR000058` | Data inexistente em `operation_date`, `payment_date`, `maturity_date` ou `return_date` (por exemplo, `2025-02-30`). |
| 400 | `TTR000016` | `operation_date` diferente da data contábil do fundo. |
| 400 | `TTR000011` | `operation_date` não é dia útil. |
| 400 | `TTR000021` | `payment_date` diferente de `operation_date` numa operação que não é a termo. |
| 400 | `TTR000017` | `payment_date` anterior a `operation_date`. |
| 400 | `TTR000010` | `maturity_date` igual ou anterior a `operation_date`. |
| 400 | `TTR000057` | Venda (`operation_part: assignor`) com `units` acima das unidades deste título na carteira do fundo. |
| 400 | `TTR000037` | Não há título na ANBIMA com este `treasury_type` e `maturity_date`. |
| 400 | `TTR000018` / `TTR000019` / `TTR000020` | Compromissada sem `yearly_negotiated_rate`, sem `return_date`, ou com `return_date` igual ou anterior a `operation_date`. |
| 400 | `TTR000042` | `operation_type` não implementado, compromissada com `operation_part: assignor`, ou fundo sem compromissada habilitada. |
| 400 | `TTR000035` | CNPJ da contraparte inválido. |
| 400 | `TTR000027` / `TTR000028` / `TTR000029` / `TTR000038` / `TTR000048` | O cadastro do fundo para títulos públicos está incompleto (conta destino, custodiante, conta SELIC ou carteira). Fale com o time de integração. |
| 404 | `TTR000004` | A `fund_class_key` não existe. |
| 403 | `TTR000040` | O fundo não pertence à sua gestora. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# Consulta de Título Público

URL: /documentation/iaas/boletador/consulta_titulo_publico

Retorna uma boleta de título público pelo `operation_key`, com o histórico de status. Use para acompanhar a aprovação, o registro no SELIC e a liquidação da operação.

:::info Disponível em

| Perfil  | Host          | Permissão exigida |
| ------- | ------------- | ----------------- |
| Gestora | `manager-api` | Leitura           |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## Request

ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operation/{operation_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
| :---- | :---- | :---- |
| `fund_class_key` | string | Identificador único do fundo. |
| `operation_key` | string | Identificador da operação devolvido na [criação da boleta](/documentation/iaas/boletador/boletador_titulos_publicos). |

## Response

STATUS 200

```json title="Response Body"
{
    "operation_key": "85cfd700-54a4-40f4-bc61-2ece992864ea",
    "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b",
    "fund_class": {
        "fund_class_key": "5122bf31-660a-4f61-a447-38e5e17162dd",
        "manager_key": "bea7581a-f901-4995-a486-46e18ae61aab",
        "name": "FUNDO EXEMPLO DTVM",
        "document_number": "11.222.333/0001-81",
        "accounting_date": "2025-12-04",
        "internal_transfer_for_main_account": false
    },
    "status": "pending_registration",
    "operation_part": "assignee",
    "operation_type": {
        "enumerator": "outright_operation",
        "code": 1052
    },
    "treasury": {
        "enumerator": "ntn_b",
        "code": 760199
    },
    "operation_date": "2025-12-04",
    "payment_date": "2025-12-04",
    "maturity_date": "2035-05-15",
    "total_operation_value": 12345.67,
    "units": 10,
    "unit_price": 1234.567891,
    "counterparty": {
        "iselic_number": "33444555",
        "document_number": "33.444.555/0001-81",
        "selic_account_number": "123456789"
    },
    "isin_code": "BRSTNCNTB633",
    "issue_date": "2025-11-04",
    "operation_data": {},
    "status_events": [
        {
            "status": "pending_manager_approval",
            "metadata": {},
            "datetime": "2025-12-04 13:10:00.000000"
        },
        {
            "status": "pending_registration",
            "metadata": {},
            "datetime": "2025-12-04 13:25:00.000000"
        }
    ]
}
```

### Atributos da resposta

Os mesmos campos da [criação da boleta](/documentation/iaas/boletador/boletador_titulos_publicos#atributos-da-resposta), mais:

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `status` | string | Status atual. Veja os [status da operação](/documentation/iaas/boletador/listagem_titulos_publicos#status-da-operacao). |
| `status_events` | array | Histórico de status, com `status`, `metadata` e `datetime` de cada mudança. |
| `selic_operation_id`, `selic_specification_id`, `selic_command_number` | string | Identificadores no SELIC. Presentes depois do registro. |
| `yearly_negotiated_rate`, `return_date`, `return_unit_price`, `total_return_value` | number / string | Dados do retorno. Presentes em `buyback_operation`. |
| `time_exception_reason` | string | Justificativa de horário, quando houver. |
| `time_exception_released_at` | string | Data e hora em que a QI Tech liberou a boleta fora do horário. |

## Erros

| Status | Código | Quando acontece |
|---|---|---|
| 404 | `TTR000013` | Não existe operação com este `operation_key` no fundo. |
| 404 | `TTR000004` | A `fund_class_key` não existe. |
| 403 | `TTR000040` | O fundo não pertence à sua gestora. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# Listagem de Títulos Públicos

URL: /documentation/iaas/boletador/listagem_titulos_publicos

Lista, de forma paginada, as boletas de títulos públicos do fundo, das mais recentes para as mais antigas (por `operation_date`). Para uma operação específica, use a [consulta da operação](/documentation/iaas/boletador/consulta_titulo_publico).

:::info Disponível em

| Perfil  | Host          | Permissão exigida |
| ------- | ------------- | ----------------- |
| Gestora | `manager-api` | Leitura           |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## Request

ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operations
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
| :---- | :---- | :---- |
| `fund_class_key` | string | Identificador único do fundo. |

### Query params

| Parâmetro | Tipo | Padrão | Máximo | Descrição |
| :---- | :---- | :---- | :---- | :---- |
| `limit` | integer | 100 | 500 | Quantidade de itens por página. |
| `page` | integer | 0 | — | Número da página (base 0). |
| `status` | string | — | — | Filtra pelo status exato da operação. Veja [status da operação](#status-da-operacao). |
| `not_status` | string | — | — | Exclui operações com determinado status. |
| `status_list` | string | — | — | Lista de status separados por vírgula (ex.: `pending_manager_approval,pending_time_exception_approval`). |
| `operation_part` | string | — | — | Filtra pelo papel do fundo (`assignee` ou `assignor`). |
| `treasury_type` | string | — | — | Filtra por tipo de título (`lft`, `ltn`, `ntn_b`, `ntn_f`). |
| `operation_type` | string | — | — | Filtra por tipo de operação (`outright_operation`, `buyback_operation`). |
| `operation_date` | string | — | — | Filtra pela data exata da operação (`YYYY-MM-DD`). |
| `from_operation_date` | string | — | — | Filtra operações com data `>=` ao valor (`YYYY-MM-DD`). |
| `to_operation_date` | string | — | — | Filtra operações com data `<=` ao valor (`YYYY-MM-DD`). |
| `maturity_date` | string | — | — | Filtra pela data exata de vencimento (`YYYY-MM-DD`). |
| `from_maturity_date` | string | — | — | Filtra vencimentos `>=` ao valor (`YYYY-MM-DD`). |
| `to_maturity_date` | string | — | — | Filtra vencimentos `<=` ao valor (`YYYY-MM-DD`). |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "operation_key": "e96ff035-e0bc-4819-931a-6a9f7fc1c597",
            "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b",
            "fund_class": {
                "fund_class_key": "9b6145dc-2207-428d-84c1-2f949461891a",
                "manager_key": "73a21e11-0ab7-461d-a93f-1e90c0a5dc0d",
                "name": "FUNDO DE INVESTIMENTO TESTE",
                "document_number": "11.222.333/0001-81",
                "accounting_date": "2025-04-14",
                "internal_transfer_for_main_account": false,
                "custodian": {
                    "name": "CUSTODIANTE EXEMPLO",
                    "document_number": "44.555.666/0001-81",
                    "iselic_number": "44555666"
                },
                "selic_account_number": "000216832",
                "target_account_key": "d3dcbf3c-1bbf-495b-b792-ac448ee20ac4"
            },
            "status": "pending_manager_approval",
            "operation_part": "assignee",
            "operation_type": {
                "enumerator": "outright_operation",
                "code": 1052
            },
            "treasury": {
                "enumerator": "ntn_b",
                "code": 760199
            },
            "operation_date": "2025-04-14",
            "payment_date": "2025-04-14",
            "maturity_date": "2025-05-15",
            "total_operation_value": 250.0,
            "units": 5,
            "unit_price": 50.0,
            "counterparty": {
                "iselic_number": "33444555",
                "document_number": "33.444.555/0001-81",
                "selic_account_number": "123456789"
            },
            "isin_code": "BRSTNCNTB633",
            "issue_date": "2000-07-15",
            "operation_data": {}
        }
    ],
    "limit": 100,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `data` | array | Lista de operações. Cada item contém os mesmos campos da consulta individual. |
| `limit` | integer | Quantidade de itens retornados na página. |
| `page` | integer | Página atual (base 0). |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

Cada operação pode trazer ainda, quando já existirem, `selic_operation_id`, `selic_specification_id`, `selic_command_number`, os dados de retorno da compromissada (`yearly_negotiated_rate`, `return_date`, `return_unit_price`, `total_return_value`), `time_exception_reason` e `time_exception_released_at`.

## Status da operação

| Etapa | Status | Significado |
|---|---|---|
| Aprovação | `pending_manager_approval` | Aguardando a aprovação da gestora no portal. Status inicial de toda boleta. |
| Aprovação | `pending_time_exception_approval` | A gestora pediu liberação de horário depois das 16:55; aguarda a equipe QI Tech. |
| Aprovação | `pending_administrator_approval` | Aguardando o administrador (status legado). |
| Pré-matching | `pending_registration`, `pending_counterparty_registration`, `pending_specification`, `pending_counterparty_specification`, `pending_specification_confirmation`, `pending_counterparty_specification_confirmation` | Registro e especificação no SELIC, do lado do fundo e da contraparte. |
| Pré-matching | `specification_mismatched` | Os dados lançados pela contraparte no SELIC não batem com os da boleta; a QI Tech trata a divergência. |
| Pré-matching | `registration_failed` | O SELIC recusou o registro da boleta. O motivo fica no `metadata` do evento em `status_events`. A QI Tech reenvia ao SELIC, ou a gestora cancela a operação no portal. |
| Liquidação | `pending_payment`, `pending_payment_confirmation`, `pending_internal_transfer`, `pending_internal_transfer_confirmation`, `pending_order_creation`, `pending_order_confirmation`, `pending_order_expectation_creation`, `pending_order_expectation_confirmation`, `pending_expectation_confirmation`, `pending_spb_message`, `pending_spb_message_confirmation` | Liquidação financeira da operação. |
| Liquidação | `pending_manual_order_validation` | Divergência na liquidação; a QI Tech confere a operação manualmente. |
| Encarteiramento | `pending_wallet_inclusion` | Inclusão do título na carteira do fundo. |
| Retorno | `pending_buyback_expectation_creation`, `pending_buyback_expectation_confirmation` | Retorno da compromissada (só `buyback_operation`). |
| Final | `operation_finished` | Operação concluída. |
| Final | `canceled` | Operação cancelada. |

## Erros

| Status | Código | Quando acontece |
|---|---|---|
| 400 | `TTR000041` | Valor inválido em `status`, `not_status`, `status_list`, `treasury_type`, `operation_type` ou `operation_part`. |
| 400 | `QIT000010` | Parâmetro de query inválido: data fora de `YYYY-MM-DD`, `limit` acima de 500 ou `page` negativo. |
| 404 | `TTR000004` | A `fund_class_key` não existe. |
| 403 | `TTR000040` | O fundo não pertence à sua gestora. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).