Pular para o conteúdo principal

Boletador de Títulos Públicos

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.

Disponível em
PerfilHostPermissão exigida
Gestoramanager-apiEscrita

URL base de cada host: Ambientes (Hosts).

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 ou pela listagem.

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âmetroTipoDescrição
fund_class_keystringIdentificador único do fundo.
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​

CampoTipoObrigatoriedadeDescrição
external_idstringopcionalSeu identificador da boleta, único por fundo. Se não informado, será gerado automaticamente (UUID). Máximo de 36 caracteres. Veja Reenvio e duplicidade.
operation_datestring (date)obrigatórioData da operação no formato YYYY-MM-DD. Deve ser um dia útil e igual à accounting_date do fundo.
payment_datestring (date)obrigatórioData 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_partstringobrigatórioPapel 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_typestringobrigatórioTipo 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).
counterpartyobjectobrigatórioDados da contraparte. Ver objeto abaixo.
treasury_typestringobrigatórioTipo de título: lft, ltn, ntn_b ou ntn_f.
unit_pricenumberobrigatórioPreç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.
unitsintegerobrigatórioQuantidade de títulos (inteiro positivo).
maturity_datestring (date)obrigatórioData de vencimento do título (YYYY-MM-DD). Deve ser estritamente posterior à operation_date.
yearly_negotiated_ratenumbercondicionalTaxa negociada anual, em forma decimal (0.144 = 14,4% a.a.). Obrigatório para buyback_operation.
return_datestring (date)condicionalData de retorno (YYYY-MM-DD). Obrigatório para buyback_operation. Deve ser > operation_date.
time_exception_reasonstringcondicionalJustificativa 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​

CampoTipoObrigatoriedadeDescrição
iselic_numberstringobrigatórioNúmero iSELIC da contraparte (8 dígitos).
selic_account_numberstringobrigatórioConta SELIC da contraparte (9 dígitos).
document_numberstringobrigatórioCNPJ da contraparte com pontuação (formato XX.XXX.XXX/XXXX-XX), com dígito verificador válido.

Response​

STATUS
201
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​

CampoTipoDescrição
operation_keystringIdentificador único da operação gerado pela QI Tech (UUID).
external_idstringIdentificador externo fornecido ou gerado automaticamente.
fund_classobjectDados do fundo associado à operação.
statusstringStatus inicial da operação: sempre pending_manager_approval. Veja os status da operação.
operation_partstringassignee (comprador) ou assignor (vendedor).
operation_typeobject{ enumerator, code } — tipo de operação e código SELIC correspondente.
treasuryobject{ enumerator, code } — tipo de título e código SELIC correspondente.
operation_datestringData da operação (YYYY-MM-DD).
payment_datestringData de liquidação (YYYY-MM-DD).
maturity_datestringData de vencimento do título (YYYY-MM-DD).
total_operation_valuedecimalValor total da operação (units × unit_price).
unitsintegerQuantidade de títulos.
unit_pricenumberPreço unitário do título.
counterpartyobjectDados da contraparte (iselic_number, document_number, selic_account_number).
isin_codestringCódigo ISIN do título.
issue_datestringData de emissão do título (YYYY-MM-DD).
operation_dataobjectMetadados internos adicionais da operação.
yearly_negotiated_rate, return_date, return_unit_price, total_return_valuenumber / stringDados do retorno. Presentes em buyback_operation.
time_exception_reasonstringJustificativa 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 filtrando por operation_date e procurando o seu external_id nos itens de data. Veja Reenvio e duplicidade.

Erros​

StatusCódigoQuando acontece
409TTR000044Já existe boleta com este external_id no fundo.
400TTR000054Envio a partir das 16:55 (horário de Brasília) sem time_exception_reason.
400TTR000058Data inexistente em operation_date, payment_date, maturity_date ou return_date (por exemplo, 2025-02-30).
400TTR000016operation_date diferente da data contábil do fundo.
400TTR000011operation_date não é dia útil.
400TTR000021payment_date diferente de operation_date numa operação que não é a termo.
400TTR000017payment_date anterior a operation_date.
400TTR000010maturity_date igual ou anterior a operation_date.
400TTR000057Venda (operation_part: assignor) com units acima das unidades deste título na carteira do fundo.
400TTR000037Não há título na ANBIMA com este treasury_type e maturity_date.
400TTR000018 / TTR000019 / TTR000020Compromissada sem yearly_negotiated_rate, sem return_date, ou com return_date igual ou anterior a operation_date.
400TTR000042operation_type não implementado, compromissada com operation_part: assignor, ou fundo sem compromissada habilitada.
400TTR000035CNPJ da contraparte inválido.
400TTR000027 / TTR000028 / TTR000029 / TTR000038 / TTR000048O cadastro do fundo para títulos públicos está incompleto (conta destino, custodiante, conta SELIC ou carteira). Fale com o time de integração.
404TTR000004A fund_class_key não existe.
403TTR000040O fundo não pertence à sua gestora.

Erros de autenticação, permissão e host: veja Erros da API.