# QI Tech — Investment-as-a-Service › 负债 Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 34 página(s). Índice: - 获取投资者持仓信息 (/zh-Hans/documentation/iaas/investidor/informacoes_posicao_investidor) - Listagem de Solicitações de Amortização (/zh-Hans/documentation/iaas/passivo/amortizacao/listagem) - 分页查询金融申请 (/zh-Hans/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras) - 金融申请结算分页查询 (/zh-Hans/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras) - 按键查询金融申请 (/zh-Hans/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave) - 创建金融申请 (/zh-Hans/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira) - 手动批准份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/aprovar_bloqueio_pendente_aprovacao) - 查询份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas) - 查询投资者的份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas_de_um_investidor) - 发送担保文件 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_da_garantia) - 发送资产文件 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_do_ativo) - 担保执行 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/execucao_de_garantia) - 减少份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/reduzir_bloqueio_de_cotas) - 申请份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas) - 份额锁定 Webhook (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota) - Consulta paginada de investidores por classe de fundo (/zh-Hans/documentation/iaas/passivo/consultas/consulta_investidores_classe_fundo) - Consulta paginada de posições de cotistas por classe de fundo (/zh-Hans/documentation/iaas/passivo/consultas/consulta_posicoes_cotistas_classe_fundo) - 发行系列结算分页查询 (/zh-Hans/documentation/iaas/passivo/consultas/consultar_fechamentos_serie_de_emissao) - 份额演变图分页查询 (/zh-Hans/documentation/iaas/passivo/consultas/consultar_mapa_de_evolucao_de_cotas) - 发行系列分页查询 (/zh-Hans/documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao) - 基金分页查询 (/zh-Hans/documentation/iaas/passivo/consultas/consultar_todos_fundos) - 发送已签署认购公告 (/zh-Hans/documentation/iaas/passivo/controle_de_oferta/enviar_boletim_de_subscricao_assinado) - 获取认购公告信息 (/zh-Hans/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao) - 获取发行信息 (/zh-Hans/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas) - 申请认购公告 (/zh-Hans/documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao) - 获取公开份额 (/zh-Hans/documentation/iaas/passivo/fundos/cotas_publicas) - 简介 (/zh-Hans/documentation/iaas/passivo/inicio) - Consulta paginada de negociações em mercado secundário (/zh-Hans/documentation/iaas/passivo/mercado_secundario/consulta_negociacoes_mercado_secundario) - 按键查询赎回申请 (/zh-Hans/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave) - Consulta paginada de pedidos de resgate por classe de fundo (/zh-Hans/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo) - Consulta paginada de pedidos de resgate por investidor (/zh-Hans/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor) - 创建赎回申请 (/zh-Hans/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate) - 发送已签署入会协议 (/zh-Hans/documentation/iaas/passivo/termo_de_adesao/enviar_termo_de_adesao_assinado) - Solicitar Termo de Adesão (/zh-Hans/documentation/iaas/passivo/termo_de_adesao/solicitar_termo_de_adesao) --- # 获取投资者持仓信息 URL: /zh-Hans/documentation/iaas/investidor/informacoes_posicao_investidor 分页返回投资者在其持有份额的每个发行系列中的持仓。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ### Request ENDPOINT /quota/investor/INVESTOR_KEY/investor_positions MÉTODO GET ### Query Params | 参数 | 类型 | 描述 | |------------------------------|---------|--------------------------------------------------------------------------------------| | `issuance_serie_key` | string | 按发行系列筛选 | | `fund_class_document_number` | string | 按基金类别 CNPJ 筛选 | | `only_active_funds` | boolean | `true` 时仅返回投资者持有份额（数量大于零）的系列。默认：`false` | | `number_of_quotas_str` | boolean | `true` 时以字符串返回份额数量，不损失精度。默认：`false` | | `page` | integer | 页码，从 `0` 开始。默认：`0` | | `limit` | integer | 每页条数。默认：`20`；最大：`100` | 当 `is_last_page` 为 `false` 时，递增 `page` 以遍历各页。 ### Responses STATUS 200 案例 01：投资者仅持有一个单一份额（COTA ÚNICA）系列的持仓 ```json { "data": [ { "investor_position_key":"UUID", "investor": { "distributor": { "distributor_key": "UUID", "document_number": "33.444.555/0001-81", "name": "SAMPLE DISTRIBUTOR NAME", "account_data": { "owner": { "name": "SAMPLE DISTRIBUTOR NAME", "document_number": "33.444.555/0001-81" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" } }, "investor_key": "UUID", "document_number": "969.698.790-03", "name": "SAMPLE INVESTOR NAME", "person_type": "natural_person / legal_person / fund_class", "account_data": { "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, "investor_sub_type": "person / financial_institution" }, "number_of_quotas": 1000.0, "quota_value": 1.05, "issuance_serie": { "name": "1", "cetip_code": "0000000UN1", "start_date": "YYYY-MM-DD", "maturity_date": "YYYY-MM-DD", "original_quota_value": 0.00000000000000, "remuneration_type": "residual", "investment_category": "fidc / multi_market", "condominum_type": "open_ended / close_ended", "tax_classification": "short_term / long_term", "investment_restriction_type": "just_professional", "issuance_serie_key": "UUID", "accounting_date": "YYYY-MM-DD", "sub_class": { "name": "COTA ÚNICA", "sub_class_key": "UUID", "subordination_level": 0, "fund_class": { "name": "SAMPLE FUND CLASS NAME", "fund_class_key": "UUID", "document_number": "44.555.666/0001-81" } } } } ], "limit": 20, "page": 0, "is_last_page": true } ``` 案例 02：投资者仅持有一个优先份额（COTA SÊNIOR）系列的持仓 ```json { "data": [ { "investor_position_key":"UUID", "investor": { "distributor": { "distributor_key": "UUID", "document_number": "33.444.555/0001-81", "name": "SAMPLE DISTRIBUTOR NAME", "account_data": { "owner": { "name": "SAMPLE DISTRIBUTOR NAME", "document_number": "33.444.555/0001-81" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" } }, "investor_key": "UUID", "document_number": "969.698.790-03", "name": "SAMPLE INVESTOR NAME", "person_type": "natural_person / legal_person / fund_class", "account_data": { "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, "investor_sub_type": "person / financial_institution" }, "number_of_quotas": 1000.0, "quota_value": 1.05, "issuance_serie": { "name": "1", "cetip_code": "0000000SN1", "start_date": "YYYY-MM-DD", "maturity_date": "YYYY-MM-DD", "original_quota_value": 0.00000000000000, "remuneration_type": "yield_curve", "interest_rate_type": "post_fixed", "pre_fixed": { "calendar_base": "workdays / calendar_360 / calendar_365", "monthly_rate": 0.00000000000000 }, "post_fixed": { "calendar_base": "workdays / calendar_360 / calendar_365", "indexer": "di / ipca", "rate": 1, "lag": {"reference": "daily / monthly", "amount": 1} }, "investment_category": "fidc / multi_market", "condominum_type": "open_ended / close_ended", "tax_classification": "short_term / long_term", "investment_restriction_type": "just_professional", "issuance_serie_key": "UUID", "accounting_date": "YYYY-MM-DD", "sub_class": { "name": "COTA SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "name": "SAMPLE FUND CLASS NAME", "fund_class_key": "UUID", "document_number": "44.555.666/0001-81" } } } } ], "limit": 20, "page": 0, "is_last_page": true } ``` 案例 03：投资者持有两个系列的持仓，一个优先份额（COTA SÊNIOR）和一个次级份额（COTA SUBORDINADA） ```json { "data":[ { "investor_position_key":"UUID", "investor":{ "distributor":{ "distributor_key":"UUID", "document_number":"33.444.555/0001-81", "name":"SAMPLE DISTRIBUTOR NAME", "account_data":{ "owner":{ "name":"SAMPLE DISTRIBUTOR NAME", "document_number":"33.444.555/0001-81" }, "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" } }, "investor_key":"UUID", "document_number":"969.698.790-03", "name":"SAMPLE INVESTOR NAME", "person_type":"natural_person / legal_person / fund_class", "account_data":{ "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" }, "investor_sub_type":"person / financial_institution" }, "number_of_quotas": 1000.0, "quota_value": 1.05, "issuance_serie":{ "name":"1", "cetip_code":"0000000SN1", "start_date":"YYYY-MM-DD", "maturity_date":"YYYY-MM-DD", "original_quota_value":0.00000000000000, "remuneration_type":"yield_curve", "interest_rate_type":"post_fixed", "pre_fixed":{ "calendar_base":"workdays / calendar_360 / calendar_365", "monthly_rate":0.00000000000000 }, "post_fixed":{ "calendar_base":"workdays / calendar_360 / calendar_365", "indexer":"di / ipca", "rate":1, "lag":{ "reference":"daily / monthly", "amount":1 } }, "investment_category":"fidc / multi_market", "condominum_type":"open_ended / close_ended", "tax_classification":"short_term / long_term", "investment_restriction_type":"just_professional", "issuance_serie_key":"UUID", "accounting_date":"YYYY-MM-DD", "sub_class":{ "name":"COTA SÊNIOR", "sub_class_key":"UUID", "subordination_level":1, "fund_class":{ "name":"SAMPLE FUND CLASS NAME", "fund_class_key":"UUID", "document_number":"44.555.666/0001-81" } } } }, { "investor_position_key":"UUID", "investor":{ "distributor":{ "distributor_key":"UUID", "document_number":"33.444.555/0001-81", "name":"SAMPLE DISTRIBUTOR NAME", "account_data":{ "owner":{ "name":"SAMPLE DISTRIBUTOR NAME", "document_number":"33.444.555/0001-81" }, "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" } }, "investor_key":"UUID", "document_number":"969.698.790-03", "name":"SAMPLE INVESTOR NAME", "person_type":"natural_person / legal_person / fund_class", "account_data":{ "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" }, "investor_sub_type":"person / financial_institution" }, "number_of_quotas": 1000.0, "quota_value": 1.05, "issuance_serie":{ "name":"1", "cetip_code":"0000000JR1", "start_date":"YYYY-MM-DD", "maturity_date":"YYYY-MM-DD", "original_quota_value":0.00000000000000, "remuneration_type":"residual", "investment_category":"fidc / multi_market", "condominum_type":"open_ended / close_ended", "tax_classification":"short_term / long_term", "investment_restriction_type":"just_professional", "issuance_serie_key":"UUID", "accounting_date":"YYYY-MM-DD", "sub_class":{ "name":"COTA SUBORDINADA", "sub_class_key":"UUID", "subordination_level":0, "fund_class":{ "name":"SAMPLE FUND CLASS NAME", "fund_class_key":"UUID", "document_number":"44.555.666/0001-81" } } } } ], "limit": 20, "page":0, "is_last_page":true } ``` ### 响应字段 | 字段 | 类型 | 描述 | |---------------|--------|----------------------------------------------------------------| | `data` | array | **[Investor Position](#investor_position)** 对象列表| | `limit` | int | 每页返回的对象数量上限 | | `page` | int | 返回的页码 | | `is_last_page`| boolean| 表示返回的页是否为最后一页 | ### Investor Position {#investor_position} | 字段 | 类型 | 描述 | |--------------------------|--------|-------------------------------------------------------| | `investor` | JSON | **[Investor](#investor)** 对象 | | `number_of_quotas` | float | 投资者在该系列中的份额数量 | | `number_of_quotas_str` | string | 同一数值的字符串形式。仅在 `number_of_quotas_str=true` 时返回 | | `quota_value` | float | 该系列最近一次结算的份额价值。若该系列尚无结算则不返回 | | `issuance_serie` | JSON | **[Issuance Serie](#issuance_serie)** 对象 | | `investor_position_key` | string | 投资者持仓唯一标识键 | ### Investor | 字段 | 类型 | 描述 | 字符数 | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | 投资者姓名 | 最多 255 | | `investor_key` | string | 投资者唯一标识键 | 36 | | `document_number` | string | 投资者 CPF/CNPJ | 14 或 18 | | `person_type` | string | 自然人 / 法人 / 基金类别 | 最多 50 | | `investor_sub_type` | string | 默认 / 金融机构 | 最多 50 | | `distributor` | JSON | **[Distributor](#distributor)** 对象 | - | | `account_data` | JSON | **[Account Data](#account_data)** 对象 | - | ### Distributor | 字段 | 类型 | 描述 | 字符数 | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | 分销商名称 | 最多 255 | | `distributor_key` | string | 分销商唯一标识键 | - | | `document_number` | string | 分销商 CPF/CNPJ | 14 或 18 | | `account_data` | JSON | **[Account Data](#account_data)** 对象 | - | ### Account Data {#account_data} | 字段 | 类型 | 描述 | |------------------------------|----------|-----------------------------------------------------------------------------| | `account_digit` | string | 银行账号校验位 | | `account_branch` | string | 银行账户支行号 | | `account_number` | string | 银行账号 | | `financial_institution_code` | string | 金融机构代码 | | `financial_institution_ispb` | string | 金融机构在巴西支付系统中的标识符 | ### Issuance Serie {#issuance_serie} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | 发行系列名称 | 最多 255 | | `issuance_serie_key` | string | 发行系列唯一标识键 | 36 | | `cetip_code` | string | 发行系列在 CETIP 中的资产代码 | 10 | | `start_date` | string | 发行系列起始日期 | 10 | | `maturity_date` | string | 发行系列到期日期 | 10 | | `original_quota_value` | float | 原始份额价值 | - | | `remuneration_type` | string | 收益曲线 / 剩余 | 最多 50 | | `investment_category` | string | FIDC / 多市场 | 最多 50 | | `condominum_type` | string | 开放式 / 封闭式 | 最多 50 | | `tax_classification` | string | 短期 / 长期 | 最多 50 | | `investment_restriction_type` | string | 无限制 / 合格投资者 / 专业投资者 | 最多 50 | | `accounting_date` | string | 发行系列会计日期 | 10 | | `sub_class` | JSON | **[Sub Class](#sub_class)** 对象 | - | ### Sub Class {#sub_class} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | 子类别名称 | 最多 255 | | `sub_class_key` | string | 子类别唯一标识键 | 36 | | `subordination_level` | int | 子类别的次级层级 | - | | `fund_class` | JSON | **[Fund Class](#fund_class)** 对象 | - | ### Fund Class {#fund_class} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | 基金类别名称 | 最多 255 | | `fund_class_key` | string | 基金类别唯一标识键 | 36 | | `document_number` | string | 基金类别 CNPJ | - | ## 错误 | 状态 | 代码 | 发生情形 | | ---- | ---- | -------- | | 400 | — | `limit` 超过 100 或 `page` 为负数 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # Listagem de Solicitações de Amortização URL: /zh-Hans/documentation/iaas/passivo/amortizacao/listagem Endpoint de consulta paginada que retorna as solicitações de amortização de uma determinada classe de fundo. A resposta inclui, para cada solicitação, os dados financeiros calculados, o histórico de status, as amortizações por investidor e os dados da série de emissão vinculada. :::info Filtros de retorno Por padrão, todos os sub-objetos (`issuance_serie`, `investor_amortizations` e `status_events`) são retornados. Utilize os query params `dto_filters_*` para omitir campos e reduzir o tamanho da resposta. ::: :::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 /quota/fund_class/{fund_class_key}/amortization_requests MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única da classe de fundo (UUID). | ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `20`. Máximo: `100`. | | `status` | array de strings | opcional | Um ou mais status da solicitação (veja [Enumeradores de `status`](#enumeradores-de-status)). Repita o parâmetro para enviar mais de um. | | `issuance_serie_key` | string | opcional | Filtra por série de emissão. | | `quotation_date` | string | opcional | Filtra pela data de cotização (`YYYY-MM-DD`). | | `dto_filters_issuance_serie` | string | opcional | Envie `true` para omitir o objeto `issuance_serie` de cada item. | | `dto_filters_investor_amortizations` | string | opcional | Envie `true` para omitir o array `investor_amortizations` de cada item. | | `dto_filters_status_events` | string | opcional | Envie `true` para omitir o array `status_events` de cada item. | :::caution Atenção Os parâmetros `dto_filters_*` omitem o campo com **qualquer** valor não vazio — inclusive `false`. Para receber o campo, não envie o parâmetro. ::: Os resultados vêm da data de cotização mais recente para a mais antiga. ```text title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/amortization_requests?page=0&limit=20 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "amortization_request_key": "3571e292-3a83-4011-904d-20ee963022ef", "type": "scheduled_amortization", "regime_type": "issuance_serie_principal_percentage", "quotation_date": "2026-06-05", "principal_percentage": 0.5, "financial_application_yield_percentage": 0.12, "gross_value": 10000.0, "result_quota_value": 1.05, "amortization_value": 5000.0, "net_value": 4750.0, "quota_percentage": 0.5, "status": "done", "status_events": [ { "status": "created", "event_datetime": "2026-06-01T10:00:00.000Z" }, { "status": "done", "event_datetime": "2026-06-05T14:30:00.000Z" } ], "investor_amortizations": [ { "investor_amortization_key": "f1e2d3c4-b5a6-7890-fedc-ba9876543210", "investor": { "investor_key": "aaaa1111-bbbb-2222-cccc-dddd33334444", "name": "Investidor Exemplo S.A.", "person_type": "legal_person", "document_number": "11.222.333/0001-81", "distributor": { "distributor_key": "dddd4444-eeee-5555-ffff-aaaa66667777", "name": "Distribuidora Exemplo", "document_number": "22.333.444/0001-81", "account_data": { "bank": "341", "agency": "1234", "account": "56789-0" } } }, "status": "done", "net_value": 4750.0, "ir_value": 200.0, "iof_value": 50.0, "ir_compensation": 0.0, "iof_compensation": 0.0, "total_value": 5000.0, "payment_method": "regular", "payment_date": "2026-06-06", "status_events": [ { "status": "created", "event_datetime": "2026-06-01T10:00:00.000Z" }, { "status": "done", "event_datetime": "2026-06-06T09:00:00.000Z" } ], "amortizations": [ { "financial_application_key": "fa111111-2222-3333-4444-555566667777", "amortization_key": "am888888-9999-aaaa-bbbb-ccccddddeeee", "status": "settled", "principal_reduction": 2500.0, "acquisition_cost_reduction": 0.0, "yield_value": 300.0, "total_value": 2800.0, "ir_value": 100.0, "iof_value": 25.0, "taxable_yield_value": 300.0 } ], "payments": [ { "payment_key": "pp000000-1111-2222-3333-444455556666", "origin_key": "f1e2d3c4-b5a6-7890-fedc-ba9876543210", "total_value": 4750.0, "target_account": { "bank": "341", "agency": "1234", "account": "56789-0" }, "payment_type": "amortization_payment.investor", "payment_date": "2026-06-06", "status": "paid", "status_events": [ { "status": "paid", "event_datetime": "2026-06-06T09:15:00.000Z" } ] } ] } ], "issuance_serie": { "issuance_serie_key": "is111111-2222-3333-4444-555566667777", "name": "Série A - Cota Sênior", "serie": 1, "original_quota_value": 1.0, "current_quota_value": 1.05, "current_number_of_quotas": 1000000.0, "current_net_worth": 1050000.0, "current_principal_value": 1000000.0, "performance_fee_current_value": 0.0, "remuneration_type": "yield_curve", "status": "active", "internal_code": "SR-001", "sub_class": { "sub_class_key": "sc222222-3333-4444-5555-666677778888", "name": "Classe Sênior", "subordination_level": 1, "fund_class": { "fund_class_key": "fc333333-4444-5555-6666-777788889999", "name": "Fundo de Investimento em Direitos Creditórios Exemplo", "short_name": "FIDC Exemplo", "document_number": "33.444.555/0001-81", "accounting_date": "2026-06-09", "sub_type": "regular", "tax_classification": "long_term", "condominum_type": "closed", "investment_category": "credit_rights", "prevent_payment": false, "manager": { "manager_key": "mg444444-5555-6666-7777-888899990000", "name": "Gestora Exemplo DTVM", "document_number": "44.555.666/0001-81" } } } } } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de solicitações de amortização. Veja tabela abaixo. | | `page` | integer | Número da página atual. | | `limit` | integer | Quantidade de registros por página. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada solicitação (objetos dentro de `data`) | Campo | Tipo | Descrição | |---|---|---| | `amortization_request_key` | string | Identificador único da solicitação (UUID). | | `type` | string | Tipo da amortização. Consulte os [enumeradores de tipo](#enumeradores-de-type) abaixo. | | `regime_type` | string | Regime de cálculo da amortização. Consulte os [enumeradores de regime](#enumeradores-de-regime_type) abaixo. | | `quotation_date` | string | Data de cotização no formato `YYYY-MM-DD`. | | `principal_percentage` | number | Percentual do principal a ser amortizado. Presente conforme o `regime_type`. | | `financial_application_yield_percentage` | number | Percentual de rendimento da aplicação financeira. Presente conforme o `regime_type`. | | `gross_value` | number | Valor bruto total da amortização em reais. | | `result_quota_value` | number | Valor da cota resultante após a amortização. | | `amortization_value` | number | Valor total a ser amortizado em reais. | | `net_value` | number | Valor líquido total após impostos em reais. | | `quota_percentage` | number | Percentual de cotas resgatadas. Presente conforme o `regime_type`. | | `status` | string | Status atual da solicitação. Consulte os [enumeradores de status](#enumeradores-de-status) abaixo. | | `status_events` | array | Histórico de transições de status. Omitido se `dto_filters_status_events=true`. Veja tabela abaixo. | | `investor_amortizations` | array | Lista de amortizações individuais por investidor. Omitido se `dto_filters_investor_amortizations=true`. Veja tabela abaixo. | | `issuance_serie` | object | Dados da série de emissão vinculada. Omitido se `dto_filters_issuance_serie=true`. Veja tabela abaixo. | #### Atributos de `status_events` | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status do evento. | | `event_datetime` | string | Data e hora do evento no formato ISO 8601 (ex: `2026-06-01T10:00:00.000Z`). | #### Atributos de `investor_amortizations` | Campo | Tipo | Descrição | |---|---|---| | `investor_amortization_key` | string | Identificador único da amortização do investidor (UUID). | | `investor` | object | Dados do investidor. Veja tabela abaixo. | | `status` | string | Status da amortização do investidor. Consulte os [enumeradores de status do investidor](#enumeradores-de-status-do-investor_amortization) abaixo. | | `net_value` | number | Valor líquido a pagar ao investidor em reais. | | `ir_value` | number | Valor de IR retido em reais. | | `iof_value` | number | Valor de IOF retido em reais. | | `ir_compensation` | number | Compensação de IR em reais. | | `iof_compensation` | number | Compensação de IOF em reais. | | `total_value` | number | Valor total bruto em reais. Presente após o cálculo. | | `payment_method` | string | Método de pagamento. Consulte os [enumeradores de método de pagamento](#enumeradores-de-payment_method) abaixo. | | `payment_date` | string | Data prevista do pagamento no formato `YYYY-MM-DD`. | | `status_events` | array | Histórico de transições de status do investidor. Mesma estrutura de `status_events` da solicitação. | | `amortizations` | array | Detalhamento por aplicação financeira. Veja tabela abaixo. | | `payments` | array | Lista de pagamentos gerados. Veja tabela abaixo. | #### Atributos de `investor` | Campo | Tipo | Descrição | |---|---|---| | `investor_key` | string | Chave única do investidor (UUID). | | `name` | string | Nome do investidor. | | `person_type` | string | Tipo de pessoa (`natural_person`, `legal_person` ou `nominee`). | | `document_number` | string | CPF ou CNPJ do investidor. Presente quando disponível. | | `external_id` | string | Identificador externo do investidor. Presente quando informado. | | `external_distribution_key` | string | Chave de distribuição externa. Presente quando informada. | | `short_name` | string | Nome abreviado. Presente quando informado. | | `sub_type` | string | Subtipo do investidor. Presente quando informado. | | `distributor` | object | Dados da distribuidora vinculada. Veja tabela abaixo. | #### Atributos de `distributor` | Campo | Tipo | Descrição | |---|---|---| | `distributor_key` | string | Chave única da distribuidora (UUID). | | `name` | string | Nome da distribuidora. | | `document_number` | string | CNPJ da distribuidora. | | `account_data` | object | Dados bancários da distribuidora. | #### Atributos de `amortizations` {#amortizations} | Campo | Tipo | Descrição | |---|---|---| | `financial_application_key` | string | Chave da aplicação financeira (UUID). | | `amortization_key` | string | Chave única da amortização (UUID). | | `status` | string | Status da amortização. | | `principal_reduction` | number | Redução de principal em reais. | | `acquisition_cost_reduction` | number | Redução de custo de aquisição em reais. | | `yield_value` | number | Valor de rendimento em reais. Presente quando calculado. | | `total_value` | number | Valor total em reais. Presente quando calculado. | | `ir_value` | number | Valor de IR em reais. Presente quando calculado. | | `iof_value` | number | Valor de IOF em reais. Presente quando calculado. | | `taxable_yield_value` | number | Valor de rendimento tributável em reais. Presente quando calculado. | #### Atributos de `payments` | Campo | Tipo | Descrição | |---|---|---| | `payment_key` | string | Chave única do pagamento (UUID). | | `origin_key` | string | Chave da origem do pagamento (UUID). | | `total_value` | number | Valor total do pagamento em reais. | | `target_account` | object | Dados da conta de destino. | | `description` | string | Descrição do pagamento. Presente quando informada. | | `payment_type` | string | Tipo do pagamento. Consulte os [enumeradores de tipo de pagamento](#enumeradores-de-payment_type) abaixo. | | `payment_date` | string | Data do pagamento no formato `YYYY-MM-DD`. | | `status` | string | Status do pagamento. Consulte os [enumeradores de status do pagamento](#enumeradores-de-status-do-payment) abaixo. | | `deleted_at` | string | Data e hora de exclusão no formato ISO 8601. Presente apenas quando o pagamento foi cancelado. | | `status_events` | array | Histórico de transições de status do pagamento. Mesma estrutura de `status_events` da solicitação. | #### Atributos de `issuance_serie` | Campo | Tipo | Descrição | |---|---|---| | `issuance_serie_key` | string | Chave única da série de emissão (UUID). | | `name` | string | Nome da série de emissão. | | `serie` | integer | Número da série. | | `original_quota_value` | number | Valor original da cota em reais. | | `current_quota_value` | number | Valor atual da cota em reais (calculado como `current_net_worth / current_number_of_quotas`). | | `current_number_of_quotas` | number | Quantidade atual de cotas em circulação. | | `current_net_worth` | number | Patrimônio líquido atual em reais. | | `current_principal_value` | number | Valor de principal atual em reais. | | `performance_fee_current_value` | number | Valor atual de taxa de performance em reais. | | `remuneration_type` | string | Tipo de remuneração da série. | | `status` | string | Status da série de emissão. | | `internal_code` | string | Código interno da série. | | `pre_fixed` | number | Taxa pré-fixada. Presente quando aplicável. | | `post_fixed` | object | Dados do indexador pós-fixado. Presente quando aplicável. | | `interest_rate_type` | string | Tipo de taxa de juros. Presente quando aplicável. | | `isin_code` | string | Código ISIN da série. Presente quando informado. | | `external_id` | string | Identificador externo. Presente quando informado. | | `specific_interest_rate_data` | object | Dados específicos de taxa de juros. Presente quando aplicável. | | `sub_class` | object | Dados da subclasse vinculada. Veja tabela abaixo. | #### Atributos de `sub_class` | Campo | Tipo | Descrição | |---|---|---| | `sub_class_key` | string | Chave única da subclasse (UUID). | | `name` | string | Nome da subclasse. | | `subordination_level` | integer | Nível de subordinação da subclasse. | | `fund_class` | object | Dados da classe de fundo. Veja tabela abaixo. | #### Atributos de `fund_class` | Campo | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única da classe de fundo (UUID). | | `name` | string | Nome do fundo. | | `short_name` | string | Nome abreviado do fundo. | | `document_number` | string | CNPJ do fundo. | | `accounting_date` | string | Data contábil vigente no formato `YYYY-MM-DD`. | | `sub_type` | string | Subtipo do fundo (`regular` ou `cash`). | | `tax_classification` | string | Classificação tributária do fundo. | | `condominum_type` | string | Tipo de condomínio do fundo. | | `investment_category` | string | Categoria de investimento. | | `prevent_payment` | boolean | Indica se pagamentos estão bloqueados para o fundo. | | `manager` | object | Dados do gestor do fundo. | | `administrator` | object | Dados do administrador. Presente quando informado. | | `integralization_account_key` | string | Chave da conta de integralização (UUID). Presente quando informada. | ## Enumeradores de `type` | Valor | Descrição | |---|---| | `scheduled_amortization` | Amortização programada/agendada | | `extraordinary_amortization` | Amortização extraordinária | ## Enumeradores de `regime_type` | Valor | Descrição | |---|---| | `cash_availability` | Baseado na disponibilidade de caixa | | `issuance_serie_principal_percentage` | Percentual do principal da série de emissão | | `quota_percentage` | Percentual de cotas | | `financial_application_principal_percentage` | Percentual do principal da aplicação financeira | | `net_value` | Valor líquido fixo | | `gross_value` | Valor bruto fixo | | `financial_application_yield_percentage` | Percentual de rendimento da aplicação financeira | ## Enumeradores de `status` | Status | Descrição | |---|---| | `created` | Solicitação criada | | `waiting_quotation_date` | Aguardando data de cotização | | `pending_inputs` | Aguardando dados de entrada | | `processing_calculation` | Cálculo em processamento | | `processing_investor_amortizations` | Processando amortizações dos investidores | | `pending_manual_approval` | Aguardando aprovação manual | | `processing_approval` | Aprovação em processamento | | `processing_issuance_serie_impacts` | Processando impactos na série de emissão | | `reprocessed` | Reprocessada | | `reproved` | Reprovada | | `done` | Concluída | | `blocked` | Bloqueada | ## Enumeradores de status do `investor_amortization` | Status | Descrição | |---|---| | `created` | Amortização do investidor criada | | `pending_quote` | Aguardando cotação | | `processing_approval` | Aprovação em processamento | | `pending_manual_approval` | Aguardando aprovação manual | | `done` | Concluída | | `reproved` | Reprovada | | `reprocessed` | Reprocessada | | `blocked` | Bloqueada | ## Enumeradores de `payment_method` | Valor | Descrição | |---|---| | `regular` | Pagamento padrão (TED/PIX) | | `b3` | Pagamento via B3 | ## Enumeradores de `payment_type` | Valor | Descrição | |---|---| | `amortization_payment.investor` | Pagamento de amortização ao investidor | | `amortization_payment.ir` | Recolhimento de IR da amortização | | `amortization_payment.iof` | Recolhimento de IOF da amortização | | `amortization_payment.collateral` | Pagamento de garantia da amortização | | `redemption.investor` | Pagamento de resgate ao investidor | | `redemption.ir` | Recolhimento de IR do resgate | | `redemption.iof` | Recolhimento de IOF do resgate | | `redemption.integralization_iof` | Recolhimento de IOF de integralização do resgate | | `redemption.tax_anticipation` | Antecipação de tributos do resgate | ## Enumeradores de status do `payment` | Status | Descrição | |---|---| | `created` | Pagamento criado | | `pending_payment` | Aguardando pagamento | | `pending_manual_approval` | Aguardando aprovação manual | | `pending_confirmation` | Aguardando confirmação | | `pending_accounting_date` | Aguardando data contábil | | `paid` | Pago | | `canceled` | Cancelado | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------- | | 400 | `QIT000004` | O fundo não é da gestora | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 分页查询金融申请 URL: /zh-Hans/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras 分页列出某份额持有人或某基金类别的金融申请。 ## 按份额持有人 返回某份额持有人的金融申请。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ENDPOINT /quota/investor/INVESTOR_KEY/financial_applications MÉTODO GET STATUS 200 对于管理人，查询仅返回其自身基金中、且属于与其关联的投资者的申请。 ### Query Params | 参数 | 描述 | | ---------------------------- | --------------------------------------------------------------------------------------------- | | `page` | 页码，从 0 开始（默认 0） | | `limit` | 每页条目数（默认 20，最大 500） | | `status` | **[Financial Application Status](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave#financial_application_status)** 列表 | | `types` | 类型列表：`primary_market`、`secondary_market` | | `issuance_serie_key` | 按发行系列过滤 | | `quotation_date` | 计价日期（`yyyy-mm-dd`） | | `fund_class_document_number` | 基金类别的 CNPJ | | `application_from_datetime` | 日期/时间大于或等于该值的申请，格式为 `yyyy-mm-ddTHH:MM:SSZ`（UTC） | | `application_to_datetime` | 日期/时间小于或等于该值的申请，格式为 `yyyy-mm-ddTHH:MM:SSZ`（UTC） | ## 按基金类别 返回管理人某基金类别的金融申请，按从新到旧排序。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_applications MÉTODO GET STATUS 200 ### Query Params | 参数 | 描述 | | --------------------------- | ---------------------------------------------------------------------------------------------- | | `page` | 页码，从 0 开始（默认 0） | | `limit` | 每页条目数（默认 20，最大 100） | | `status` | **[Financial Application Status](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave#financial_application_status)** 列表 | | `investor_name` | 投资者姓名的一部分（不区分大小写） | | `investor_document_number` | 投资者 CPF/CNPJ | | `quotation_date` | 计价日期（`yyyy-mm-dd`） | | `application_from_datetime` | 日期/时间大于或等于该值的申请，格式为 `yyyy-mm-ddTHH:MM:SSZ`（UTC） | | `application_to_datetime` | 日期/时间小于或等于该值的申请，格式为 `yyyy-mm-ddTHH:MM:SSZ`（UTC） | `limit` 超过最大值时返回 400。 ## Response 两种查询返回相同的结构。`data` 中的每一项都是 [按键查询金融申请](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave#financial_application) 中所述的 **Financial Application** 对象。 ```json { "data": [ { "financial_application_key": "UUID", "share_capital": 1000.0, "status": "quoted", "financial_application_type": "primary_market", "quotation_date": "2025-01-10" } ], "limit": 20, "page": 0, "is_last_page": true } ``` | 字段 | 类型 | 描述 | | -------------- | ------- | --------------------------------------------- | | `data` | array | 金融申请列表 | | `limit` | int | 每页条目数 | | `page` | int | 返回的页码 | | `is_last_page` | boolean | 没有更多页时为 `true` | ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ---------------------------------------------------------------------------------------- | | 400 | `QIT000001` | 日期或日期/时间格式无效 | | 400 | `QIT000004` | 该管理人不是该基金的管理人，或未与该投资者关联 | | 404 | `QTA000002` | 未找到基金类别（按类别查询） | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 金融申请结算分页查询 URL: /zh-Hans/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras 按基金类别或按申请，列出金融申请的每日结算（会计持仓）。 ## 按基金类别 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_application_closings MÉTODO GET STATUS 200 ### Query Params | 参数 | 描述 | | -------------------------- | ------------------------------------------------------------------------- | | `accounting_date` | 特定结算会计日期（`yyyy-mm-dd`） | | `from_date` | 周期起始日期（`yyyy-mm-dd`） | | `to_date` | 周期结束日期（`yyyy-mm-dd`） | | `investor_document_number` | 投资者 CPF/CNPJ | | `limit` | 每页条目数（默认 75，最大 75） | | `page` | 页码，从 0 开始（默认 0） | :::caution 注意 发送 `accounting_date` **或** `from_date` 与 `to_date` 这一对参数，二者不可同时发送。两者都未发送时，API 返回 `QTA000026`；同时发送时，返回 `QIT000001`。不在此列表中的参数同样会被拒绝，并返回 `QIT000001`。 ::: 结果按会计日期从新到旧排序。 ## 按投资者和金融申请 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ENDPOINT /quota/investor/INVESTOR_KEY/financial_application/FINANCIAL_APPLICATION_KEY/financial_application_closings MÉTODO GET STATUS 200 ### Query Params | 参数 | 描述 | | ------------------------------------ | ------------------------------------------------------------------------------------------ | | `last_financial_application_closing` | 布尔值。为 `true` 时，仅返回该申请的最近一次结算（默认 `false`） | | `limit` | 每页条目数（默认 50，最大 500） | | `page` | 页码，从 0 开始（默认 0） | ## Response 案例 01：查询成功 ```json { "data": [ { "financial_application": { "financial_application_key": "UUID", "share_capital": 1000.0, "status": "quoted", "financial_application_type": "primary_market", "payment_method": "regular", "quotation_date": "2025-01-10", "investor": { "investor_key": "UUID", "name": "INVESTIDOR EXEMPLO", "person_type": "natural_person" }, "issuance_serie": { "issuance_serie_key": "UUID" } }, "total_value": 1012.35, "number_of_quotas": 998.12345678, "principal_value": 1000.0, "acquisition_cost": 1000.0, "yield_value": 12.35, "ir_value": 2.78, "iof_value": 0.0, "taxable_yield_value": 12.35, "accounting_date": "2025-01-31" } ], "limit": 75, "page": 0, "is_last_page": true } ``` | 字段 | 类型 | 描述 | | -------------- | ------- | --------------------------------------------------------------------------------------- | | `data` | array | **[Financial Application Closing](#financial-application-closing)** 对象列表 | | `limit` | int | 每页条目数 | | `page` | int | 返回的页码 | | `is_last_page` | boolean | 没有更多页时为 `true` | ### Financial Application Closing | 字段 | 类型 | 描述 | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `financial_application` | object | 完整的金融申请，格式同 [按键查询金融申请](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave#financial_application) | | `total_value` | float | 结算时申请的总价值 | | `number_of_quotas` | float | 结算时的份额数量 | | `principal_value` | float | 结算时的本金价值 | | `acquisition_cost` | float | 结算时份额的取得成本 | | `yield_value` | float | 总收益 | | `ir_value` | float | 所得税（IR） | | `iof_value` | float | 金融操作税（IOF） | | `taxable_yield_value` | float | 应税收益 | | `accounting_date` | string | 结算的会计日期 | ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ------------------------------------------------------------------------------------- | | 400 | `QTA000026` | 按类别查询时既未发送 `accounting_date`，也未发送 `from_date`/`to_date` | | 400 | `QIT000001` | 参数无效或未知、`limit` 超过 75，或 `accounting_date` 与 `from_date`/`to_date` 同时发送 | | 400 | `QIT000004` | 该基金不属于该管理人 | | 404 | `QTA000020` | 未找到投资者（API 返回的是未找到分销商的错误） | | 404 | `QTA000023` | 未找到该投资者的金融申请 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 按键查询金融申请 URL: /zh-Hans/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave 按键返回投资者的某笔金融申请。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------------- | | 管理人 | `manager-api` | 读取 | | 顾问 | `consultant-api` | 由集成团队开通 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota/investor/INVESTOR_KEY/financial_application/FINANCIAL_APPLICATION_KEY MÉTODO GET STATUS 200 管理人只能查询与其关联的投资者；顾问只能查询其拥有权限的基金中的申请。 ## Responses 案例 01：查询成功 ```json { "financial_application_key": "UUID", "external_id": "SEU_ID_EXTERNO", "share_capital": 1000.0, "status": "quoted", "financial_application_type": "primary_market", "payment_method": "regular", "central_depositary": "unregistered", "quotation_date": "2025-01-10", "original_number_of_quotas": 998.12345678, "original_number_of_quotas_str": "998.12345678", "current_number_of_quotas": 998.12345678, "current_principal_value": 1000.0, "acquisition_cost": 1000.0, "status_events": [ { "event_datetime": "2025-01-09T14:30:00Z", "status": "pending_payment" }, { "event_datetime": "2025-01-10T21:00:00Z", "status": "quoted" } ], "redemptions": [], "amortizations": [], "investor": { "investor_key": "UUID", "name": "INVESTIDOR EXEMPLO", "person_type": "natural_person", "document_number": "969.698.790-03", "distributor": { "distributor_key": "UUID", "document_number": "11.222.333/0001-81", "name": "DISTRIBUIDORA EXEMPLO", "account_data": {} } }, "issuance_serie": { "issuance_serie_key": "UUID", "name": "SERIE 1", "serie": 1, "status": "active", "remuneration_type": "yield_curve", "original_quota_value": 1.0, "current_quota_value": 1.0018, "sub_class": { "name": "COTA SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "name": "FUNDO EXEMPLO", "fund_class_key": "UUID", "document_number": "11.222.333/0001-81" } } }, "water_mark_events": [] } ``` 可选字段（`external_id`、`original_number_of_quotas`、`current_number_of_quotas`、`current_principal_value`、`acquisition_cost`、`quotation_date`）仅在有值时返回。列表 `status_events`、`redemptions`、`amortizations` 和 `reserved_taxable_yields` 为空时不返回。 ### Financial Application {#financial_application} | 字段 | 类型 | 描述 | | ------------------------------- | ------ | -------------------------------------------------------------------------------- | | `financial_application_key` | string | 金融申请唯一键 | | `external_id` | string | 外部标识符 | | `share_capital` | float | 申请金额 | | `status` | string | **[Financial Application Status](#financial_application_status)** 枚举值 | | `financial_application_type` | string | `primary_market`（申请）或 `secondary_market`（二级市场） | | `payment_method` | string | `regular`（Pix 或 TED）或 `b3` | | `central_depositary` | string | `unregistered` 或 `cetip` | | `quotation_date` | string | 计价日期（`yyyy-mm-dd`） | | `original_number_of_quotas` | float | 计价时的份额数量（`_str`：以字符串表示的同一数值，不做舍入） | | `current_number_of_quotas` | float | 当前份额数量 | | `current_principal_value` | float | 当前本金 | | `acquisition_cost` | float | 取得成本 | | `status_events` | array | 状态历史：`status` 和 `event_datetime`（UTC） | | `redemptions` | array | 消耗该申请的赎回：`redemption_key`、`redemption_type`、`number_of_quotas`、`total_value`、`ir_value`、`iof_value`、`yield_value`、`taxable_yield_value`、`redemption_date` | | `amortizations` | array | 已支付的摊销：`amortization_key`、`payment_date`、`total_value`、`principal_reduction`、`acquisition_cost_reduction`，以及（如有）`yield_value`、`taxable_yield_value`、`ir_value`、`iof_value` | | `reserved_taxable_yields` | array | 预留的应税收益（come-cotas） | | `investor` | object | 投资者：`investor_key`、`name`、`person_type`、`document_number` 和 `distributor` | | `issuance_serie` | object | 发行系列，包含 `sub_class` 和 `sub_class.fund_class` | | `water_mark_quota_value` | float | 高水位线（业绩报酬）的参考份额价值（如有） | | `water_mark_reference_date` | string | 高水位线参考日期（如有） | | `water_mark_events` | array | 高水位线事件 | ### Financial Application Status {#financial_application_status} | 枚举值 | 描述 | | ----------------------------------- | ----------------------------------------------- | | `created` | 已创建 | | `pending_formalization` | 待正式化（认购公告） | | `pending_payment` | 待付款 | | `processing_quotation` | 计价处理中 | | `pending_quote` | 待计价 | | `processing_issuance_serie_impacts` | 正在处理对系列的影响 | | `quoted` | 已计价 | | `settled` | 已全部摊销 | | `redeemed` | 已全部赎回 | | `canceled` | 已取消 | | `reprocessed` | 已重新处理 | ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ------------------------------------------------------------------------------------------------- | | 400 | `QIT000004` | 管理人未与该投资者关联 | | 403 | `QTA000315` | 顾问对该申请所属基金没有权限 | | 404 | `QTA000021` | 未找到投资者 | | 404 | `QTA000260` | 未找到该投资者的金融申请 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 创建金融申请 URL: /zh-Hans/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira 为投资者在某发行系列中创建金融申请。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------------- | | 管理人 | `manager-api` | 写入 | | 顾问 | `consultant-api` | 由集成团队开通 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota/investor/INVESTOR_KEY/financial_application MÉTODO POST STATUS 201 ```json title='请求体' { "issuance_serie_key": "UUID", "share_capital": 0.00, "payment_method": "b3 / regular", "central_depositary": "unregistered / cetip", "quotation_date": "yyyy-mm-dd" } ``` :::info 必填字段 - issuance_serie_key - share_capital ::: :::caution 注意 **payment_method** 和 **central_depositary** 为可选字段。如未发送，API 将使用下表中标记为默认的值（`regular` 和 `unregistered`）。 - 当 **central_depositary** 为 `cetip` 时，**payment_method** 可为 `regular` 或 `b3`；为 `unregistered` 时，仅可为 `regular`（`b3` 将返回错误 `QTA000359`）。 ::: ### Body params | 字段 | 类型 | 描述 | |-----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------| | `issuance_serie_key` | string | 发行系列的唯一标识键 | | `share_capital` | float | 金融申请金额（大于或等于 0）。如该系列设有最低申请金额，则金额须达到该最低值 | | `payment_method` | string | 付款方式。可选值：
• regular：Pix 或 TED **（默认）**
• b3：通过 B3 | | `central_depositary` | string | 托管登记机构类型。可选值：
• unregistered：无登记机构 **（默认）**
• cetip：在 Cetip 登记 | | `quotation_date` | string | 申请的计价日期，格式为 yyyy-mm-dd（可选）。必须为工作日，且不得早于基金的会计日期。如省略，则根据该系列的期限配置计算 | ## Response 响应返回所创建的金融申请对象，格式与[按键查询](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave)相同。请保存 `financial_application_key`。 ```json title='响应体（摘要）' { "financial_application_key": "UUID", "share_capital": 1000.0, "status": "pending_payment", "financial_application_type": "primary_market", "payment_method": "regular", "central_depositary": "unregistered", "quotation_date": "2025-01-10" } ``` ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | --------------------------------------------------------------------------------------------------- | | 400 | `QIT000001` | 请求体无效：缺少必填字段、类型错误或包含未定义的字段 | | 400 | `QIT000004` | 该系列不属于该管理人的基金 | | 400 | `QTA000359` | `payment_method` 为 `b3`，而 `central_depositary` 为 `unregistered` | | 400 | `QTA000272` | `share_capital` 低于该系列的最低申请金额 | | 400 | `QTA000176` | `quotation_date` 不是工作日 | | 400 | `QTA000225` | `quotation_date` 早于基金的会计日期 | | 400 | `QTA000264` | 金额超过发行或认购公告中的可用额度（封闭式基金） | | 400 | `QTA000267` | 投资者的认购公告尚未达到可认购状态（封闭式基金） | | 400 | `QTA000269` | 该申请将导致子类别不符合要求（次级比例） | | 403 | `QTA000315` | 顾问对该系列所属基金没有权限 | | 404 | `QTA000004` | `payment_method` 或 `central_depositary` 的值无效 | | 404 | `QTA000015` | 未找到 `issuance_serie_key` | | 404 | `QTA000021` | 未找到投资者（在 `manager-api` 上，目前返回的是 `QTA000020`） | | 404 | `QTA000265` | 投资者没有认购公告（封闭式基金） | | 404 | `QTA000266` | 该系列没有份额发行（封闭式基金） | | 422 | `QTA000425` | 该发行系列已结清 | | 422 | `QTA000357` | 操作被禁止：该系列的份额价值为零或负数 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 手动批准份额锁定 URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/aprovar_bloqueio_pendente_aprovacao --- ## 简介 本资源旨在详细说明份额锁定的手动审批流程。 :::caution 注意 只有当锁定金额超过净资产总值的 **3.8%** 以内时，份额锁定才会进入待手动审批状态。 ::: :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 写入 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## 审批 ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/pending_manual_approval/approve MÉTODO PUT STATUS 204 ## 拒绝 ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/pending_manual_approval/reprove MÉTODO PUT STATUS 204 ## 错误 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 查询份额锁定 URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas --- ## 简介 本资源旨在详细说明**投资者**的某个**份额锁定**请求的信息。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------------- | | 管理人 | `manager-api` | 写入 | | 顾问 | `consultant-api` | 由集成团队开通 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY MÉTODO GET STATUS 200 ## Response ```json { "quota_lock_key": "UUID", "status": "pending_documents", "original_locked_quotas": 0.0, "current_locked_quotas": 0.0, "original_locked_value": 0.0, "current_locked_value": 0.0, "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Recipient Mother Name" } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Borrower Mother Name" } }, "assets": [ { "asset_key": "UUID", "asset_type": "cce", "credit_operation": { "contract_number": "1000000001", "principal_value": 0.0, "interest_rate_type": "post_fixed", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360" }, "post_fixed": { "calendar_base": "workdays", "indexer": "di", "rate": 1, "lag": { "reference": "daily", "amount": 1 } } }, "documents": [ { "document_key": "UUID", "document_type": "asset_document" } ] } ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.0, "financial_value": 0.0 }, { "issuance_serie_key": "UUID", "number_of_quotas": 0.0, "financial_value": 0.0 } ], "documents": [ { "document_key": "UUID", "document_type": "collateral_contract" } ] }, "investor_positions_locks": [ { "investor_position_lock_key": "UUID", "investor_position_key": "UUID", "original_locked_quotas": 0.0, "current_locked_quotas": 0.0, "original_locked_value": 0.0, "current_locked_value": 0.0 } ] } ``` ## Quota Lock | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |------------------------------------------------------------------------|------------| | `quota_lock_key` | string | 份额锁定唯一标识符 | 36 | | `status` | string | 份额锁定状态枚举值 | 最多255 | | `type` | string | 份额锁定类型枚举值 | 最多255 | | `original_locked_quotas` | float | 原始锁定份额数量 | - | | `current_locked_quotas` | float | 当前锁定份额数量 | - | | `original_locked_value` | float | 原始锁定价值 | - | | `current_locked_value` | float | 当前锁定价值 | - | | `collateral` | JSON | **[担保](#collateral)** 对象 | - | | `investor_positions_locks` | Array | **[投资者持仓锁定](#locked-investor-positions)** 对象列表 | - | ## Quota Lock Status | 枚举值 | 描述 | |--------------------------|-----------------------| | `pending_documents` | 待文件 | | `pending_approval` | 待审批 | | `denied` | 已拒绝 | | `approved` | 已批准 | ## Quota Lock Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `collateral` | 担保 | ## Collateral | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |-----------------------------------------------------------------------|------------| | `recipient` | JSON | **[受益人](#recipient)** 对象 | - | | `borrower` | JSON | **[借款人](#borrower)** 对象 | - | | `assets` | Array | **[资产](#asset)** 对象列表 | - | | `issuance_series` | Array | **[发行系列](#issuance_serie)** 对象列表 | - | | `documents` | Array | **[担保文件](#document)** 对象列表 | - | ## Issuance Serie {#issuance_serie} | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|-------------------------------------------------------|--------------| | `issuance_serie_key` | string | 发行系列键 | 36 | | `number_of_quotas` | float | 已锁定的份额数量 | - | | `financial_value` | float | 已锁定的金融价值 | - | ## Recipient | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |-----------------------------------------------------|------------| | `name` | string | 受益人姓名 | 最多255 | | `document_number` | string | 受益人 CPF / CNPJ | 14或18 | | `person_type` | string | 自然人或法人枚举值 | 最多255 | | `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - | | `legal_person` | JSON | **[法人](#legal_person)** 对象 | - | ## Borrower | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |-----------------------------------------------------|------------| | `name` | string | 借款人姓名 | 最多255 | | `document_number` | string | 借款人 CPF / CNPJ | 14或18 | | `person_type` | string | 自然人或法人枚举值 | 最多255 | | `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - | | `legal_person` | JSON | **[法人](#legal_person)** 对象 | - | ## Person Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `natural_person` | 自然人 | | `legal_person` | 法人 | ## Natural Person {#natural_person} | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |-----------------------------------------------------|------------| | `birthdate` | string | 出生日期 | 10 | | `mother_name` | string | 母亲姓名 | 最多255 | ## Legal Person {#legal_person} | 字段 | 类型 | 描述 | 字符数 | |------------------|----------|----------------------------------------------------------|--------------| | `activity_code` | string | 国家经济活动分类代码 (CNAE) | 10 | | `representatives`| array | **[代表人](#representative)** 对象列表 | - | ## Representative | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|------------------------------------------------|--------------| | `name` | string | 代表人姓名 | 最多255 | | `document_number` | string | 代表人 CPF | 14 | ## Asset | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|---------------------------------------------------------------|--------------| | `asset_key` | string | 资产唯一标识符 | 最多255 | | `asset_type` | string | 资产类型枚举值 | 最多255 | | `status` | string | 资产状态枚举值 | 最多255 | | `credit_operation` | JSON | **[信贷操作](#credit_operation)** 对象 | - | | `documents` | Array | **[资产文件](#document)** 对象列表 | - | ## Asset Status | 枚举值 | 描述 | |--------------------------|-----------------------| | `pending_approval` | 待审批 | | `done` | 已完成 | ## Document | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|---------------------------------------------------------------|--------------| | `document_key` | string | 资产唯一标识符 | 最多255 | | `document_type` | string | 资产类型枚举值 | 最多255 | ## Asset Type | 枚举值 | 描述 | |--------------------------|-----------| | `ccb` | CCB | | `cce` | CCE | ## Credit Operation {#credit_operation} | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|-------------------------------------------------------|--------------| | `contract_number` | string | 合同号 | 最多255 | | `principal_value` | string | 操作本金价值 | - | | `interest_rate_type` | string | 浮动/固定利率枚举值 | 最多255 | | `pre_fixed` | JSON | **[固定利率](#pre_fixed)** 对象 | - | | `post_fixed` | JSON | **[浮动利率](#pos_fixed)** 对象 | - | ## Interest Rate Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `pre_fixed` | 固定利率 | | `post_fixed` | 浮动利率 | ## Pre fixed {#pre_fixed} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|--------------------------------------------------------------|------------| | `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 | | `monthly_rate` | float | 月利率 | - | ## Post fixed {#pos_fixed} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|-----------------------------------------------------------------|------------| | `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 | | `indexer` | string | DI / IPCA 枚举值 | 最多255 | | `rate` | float | 利率 | - | | `lag` | JSON | **[Lag](#lag)** 对象 | - | ## calendar_base | 枚举值 | 描述 | |--------------------------|-----------------------| | `workdays` | 工作日 | | `calendar_360` | 360日历 | | `calendar_365` | 365日历 | ## Indexer | 枚举值 | 描述 | |--------------------------|-----------------------| | `di` | DI | | `ipca` | IPCA | ## Lag | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|---------------------------------------------------|------------| | `reference` | string | 每日 / 每月枚举值 | 最多255 | | `amount` | integer | 滞后数量 | - | ## Reference | 枚举值 | 描述 | |--------------------------|-----------------------| | `daily` | 每日 | | `monthly` | 每月 | ## Locked Investor Positions | 字段 | 类型 | 描述 | 字符数 | |---------------------------------|------- |-----------------------------------------------------------------------|------------| | `investor_position_lock_key` | string | 投资者持仓锁定唯一标识符 | 36 | | `investor_position_key` | string | 投资者持仓唯一标识符 | 36 | | `original_locked_quotas` | float | 原始锁定份额数量 | - | | `current_locked_quotas` | float | 当前锁定份额数量 | - | | `original_locked_value` | float | 原始锁定价值 | - | | `current_locked_value` | float | 当前锁定价值 | - | ## 错误 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 查询投资者的份额锁定 URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas_de_um_investidor --- ## 简介 本资源旨在详细说明**投资者**的所有**份额锁定**请求的信息。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------------- | | 管理人 | `manager-api` | 写入 | | 顾问 | `consultant-api` | 由集成团队开通 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_locks MÉTODO GET STATUS 200 ## Response ```json { "data": [ { "quota_lock_key": "UUID", "status": "pending_documents", "original_locked_quotas": 0.0, "current_locked_quotas": 0.0, "original_locked_value": 0.0, "current_locked_value": 0.0, "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Recipient Mother Name" } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Borrower Mother Name" } }, "assets": [ { "asset_key": "UUID", "asset_type": "cce", "credit_operation": { "contract_number": "1000000001", "principal_value": 0.0, "interest_rate_type": "post_fixed", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360" }, "post_fixed": { "calendar_base": "workdays", "indexer": "di", "rate": 1, "lag": { "reference": "daily", "amount": 1 } } }, "documents": [ { "document_key": "UUID", "document_type": "asset_document" } ] } ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.0, "financial_value": 0.0 }, { "issuance_serie_key": "UUID", "number_of_quotas": 0.0, "financial_value": 0.0 } ], "documents": [ { "document_key": "UUID", "document_type": "collateral_contract" } ] }, "investor_positions_locks": [ { "investor_position_lock_key": "UUID", "investor_position_key": "UUID", "original_locked_quotas": 0.0, "current_locked_quotas": 0.0, "original_locked_value": 0.0, "current_locked_value": 0.0 } ] }, { "quota_lock_key":"04eeaabc-cb40-484a-b730-85ed5aed7bbf", "status":"approved", "type":"lawsuit", "original_locked_value":"50000.00", "current_locked_value":"50000.00", "lawsuit":{ "protocol":"20250037746822", "lock_date":"2024-01-15", "unlock_date":"2024-01-16", "process_number":"13289520258250000", "document_number":"236.682.501-38", "requested_amount":50000.0 } } ], "page": 0, "is_last_page": true } ``` ## Quota Lock | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |------------------------------------------------------------------------|------------| | `quota_lock_key` | string | 份额锁定唯一标识符 | 36 | | `status` | string | 份额锁定状态枚举值 | 最多255 | | `type` | string | 份额锁定类型枚举值 | 最多255 | | `original_locked_quotas` | float | 原始锁定份额数量 | - | | `current_locked_quotas` | float | 当前锁定份额数量 | - | | `original_locked_value` | float | 原始锁定价值 | - | | `current_locked_value` | float | 当前锁定价值 | - | | `collateral` | JSON | **[担保](#collateral)** 对象 | - | | `investor_positions_locks` | Array | **[投资者持仓锁定](#locked-investor-positions)** 对象列表 | - | ## Quota Lock Status | 枚举值 | 描述 | |--------------------------|-----------------------| | `pending_documents` | 待文件 | | `pending_approval` | 待审批 | | `denied` | 已拒绝 | | `approved` | 已批准 | ## Quota Lock Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `collateral` | 担保 | ## Collateral | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |-----------------------------------------------------------------------|------------| | `recipient` | JSON | **[受益人](#recipient)** 对象 | - | | `borrower` | JSON | **[借款人](#borrower)** 对象 | - | | `assets` | Array | **[资产](#asset)** 对象列表 | - | | `issuance_series` | Array | **[发行系列](#issuance_serie)** 对象列表 | - | | `documents` | Array | **[担保文件](#document)** 对象列表 | - | ## Issuance Serie {#issuance_serie} | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|-------------------------------------------------------|--------------| | `issuance_serie_key` | string | 发行系列键 | 36 | | `number_of_quotas` | float | 已锁定的份额数量 | - | | `financial_value` | float | 已锁定的金融价值 | - | ## Recipient | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |-----------------------------------------------------|------------| | `name` | string | 受益人姓名 | 最多255 | | `document_number` | string | 受益人 CPF / CNPJ | 14或18 | | `person_type` | string | 自然人或法人枚举值 | 最多255 | | `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - | | `legal_person` | JSON | **[法人](#legal_person)** 对象 | - | ## Borrower | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |-----------------------------------------------------|------------| | `name` | string | 借款人姓名 | 最多255 | | `document_number` | string | 借款人 CPF / CNPJ | 14或18 | | `person_type` | string | 自然人或法人枚举值 | 最多255 | | `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - | | `legal_person` | JSON | **[法人](#legal_person)** 对象 | - | ## Person Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `natural_person` | 自然人 | | `legal_person` | 法人 | ## Natural Person {#natural_person} | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |-----------------------------------------------------|------------| | `birthdate` | string | 出生日期 | 10 | | `mother_name` | string | 母亲姓名 | 最多255 | ## Legal Person {#legal_person} | 字段 | 类型 | 描述 | 字符数 | |------------------|----------|----------------------------------------------------------|--------------| | `activity_code` | string | 国家经济活动分类代码 (CNAE) | 10 | | `representatives`| array | **[代表人](#representative)** 对象列表 | - | ## Representative | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|------------------------------------------------|--------------| | `name` | string | 代表人姓名 | 最多255 | | `document_number` | string | 代表人 CPF | 14 | ## Asset | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|---------------------------------------------------------------|--------------| | `asset_key` | string | 资产唯一标识符 | 最多255 | | `asset_type` | string | 资产类型枚举值 | 最多255 | | `status` | string | 资产状态枚举值 | 最多255 | | `credit_operation` | JSON | **[信贷操作](#credit_operation)** 对象 | - | | `documents` | Array | **[资产文件](#document)** 对象列表 | - | ## Asset Status | 枚举值 | 描述 | |--------------------------|-----------------------| | `pending_approval` | 待审批 | | `done` | 已完成 | ## Document | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|---------------------------------------------------------------|--------------| | `document_key` | string | 资产唯一标识符 | 最多255 | | `document_type` | string | 资产类型枚举值 | 最多255 | ## Asset Type | 枚举值 | 描述 | |--------------------------|-----------| | `ccb` | CCB | | `cce` | CCE | ## Credit Operation {#credit_operation} | 字段 | 类型 | 描述 | 字符数 | |-----------------------------------|----------|-------------------------------------------------------|--------------| | `contract_number` | string | 合同号 | 最多255 | | `principal_value` | string | 操作本金价值 | - | | `interest_rate_type` | string | 浮动/固定利率枚举值 | 最多255 | | `pre_fixed` | JSON | **[固定利率](#pre_fixed)** 对象 | - | | `post_fixed` | JSON | **[浮动利率](#pos_fixed)** 对象 | - | ## Interest Rate Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `pre_fixed` | 固定利率 | | `post_fixed` | 浮动利率 | ## Pre fixed {#pre_fixed} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|--------------------------------------------------------------|------------| | `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 | | `monthly_rate` | float | 月利率 | - | ## Post fixed {#pos_fixed} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|-----------------------------------------------------------------|------------| | `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 | | `indexer` | string | DI / IPCA 枚举值 | 最多255 | | `rate` | float | 利率 | - | | `lag` | JSON | **[Lag](#lag)** 对象 | - | ## calendar_base | 枚举值 | 描述 | |--------------------------|-----------------------| | `workdays` | 工作日 | | `calendar_360` | 360日历 | | `calendar_365` | 365日历 | ## Indexer | 枚举值 | 描述 | |--------------------------|-----------------------| | `di` | DI | | `ipca` | IPCA | ## Lag | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|---------------------------------------------------|------------| | `reference` | string | 每日 / 每月枚举值 | 最多255 | | `amount` | integer | 滞后数量 | - | ## Reference | 枚举值 | 描述 | |--------------------------|-----------------------| | `daily` | 每日 | | `monthly` | 每月 | ## Locked Investor Positions | 字段 | 类型 | 描述 | 字符数 | |---------------------------------|------- |-----------------------------------------------------------------------|------------| | `investor_position_lock_key` | string | 投资者持仓锁定唯一标识符 | 36 | | `investor_position_key` | string | 投资者持仓唯一标识符 | 36 | | `original_locked_quotas` | float | 原始锁定份额数量 | - | | `current_locked_quotas` | float | 当前锁定份额数量 | - | | `original_locked_value` | float | 原始锁定价值 | - | | `current_locked_value` | float | 当前锁定价值 | - | ## 错误 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 发送担保文件 URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_da_garantia --- ## 简介 本资源旨在向我们发送与正在申请**份额锁定**的**担保**正式化相关的**文件**。 ## Input / Output: 作为***输入***，需发送**文件类型**和文件的 **base 64** 编码。请参见以下示例。 作为***输出***，将返回 ***collateral_document_key***。***collateral_document_key*** 用于标识已发送的**担保文件**。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------------- | | 管理人 | `manager-api` | 写入 | | 顾问 | `consultant-api` | 由集成团队开通 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/collateral/COLLATERAL_KEY/document MÉTODO POST STATUS 201 ## Request body ```json title='请求体' { "document_type": "collateral_contract", "document_b64" : "B64" } ``` ## Collateral Document | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------|--------|------------------------------|----------|------| | `document_type` | string | 担保文件类型枚举值 | 最多255 | 是 | | `document_b64` | string | 以 base64 编码的文件内容 | - | 是 | ## Document Type | 枚举值 | 描述 | |------------------------|----------| | `collateral_contract` | 担保合同 | | `rental_contract` | 租赁合同 | ## Response ```json title='响应体' { "collateral_document_key": "UUID" } ``` ## 错误 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 发送资产文件 URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_do_ativo --- ## 简介 本资源旨在向我们发送作为正在申请**份额锁定**的**担保**标的的**资产**的**文件**。 ## Input / Output: 作为***输入***，需发送**文件类型**和文件的 **base 64** 编码。请参见以下示例。 作为***输出***，将返回 ***asset_document_key***。***asset_document_key*** 用于标识已发送的**资产文件**。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------------- | | 管理人 | `manager-api` | 写入 | | 顾问 | `consultant-api` | 由集成团队开通 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/collateral/COLLATERAL_KEY/asset/ASSET_KEY/document MÉTODO POST STATUS 201 ## Request body ```json title='请求体' { "document_type": "asset_document", "document_b64" : "B64" } ``` ## Response ```json title='响应体' { "asset_document_key": "UUID" } ``` ## 错误 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 担保执行 URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/execucao_de_garantia --- ## 简介 本资源旨在**执行**以**投资者**份额设立的**担保**，将份额锁定转换为向**债权人**的付款。 与其他锁定事件不同，担保执行会在基金类别中生成一笔**赎回申请**，所得金额以担保中登记的**债权人名义**支付，而非支付给投资者。投资者的持仓将按实际赎回的份额数量相应减少。 ## 前提条件 在申请执行之前，请确认： | 条件 | 说明 | |------|------| | 锁定已批准 | 份额锁定必须处于 `approved` 状态。 | | 担保类型的锁定 | 仅包含 `collateral` 对象的锁定可以执行。司法查封类锁定不可执行。 | | 债权人已确定 | `collateral.recipient` 必须包含 `name` 和 `document_number`。 | | 债权人银行账户 | `collateral.recipient.bank_account` 必须包含 `account_number`、`account_branch`、`account_digit` 和 `financial_institution_ispb`。 | 债权人及其银行账户在创建锁定时登记，参见[申请份额锁定](/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas)。若担保登记信息不完整，所申请的执行**不会被记录**。 :::caution 注意 `collateral.recipient.bank_account` 中提供的银行账户为**债权人账户**，是执行付款的目标账户。请勿与 `collateral.bank_account_key` 混淆，后者标识**投资者**的账户，不参与担保执行。 ::: :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 写入 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/investor_position_lock/INVESTOR_POSITION_LOCK_KEY/event MÉTODO POST STATUS 201 担保执行 ```json { "type": "collateral_execution", "net_value": 1000.00 } ``` ## Collateral Execution Event | 字段 | 类型 | 说明 | 字符数 | 必填 | |--------------|--------|----------------------------------------------------------|----------|------| | `type` | string | 事件类型枚举值。担保执行为：`collateral_execution` | 最多 255 | 是 | | `net_value` | float | 需执行并支付给债权人的净额 | - | 是 | `net_value` 中提供的金额不得超过申请时的已锁定金额。 ## Response 执行已记录 ```json { "investor_position_lock_event_key": "UUID" } ``` | 字段 | 类型 | 说明 | 字符数 | |------------------------------------|--------|--------------------|--------| | `investor_position_lock_event_key` | string | 所创建执行事件的标识 | 36 | ## 申请之后 1. 执行事件以 `pending_processing` 状态记录。此时被锁定的金额**仍然全额锁定**。 2. 系统按所提供的金额，在基金类别中自动开立一笔 `net_value_redemption` 类型的赎回申请。 3. 赎回申请在基金类别的常规周期中完成计价。付款将支付至债权人账户，金额为**扣除所得税（IR）和金融操作税（IOF）后的净额**。 4. 计价完成后，实际赎回的份额数量从锁定中扣减，事件转为 `done`。 若赎回申请在计价前被取消，执行事件转为 `canceled`，被锁定的金额**全额保留**，不做部分扣减。 ## Event Status | 枚举值 | 说明 | |-----------------------|---------------------------------------------| | `pending_processing` | 执行已记录，等待赎回申请完成计价 | | `done` | 执行已完成，份额已从锁定中扣减 | | `canceled` | 执行已取消，被锁定的金额予以保留 | ## 状态跟踪 执行状态通过[份额锁定查询](/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas)接口查询，位于 `investor_position_locks[].events[]` 对象中。 锁定查询中的事件 ```json { "investor_position_locks": [ { "investor_position_lock_key": "UUID", "current_locked_quotas": 100.00000000000000, "events": [ { "quota_lock_event_key": "UUID", "type": "collateral_execution", "status": "pending_processing" } ] } ] } ``` :::info 在查询响应中，事件标识通过 `quota_lock_event_key` 字段返回，与创建时返回的 `investor_position_lock_event_key` 相对应。 ::: 执行完成后，同一事件将显示 `status: "done"`，并通过 `new_locked_quotas` 字段给出锁定中剩余的份额数量。 担保执行事件没有专用的 webhook。份额锁定可用的 webhook 参见[份额锁定 Webhooks](/documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota)。 ## 错误 | 状态 | 代码 | 发生情形 | |--------|-------------|------------------------------------------| | 400 | `QLK000044` | 提供的 `net_value` 为空、为零或为负数 | | 400 | `QLK000042` | 提供的 `net_value` 超过已锁定金额 | | 400 | `QLK000036` | 所选代理并非该锁定的申请方 | | 404 | `QLK000022` | 未找到份额锁定 | | 404 | `QLK000037` | 未找到被锁定的持仓 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 减少份额锁定 URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/reduzir_bloqueio_de_cotas --- ## 简介 本资源旨在减少**投资者**的**份额锁定**金额。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 写入 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/investor_position_lock/INVESTOR_POSITION_LOCK_KEY/event MÉTODO POST STATUS 201 减少锁定价值 ```json { "type": "decrease_locked_value", "new_locked_value": 0.00 } ``` 减少锁定份额数量 ```json { "type": "decrease_locked_quotas", "new_locked_quotas": 0.00 } ``` 担保执行 ```json { "type": "collateral_execution", "net_value": 0.00 } ``` ## Locked Investor Position Event | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------|------- |--------------------------------------|------------|-------------| | `type` | string | 事件类型枚举值 | 最多255 | 是 | | `new_locked_value` | float | 新的锁定金融价值 | - | 否 | | `new_locked_quotas` | float | 新的锁定份额数量 | - | 否 | | `net_value` | float | 担保执行中确定的净额 | - | 否 | `new_locked_value`、`new_locked_quotas` 和 `net_value` 三者中必须且只能发送其中一个。 ## Event Type | 枚举值 | 描述 | |--------------------------|--------------------------------------------------| | `decrease_locked_quotas` | 减少锁定份额数量 | | `decrease_locked_value` | 减少锁定金融价值 | | `collateral_execution` | 担保执行 | `collateral_execution` 事件有其独立的流程、前提条件和状态跟踪，详见[担保执行](/documentation/iaas/passivo/bloqueio_de_cotas/execucao_de_garantia)。 ## 错误 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 申请份额锁定 URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas --- ## 简介 本资源旨在为**投资者**创建**份额锁定**申请。 ## Input / Output: 需发送**锁定类型**以及该锁定类型的特定信息。 作为***输出***，将返回代表该**份额锁定**的 ***quota_lock_key***。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------------- | | 管理人 | `manager-api` | 写入 | | 顾问 | `consultant-api` | 由集成团队开通 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock MÉTODO POST STATUS 201 担保份额锁定 - CCE - 自然人 ```json { "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Recipient Mother Name" } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Borrower Mother Name" } }, "assets": [ { "asset_type": "cce", "credit_operation": { "contract_number": "1000000001", "principal_value": 0.0, "interest_rate_type": "post_fixed", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360" }, "post_fixed": { "calendar_base": "workdays", "indexer": "di", "rate": 1, "lag": { "reference": "daily", "amount": 1 } } } } ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00 }, { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00 } ], "bank_account_key": "UUID" } } ``` 担保份额锁定 - CCE - 法人 ```json { "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "00.000.000/0000-00", "person_type": "legal_person", "legal_person": { "activity_code": "00.00-0-00", "representatives": [ { "name": "Sample Recipient Representative Name", "document_number": "000.000.000-00" } ] } }, "borrower": { "name": "Sample Borrower Name", "document_number": "00.000.000/0000-00", "person_type": "legal_person", "legal_person": { "activity_code": "00.00-0-00", "representatives": [ { "name": "Sample Borrower Representative Name", "document_number": "000.000.000-00" } ] } }, "assets": [ { "asset_type": "cce", "credit_operation": { "contract_number": "1000000001", "principal_value": 0.0, "interest_rate_type": "post_fixed", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360" }, "post_fixed": { "calendar_base": "workdays", "indexer": "di", "rate": 1, "lag": { "reference": "daily", "amount": 1 } } } } ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00 }, { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00 } ], "bank_account_key": "UUID" } } ``` 担保份额锁定 - 租赁合同 - 自然人 ```json { "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Recipient Mother Name" } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Borrower Mother Name" } }, "assets": [ { "asset_type": "rental_contract", "rental_contract": { "monthly_value": 0.0, "property_address": { "street": "Sample Street", "number": "123", "neighborhood": "Sample Neighborhood", "city": "Sample City", "uf": "SP", "complement": "Sample Complement", "postal_code": "00000-000", "country": "BRA" }, "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "readjustment_index": 0.0 } } ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00 } ], "bank_account_key": "UUID" } } ``` 担保份额锁定 - 租赁合同 - 法人 ```json { "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "00.000.000/0000-00", "person_type": "legal_person", "legal_person": { "activity_code": "00.00-0-00", "representatives": [ { "name": "Sample Recipient Representative Name", "document_number": "000.000.000-00" } ] } }, "borrower": { "name": "Sample Borrower Name", "document_number": "00.000.000/0000-00", "person_type": "legal_person", "legal_person": { "activity_code": "00.00-0-00", "representatives": [ { "name": "Sample Borrower Representative Name", "document_number": "000.000.000-00" } ] } }, "assets": [ { "asset_type": "rental_contract", "rental_contract": { "monthly_value": 0.0, "property_address": { "street": "Sample Street", "number": "123", "neighborhood": "Sample Neighborhood", "city": "Sample City", "uf": "SP", "complement": "Sample Complement", "postal_code": "00000-000", "country": "BRA" }, "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "readjustment_index": 0.0 } } ], "issuance_series": [ { "issuance_serie_key": "UUID", "financial_application_keys": [ "UUID", "UUID" ] } ], "bank_account_key": "UUID" } } ``` ## Quota Lock | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|------- |------------------------------------------------------------------|------------| | `type` | string | 份额锁定类型枚举值 | 最多255 | | `collateral` | JSON | **[担保](#collateral)** 对象 | - | ## Quota Lock Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `collateral` | 担保 | ## Collateral | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------|------- |------------------------------------------------------------------|------------|-------------| | `recipient` | JSON | **[受益人](#recipient)** 对象 | - | 是 | | `borrower` | JSON | **[借款人](#borrower)** 对象 | - | 是 | | `assets` | Array | **[资产](#asset)** 对象列表 | - | 是 | | `issuance_series` | Array | **[发行系列](#issuance_serie)** 对象列表 | - | 是 | | `bank_account_key` | string | 与担保关联的银行账户 UUID | - | 否 | ## Recipient | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------|------- |-----------------------------------------------------|------------|-------------| | `name` | string | 受益人姓名 | 最多255 | 是 | | `document_number` | string | 受益人 CPF / CNPJ | 14或18 | 是 | | `person_type` | string | 自然人或法人枚举值 | 最多255 | 是 | | `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - | 否 | | `legal_person` | JSON | **[法人](#legal_person)** 对象 | - | 否 | ## Borrower | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------|------- |-----------------------------------------------------|------------|------------ | | `name` | string | 借款人姓名 | 最多255 | 是 | | `document_number` | string | 借款人 CPF / CNPJ | 14或18 | 是 | | `person_type` | string | 自然人或法人枚举值 | 最多255 | 是 | | `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - | 否 | | `legal_person` | JSON | **[法人](#legal_person)** 对象 | - | 否 | ## Person Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `natural_person` | 自然人 | | `legal_person` | 法人 | ## Natural Person {#natural_person} | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------|------- |-----------------------------------------------------|------------|-------------| | `birthdate` | string | 出生日期 | 10 | 是 | | `mother_name` | string | 母亲姓名 | 最多255 | 是 | ## Legal Person {#legal_person} | 字段 | 类型 | 描述 | 字符数 | 必填 | |------------------|----------|----------------------------------------------------------|--------------|-------------| | `activity_code` | string | 国家经济活动分类代码 (CNAE) | 10 | 是 | | `representatives`| array | **[代表人](#representative)** 对象列表 | - | 是 | ## Representative | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------------|----------|------------------------------------------------|--------------|-------------| | `name` | string | 代表人姓名 | 最多255 | 是 | | `document_number` | string | 代表人 CPF | 14 | 是 | ## Asset | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------------|----------|--------------------------------------------------------|--------------|-------------| | `asset_type` | string | 资产类型枚举值 | 最多255 | 是 | | `credit_operation` | JSON | **[信贷操作](#credit_operation)** 对象 | - | 否 | | `rental_contract` | JSON | **[租赁合同](#rental_contract)** 对象 | - | 否 | ## Asset Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `ccb` | CCB | | `cce` | CCE | | `rental_contract` | 租赁合同 | ## Credit Operation {#credit_operation} | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------------|----------|-------------------------------------------------------|--------------|-------------| | `contract_number` | string | 合同号 | 最多255 | 是 | | `principal_value` | string | 操作本金价值 | - | 是 | | `interest_rate_type` | string | 浮动/固定利率枚举值 | 最多255 | 是 | | `pre_fixed` | JSON | **[固定利率](#pre_fixed)** 对象 | - | 否 | | `post_fixed` | JSON | **[浮动利率](#pos_fixed)** 对象 | - | 否 | ## Interest Rate Type | 枚举值 | 描述 | |--------------------------|-----------------------| | `pre_fixed` | 固定利率 | | `post_fixed` | 浮动利率 | ## Pre fixed {#pre_fixed} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|--------------------------------------------------------------|------------| | `calendar_base` | string | 工作日 / 360 天日历 / 365 天日历枚举值 | 最多255 | | `monthly_rate` | float | 月利率 | - | ## Post fixed {#pos_fixed} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|-----------------------------------------------------------------|------------| | `calendar_base` | string | 工作日 / 360 天日历 / 365 天日历枚举值 | 最多255 | | `indexer` | string | DI / IPCA 枚举值 | 最多255 | | `rate` | float | 利率 | - | | `lag` | JSON | **[Lag](#lag)** 对象 | - | ## calendar_base | 枚举值 | 描述 | |--------------------------|-----------------------| | `workdays` | 工作日 | | `calendar_360` | 360 天日历 | | `calendar_365` | 365 天日历 | ## Indexer | 枚举值 | 描述 | |--------------------------|-----------------------| | `di` | DI | | `ipca` | IPCA | ## Lag | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|---------------------------------------------------|------------| | `reference` | string | 每日 / 每月枚举值 | 最多255 | | `amount` | integer | Lag 数量 | - | ## Reference | 枚举值 | 描述 | |--------------------------|-----------------------| | `daily` | 每日 | | `monthly` | 每月 | ## Rental Contract {#rental_contract} | 字段 | 类型 | 描述 | 字符数 | 必填 | |----------------------|----------|-------------------------------------------------------|--------------|-------------| | `monthly_value` | float | 月租金额 | - | 是 | | `property_address` | JSON | 房产的 **[地址](#address)** 对象 | - | 是 | | `start_date` | string | 合同开始日期（YYYY-MM-DD） | 10 | 是 | | `end_date` | string | 合同结束日期（YYYY-MM-DD） | 10 | 是 | | `readjustment_index` | float | 合同调整指数 | - | 否 | ## Address | 字段 | 类型 | 描述 | 字符数 | 必填 | |----------------|----------|--------------------------------------------------|--------------|-------------| | `street` | string | 街道 | 最多255 | 否 | | `number` | string | 门牌号 | - | 否 | | `neighborhood` | string | 街区 | 最多255 | 否 | | `city` | string | 城市 | 最多255 | 否 | | `uf` | string | 联邦州（2 位字母缩写） | 2 | 否 | | `complement` | string | 地址补充信息 | 最多255 | 否 | | `postal_code` | string | 邮政编码（CEP），格式为 `00000-000` | 9 | 否 | | `country` | string | 国家代码（3 位字母） | 3 | 否 | ## Issuance Serie {#issuance_serie} | 字段 | 类型 | 描述 | 字符数 | 必填 | |-----------------------------------|----------|-------------------------------------------------------|--------------|-------------| | `issuance_serie_key` | string | 发行系列键 | 36 | 是 | | `number_of_quotas` | float | 待锁定的份额数量 | - | 否 | | `financial_value` | float | 待锁定的金融价值 | - | 否 | ## Responses ```json title='响应体' { "quota_lock_key": "UUID" } ``` ## 错误 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 份额锁定 Webhook URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota --- ## 简介 以下是**份额锁定**过程中发送的 webhooks 详细信息。 锁定已批准 ```json { "webhook_type": "quota_lock.quota_lock_status_change", "webhook_datetime": "2024-12-05T00:00:00Z", "data": { "status": "approved", "quota_lock_key": "UUID" } } ``` 锁定已拒绝 ```json { "webhook_type": "quota_lock.quota_lock_status_change", "webhook_datetime": "2024-12-05T00:00:00Z", "data": { "status": "denied", "quota_lock_key": "UUID" } } ``` --- # Consulta paginada de investidores por classe de fundo URL: /zh-Hans/documentation/iaas/passivo/consultas/consulta_investidores_classe_fundo Retorna **investidores que possuem aplicação financeira** vinculada à classe de fundo informada (via séries de emissão e subclasses), de forma paginada. Permite filtrar por documento, nome e data de fechamento. :::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 /quota/fund_class/{fund_class_key}/investors MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. | | `document_number` | string | opcional | Filtra pelo documento do investidor com pontuação. | | `name` | string | opcional | Parte do nome do investidor (sem diferenciar maiúsculas). | | `reference_date` | string (data) | opcional | Retorna só investidores com fechamento de aplicação financeira nessa data contábil (`YYYY-MM-DD`). | ```text title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/investors?page=0&limit=25&reference_date=2024-04-01 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "11.222.333/0001-81", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "11.222.333/0001-81" }, "account_digit": "1", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "341", "financial_institution_ispb": "60746948" } }, "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Maria Cotista Silva", "person_type": "natural_person", "document_number": "969.698.790-03", "external_id": "ext-inv-001", "external_distribution_key": null }, { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "11.222.333/0001-81", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "11.222.333/0001-81" }, "account_digit": "1", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "341", "financial_institution_ispb": "60746948" } }, "investor_key": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Investimentos PJ Ltda", "person_type": "legal_person", "document_number": "22.333.444/0001-81", "external_id": null, "external_distribution_key": "dist-key-7721" } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de investidores. | | `page` | integer | Página atual. | | `limit` | integer | Tamanho da página. | | `is_last_page` | boolean | Indica fim da paginação. | #### Campos de cada investidor em `data` | Campo | Tipo | Descrição | |---|---|---| | `investor_key` | string | Identificador único do investidor (UUID). | | `name` | string | Nome. | | `person_type` | string | Tipo de pessoa (enumerador, ex.: `natural_person`, `legal_person`). | | `document_number` | string | Documento, quando houver. | | `distributor` | object | Dados da distribuidora (`distributor_key`, `document_number`, `name`, `account_data`). | | `external_id` | string | Opcional — identificador externo. | | `external_distribution_key` | string | Opcional — chave de distribuição externa. | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------- | | 400 | `QIT000004` | O fundo não é da gestora | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta paginada de posições de cotistas por classe de fundo URL: /zh-Hans/documentation/iaas/passivo/consultas/consulta_posicoes_cotistas_classe_fundo Endpoint de consulta paginada que retorna as **posições por investidor e série de emissão** em uma classe de fundo: cotistas com saldo de cotas na aplicação financeira, com valor de cota obtido do fechamento mais recente da série. Utilize `document_number` para filtrar um cotista específico. :::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 /quota/fund_class/{fund_class_key}/investor_positions MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `20`. Máximo: `100`. | | `document_number` | string | opcional | Filtra pelo documento do investidor (com pontuação). | ```text title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/investor_positions?page=0&limit=20&document_number=969.698.790-03 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "investor": { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "11.222.333/0001-81", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "11.222.333/0001-81" }, "account_digit": "1", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "341", "financial_institution_ispb": "60746948" } }, "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Maria Cotista Silva", "person_type": "natural_person", "document_number": "969.698.790-03", "external_id": "ext-inv-001" }, "issuance_serie": { "issuance_serie_key": "c3d4e5f6-a7b8-9012-cdef-123456789012", "original_quota_value": 1.0, "current_number_of_quotas": 500000.0, "current_net_worth": 525000.75, "current_principal_value": 500000.0, "performance_fee_current_value": 0.0, "remuneration_type": "yield_curve", "interest_rate_type": "post_fixed", "name": "Série Única", "serie": 1, "sub_class": { "name": "Cota Sênior", "sub_class_key": "d4e5f6a7-b8c9-0123-def0-234567890123", "subordination_level": 1, "fund_class": { "name": "Fundo Exemplo FIDC", "short_name": "FEX", "document_number": "11.222.333/0001-81", "fund_class_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "accounting_date": "2024-06-01", "sub_type": "regular", "tax_classification": "long_term", "condominum_type": "open_ended", "prevent_payment": false, "manager": { "manager_key": "f6a7b8c9-d0e1-2345-f012-456789012345", "document_number": "11.222.333/0001-81", "manager_name": "Gestora Exemplo S.A." } } }, "status": "active", "internal_code": "INT-FEX-01", "current_quota_value": 1.0500015, "post_fixed": { "calendar_base": "calendar_252", "indexer": "cdi", "rate": 1.0, "lag": { "reference": "daily", "amount": 1 } }, "isin_code": "BRSTREXTFID6", "water_mark_events": [] }, "number_of_quotas": 10000.0, "quota_value": 1.05234567 } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de posições. Cada item agrega **investidor**, **série de emissão**, **quantidade de cotas** e **valor de cota** (`quota_value` quando existir fechamento). | | `page` | integer | Página atual. | | `limit` | integer | Tamanho da página solicitado. | | `is_last_page` | boolean | Indica se não há mais registros após esta página. | #### Objeto em `data` | Campo | Tipo | Descrição | |---|---|---| | `investor` | object | Dados do cotista e da distribuidora. | | `issuance_serie` | object | Série de emissão da posição, incluindo `sub_class` e `fund_class` aninhados. | | `number_of_quotas` | number | Soma das cotas da aplicação financeira para aquele investidor e série. | | `quota_value` | number | Valor de cota do fechamento mais recente da série; omitido se não houver fechamento disponível. | Campos opcionais de `issuance_serie` (como `pre_fixed`, `post_fixed`, `isin_code`, `external_id`) só aparecem quando preenchidos no cadastro da série. Só entram posições com saldo de cotas maior que zero, em fundos da gestora da integração. Um fundo de outra gestora devolve lista vazia. Para mais contexto sobre séries, consulte [Consulta paginada de séries de emissão](/documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao). ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------- | | 404 | `QTA000002` | Classe de fundo não encontrada | | 404 | `QTA00053` | Gestora da integração não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 发行系列结算分页查询 URL: /zh-Hans/documentation/iaas/passivo/consultas/consultar_fechamentos_serie_de_emissao 分页返回某发行系列的**每日结算**（结算各阶段的份额价值和净资产），按会计日期从新到旧排序。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota/fund_class/{fund_class_key}/sub_class/{sub_class_key}/issuance_serie/{issuance_serie_key}/issuance_serie_closings MÉTODO GET STATUS 200 ### Path params | 参数 | 类型 | 描述 | |---|---|---| | `fund_class_key` | string | 基金类别唯一键（UUID）。 | | `sub_class_key` | string | 该系列所属子类别的唯一键（UUID）。 | | `issuance_serie_key` | string | 发行系列唯一键（UUID）。 | 这些键可通过 **[发行系列分页查询](/documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao)** 获取。 ### Query params | 参数 | 类型 | 是否必填 | 描述 | |---|---|---|---| | `accounting_date` | string (日期) | 视情况 | 特定结算的会计日期（`YYYY-MM-DD`）。 | | `from_date` | string (日期) | 视情况 | 周期起始会计日期（`YYYY-MM-DD`）。须与 `to_date` 一同发送。 | | `to_date` | string (日期) | 视情况 | 周期结束会计日期（`YYYY-MM-DD`）。须与 `from_date` 一同发送。 | | `status` | string | 可选 | 以逗号分隔的结算状态列表。`pending_distribution`：返回指数化系列在基金尚未结算日期的份额价值。`closed`：返回已完成的结算。未传此参数时，仅返回已计算出总份额价值的结算。 | | `page` | integer | 可选 | 页码（从 `0` 开始）。默认：`0`。 | | `limit` | integer | 可选 | 每页记录数。默认：`50`。最大：`500`。 | :::caution 注意 必须发送 `accounting_date` **或** `from_date` 与 `to_date` 的组合。两者都未发送时，API 返回 `QTA000026`。 ::: ```text title="调用示例" GET /quota/fund_class/{fund_class_key}/sub_class/{sub_class_key}/issuance_serie/{issuance_serie_key}/issuance_serie_closings?from_date=2026-09-29&to_date=2026-09-30&page=0&limit=50 ``` ## Response ```json title="响应体" { "data": [ { "gross_quota_value": 1250.0, "gross_net_worth": 1250000.0, "accounting_date": "2026-09-30", "status": "closed", "before_amortization_quota_value": 1248.5, "before_amortization_net_worth": 1248500.0, "quota_value": 1248.5, "total_net_worth": 1248500.0, "closed_net_worth": 1248500.0, "closed_quota_value": 1248.5, "performance_fee_current_value": 1500.0 }, { "gross_quota_value": 1249.1, "gross_net_worth": 1249100.0, "accounting_date": "2026-09-29", "status": "closed", "before_amortization_quota_value": 1247.7, "before_amortization_net_worth": 1247700.0, "quota_value": 1247.7, "total_net_worth": 1247700.0, "closed_net_worth": 1247700.0, "closed_quota_value": 1247.7, "performance_fee_current_value": 1400.0 } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### 响应属性 | 字段 | 类型 | 描述 | |---|---|---| | `data` | array | 该系列的结算列表，按会计日期从新到旧排序。 | | `limit` | integer | 每页大小。 | | `page` | integer | 当前页码。 | | `is_last_page` | boolean | 表示分页是否结束。 | #### `data` 中每条结算的字段 | 字段 | 类型 | 描述 | |---|---|---| | `accounting_date` | string | 结算的会计日期（`YYYY-MM-DD`）。 | | `gross_quota_value` | float | 总份额价值，扣除业绩报酬前。 | | `gross_net_worth` | float | 总净资产，扣除业绩报酬前。 | | `status` | string | 结算状态（例如 `pending_distribution`、`closed`）。 | | `before_amortization_quota_value` | float | 扣除业绩报酬后、摊销前的份额价值。 | | `before_amortization_net_worth` | float | 扣除业绩报酬后、摊销前的净资产。 | | `quota_value` | float | 当日最终份额价值，摊销后。 | | `total_net_worth` | float | 当日最终净资产，摊销后。 | | `closed_quota_value` | float | 结算锁定的份额价值。 | | `closed_net_worth` | float | 结算锁定的净资产。 | | `performance_fee_current_value` | float | 计提的业绩报酬金额。 | 除 `accounting_date`、`gross_quota_value` 和 `gross_net_worth` 外，其他字段仅在当日已计算时返回。 ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ----------------------------------------------------------------- | | 400 | `QTA000026` | 未发送 `accounting_date`，也未发送 `from_date`/`to_date` | | 400 | `QIT000004` | 该基金不属于该管理人 | | 404 | `QTA000002` | 未找到基金类别 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 份额演变图分页查询 URL: /zh-Hans/documentation/iaas/passivo/consultas/consultar_mapa_de_evolucao_de_cotas 基于基金已确认的投资组合，按日返回某发行系列的份额演变（净资产、份额价值、变动和收益率）。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | ------------------- | | 管理人 | `manager-api` | 读取 | | 顾问 | `consultant-api` | View Compositions | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/issuance_serie/ISSUANCE_SERIE_KEY/quota_evolution_map MÉTODO GET STATUS 200 ## Params | 参数 | 类型 | 必填 | 描述 | | -------------------- | ------ | ----------- | ------------------------- | | `fund_class_key` | `UUID` | 是 | 基金键 | | `issuance_serie_key` | `UUID` | 是 | 发行系列键 | ## Query Params | 参数 | 类型 | 必填 | 描述 | | ---------------- | ------------ | ----------- | ------------------------------------------------ | | `reference_date` | `YYYY-MM-DD` | 视情况 | 查询的单一参考日期 | | `start_date` | `YYYY-MM-DD` | 视情况 | 区间起始日期 | | `end_date` | `YYYY-MM-DD` | 视情况 | 区间结束日期 | | `limit` | `int` | 否 | 每页记录数（默认：50，最大：100） | | `page` | `int` | 否 | 当前页码（默认：0） | :::caution 注意 发送 `reference_date`（单日）**或** `start_date` 与 `end_date` 这一对参数（区间），二者不可同时发送。结果按日期从新到旧排序。 ::: 案例 01：单一日期的返回结果 ```json { "data": [ { "gross_net_worth": 10867777.38, "net_net_worth": 10867777.38, "gross_quota_value": 1.855893979904, "net_quota_value": 1.855893979904, "number_of_quotas": 5855818.003441199, "composition_date": "2025-05-04", "applied_value": 0.0, "applied_quotas": 0.0, "redeemed_value": 0.0, "redeemed_quotas": 0.0, "amortized_value": 0.0, "tax_anticipated_value": 0.0, "tax_anticipated_quotas": 0.0, "daily_rentability": 0.0006, "monthly_rentability": 0.0072, "yearly_rentability": 0.0898 } ], "is_last_page": true, "page": 0, "limit": 10 } ``` ## Quota Evolution Map | 字段 | 类型 | 描述 | | ------------------------ | ------ | --------------------------------------------------------------- | | `gross_net_worth` | number | 组合日的总资产 | | `net_net_worth` | number | 组合日的净资产 | | `gross_quota_value` | number | 份额总价值 | | `net_quota_value` | number | 份额净价值 | | `number_of_quotas` | number | 当日份额总数 | | `composition_date` | string | 组合日期（格式：`YYYY-MM-DD`） | | `applied_value` | number | 当日申请金额 | | `applied_quotas` | number | 当日申请的份额数量 | | `redeemed_value` | number | 当日赎回金额 | | `redeemed_quotas` | number | 当日赎回的份额数量 | | `amortized_value` | number | 当日摊销金额 | | `tax_anticipated_value` | number | 当日预缴税额 | | `tax_anticipated_quotas` | number | 当日预缴税对应的份额数量 | | `daily_rentability` | number | 日收益率（小数格式，例如 `0.0007` 表示 0.07%） | | `monthly_rentability` | number | 月收益率（小数格式，例如 `0.0060` 表示 0.60%） | | `yearly_rentability` | number | 年收益率（小数格式，例如 `0.096` 表示 9.6%） | 收益率字段仅在当日已计算时返回。 ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ------------------------------------------------------------------------------- | | 400 | `CMP000018` | 未发送任何日期过滤条件 | | 400 | `CMP000019` | `reference_date` 与 `start_date`/`end_date` 同时发送，或该对日期只发送了其中一个 | | 400 | `CMP000017` | `start_date` 晚于 `end_date` | | 400 | `CMP000021` | 该系列不属于所提供的基金 | | 400 | `QIT000004` | 该基金不属于该管理人 | | 403 | `CMP000032` | 顾问：该基金不属于授予访问权限的管理人 | | 404 | `CMP000001` | 未找到基金类别 | | 404 | `CMP000020` | 未找到发行系列 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 发行系列分页查询 URL: /zh-Hans/documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao 分页列出管理人旗下基金的发行系列。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota/issuance_series MÉTODO GET STATUS 200 ## Query Params | 参数 | 描述 | | ---------------------------- | ------------------------------------------------------------------------------------------ | | `page` | 页码，从 0 开始（默认 0） | | `limit` | 每页条目数（默认 20，最大 500） | | `issuance_serie_key` | 发行系列唯一键 | | `fund_class_document_number` | 该系列所属基金的 CNPJ | | `fund_class_name` | 基金名称的一部分（不区分大小写） | | `only_active` | 为 `true` 时，仅返回有流通份额且状态不为 `settled` 和 `pending_first_integralization` 的系列（默认 `false`） | | `not_in_status` | 要从结果中排除的系列状态列表 | 案例 01：返回一个发行系列 ```json { "data": [ { "issuance_serie_key": "UUID", "name": "SERIE 1", "serie": 1, "status": "active", "internal_code": "FUNDOEX-SR1", "remuneration_type": "residual", "original_quota_value": 1.0, "current_quota_value": 1.0518, "current_number_of_quotas": 500000.0, "current_net_worth": 525900.0, "current_principal_value": 500000.0, "performance_fee_current_value": 0.0, "minimum_share_capital": 0.0, "operation_period_configuration": {}, "sub_class": { "name": "COTA SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "name": "FUNDO EXEMPLO", "short_name": "FUNDO EX", "fund_class_key": "UUID", "document_number": "11.222.333/0001-81", "accounting_date": "2025-01-10", "sub_type": "regular", "tax_classification": "long_term", "condominum_type": "open_ended", "prevent_payment": false, "manager": { "manager_key": "UUID", "document_number": "11.222.333/0001-81", "manager_name": "GESTORA EXEMPLO" }, "administrator": { "name": "QI DTVM", "administrator_key": "UUID", "document_number": "11.222.333/0001-81" } } }, "water_mark_events": [] } ], "limit": 20, "page": 0, "is_last_page": true } ``` ## Issuance Serie | 字段 | 类型 | 描述 | | -------------------------------- | ------ | ------------------------------------------------------------------------- | | `issuance_serie_key` | string | 系列唯一键 | | `name` | string | 系列名称 | | `serie` | number | 系列编号 | | `status` | string | `created`、`pending_first_integralization`、`active` 或 `settled` | | `internal_code` | string | 系列内部代码 | | `remuneration_type` | string | `yield_curve` 或 `residual` | | `original_quota_value` | number | 原始份额价值 | | `current_quota_value` | number | 当前份额价值（净资产 ÷ 份额；无份额时为原始值） | | `current_number_of_quotas` | number | 流通份额 | | `current_net_worth` | number | 当前净资产 | | `current_principal_value` | number | 当前本金 | | `performance_fee_current_value` | number | 计提的业绩报酬 | | `minimum_share_capital` | number | 最低申请金额 | | `operation_period_configuration` | object | 申请和赎回的计价与付款期限 | | `interest_rate_type`, `pre_fixed`, `post_fixed` | — | 系列的收益设置（如有） | | `isin_code`, `external_id` | string | 有值时返回 | | `sub_class` | object | 子类别（`name`、`sub_class_key`、`subordination_level`）及 `fund_class` | | `water_mark_events` | array | 高水位线事件（业绩报酬） | `fund_class` 对象的字段与[基金分页查询](/documentation/iaas/passivo/consultas/consultar_todos_fundos)相同。 ## 错误 此查询没有业务规则错误：无匹配结果的过滤条件返回空的 `data`。 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 基金分页查询 URL: /zh-Hans/documentation/iaas/passivo/consultas/consultar_todos_fundos 分页列出管理人的基金类别。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota/fund_classes MÉTODO GET STATUS 200 ## Query Params | 参数 | 描述 | | ----------------- | ----------------------------------------------------------------------- | | `page` | 页码，从 0 开始（默认 0） | | `limit` | 每页条目数（默认 50，最大 500） | | `name` | 基金名称或简称的一部分（不区分大小写） | | `document_number` | 基金 CNPJ | | `fund_class_key` | 基金唯一键 | 案例 01：仅返回一个基金 ```json { "data": [ { "name": "FUNDO EXEMPLO", "short_name": "FUNDO EX", "document_number": "11.222.333/0001-81", "fund_class_key": "UUID", "accounting_date": "2025-01-10", "sub_type": "regular", "tax_classification": "long_term", "condominum_type": "open_ended", "prevent_payment": false, "manager": { "manager_key": "UUID", "document_number": "11.222.333/0001-81", "manager_name": "GESTORA EXEMPLO" }, "administrator": { "name": "QI DTVM", "administrator_key": "UUID", "document_number": "11.222.333/0001-81" } } ], "limit": 50, "page": 0, "is_last_page": true } ``` ## Fund Class | 字段 | 类型 | 描述 | | ----------------------------- | ------- | --------------------------------------------------------------- | | `fund_class_key` | string | 基金唯一键 | | `name` | string | 基金名称 | | `short_name` | string | 基金简称 | | `document_number` | string | 基金 CNPJ | | `accounting_date` | string | 基金当前会计日期 | | `sub_type` | string | 基金子类型：`regular` 或 `cash` | | `tax_classification` | string | 税务分类 | | `condominum_type` | string | 基金组织形式：`open_ended`（开放式）或 `close_ended`（封闭式） | | `prevent_payment` | boolean | 表示基金的付款是否被冻结 | | `manager` | object | 管理人：`manager_key`、`document_number`、`manager_name` | | `administrator` | object | 管理机构：`administrator_key`、`name`、`document_number`（如有）| | `integralization_account_key` | string | 缴款账户（如有） | ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | --------------------------------------------- | | 400 | `QIT000004` | 未找到该集成对应的管理人 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 发送已签署认购公告 URL: /zh-Hans/documentation/iaas/passivo/controle_de_oferta/enviar_boletim_de_subscricao_assinado --- ## 简介 本资源旨在向我们发送**投资者**对某基金**份额发行**的**认购公告**签署证明。 :::caution 注意 本资源仅适用于担任**分销商**角色的集成。请使用分销商配置文件的 API 密钥和主机：参见 [环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Input / Output: 作为***输入***，需发送认购信息、投资者所认购的**份额发行** UUID、**签署方式**，以及根据签署方式进行验证所需的内容。示例如下。 作为***输出***，将返回所创建**认购公告**的完整对象，其中包含用于标识该认购公告的 ***subscription_note_key***。认购公告创建时即为 `active` 状态（若 `remaining_subscription_note_value` 为零，则为 `sold_off`）。 ## Request ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/signed_subscription_note MÉTODO POST STATUS 201 ## Request body ```json title='请求体' { "number_of_quotas": 500.0, "original_subscription_note_value": 50000.00, "start_date": "2026-01-15", "maturity_date": "2026-12-31", "quota_offering_key": "UUID", "transaction_type": "ted", "signature_method": "opt_in", "opt_in_hash" : "OPT_IN_HASH" } ``` | 字段 | 类型 | 描述 | 必填 | |-------------------------------------|--------|------------------------------------------------------------------------------------------------------------|-------------| | `original_subscription_note_value` | number | 认购公告金额。最小值为 0。不得超过发行的剩余金额 | 是 | | `quota_offering_key` | string | 份额发行的 UUID。该发行必须为 `active` 状态、有剩余金额，且没有待处理的补充协议 | 是 | | `transaction_type` | string | `ted` 或 `b3` | 是 | | `signature_method` | string | 所用签署方式。使用 `opt_in` 时发送 `opt_in_hash`；使用其他任何方式时发送 `document_b64` | 是 | | `opt_in_hash` | string | opt-in 哈希值（最多 250 个字符） | 否 | | `document_b64` | string | 以 base64 编码的已签署认购公告 | 否 | | `number_of_quotas` | number | 认购公告的份额数量 | 否 | | `remaining_subscription_note_value` | number | 认购公告剩余余额。不得大于 `original_subscription_note_value` | 否 | | `start_date` | string | 开始日期（`YYYY-MM-DD`）。如省略，则使用当前日期（UTC） | 否 | | `maturity_date` | string | 到期日期（`YYYY-MM-DD`）。不得为过去的日期 | 否 | :::caution 注意 在集成过程中，将要求提供对所发送哈希值进行认证的方式。 ::: ## Response 响应格式与[申请认购公告](/documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao#response)的响应相同。 ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ------------------------------------------------------------------------------------- | | 400 | `QOF000020` | `maturity_date` 为过去的日期 | | 400 | `QOF000026` | 认购公告金额大于发行的剩余金额 | | 400 | `QOF000046` | `transaction_type` 无效 | | 400 | `QOF000047` | 投资者分类不允许认购该发行 | | 400 | `QOF000068` | `signature_method` 无效 | | 400 | `QOF000069` | `signature_method` 为 `opt_in`，但未发送 `opt_in_hash` | | 400 | `QOF000072` | `signature_method` 不是 `opt_in`，但未发送 `document_b64` | | 400 | `QOF000150` | `remaining_subscription_note_value` 大于 `original_subscription_note_value` | | 400 | `QIT000004` | 该集成不是该投资者的分销商 | | 404 | `QOF000017` | 未找到投资者 | | 404 | `QOF000019` | 未找到份额发行 | | 404 | `QOF000039` | 该发行未激活、已到期或没有剩余金额 | | 409 | `QOF000152` | 该发行有一份待审批的补充协议 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 获取认购公告信息 URL: /zh-Hans/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao --- 以分页方式列出某投资者或某基金类别的**认购公告**。 ## Request ### 投资者的认购公告 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_notes MÉTODO GET STATUS 200 管理人只能获取其所管理基金的发行下的认购公告。 | Query param | 描述 | |------------------------------|-------------------------------------------------------------------------------------------------| | `limit` | 每页条目数。默认 50，最大 500 | | `page` | 页码，从 0 开始。默认 0 | | `status` | 按状态过滤。可传入多个值，以逗号分隔 | | `issuance_serie_key` | 按发行系列过滤 | | `fund_class_document_number` | 按基金类别 CNPJ 过滤 | | `financial_application_key` | 按金融申请过滤 | | `quotation_date` | 与 `status=sold_off` 一起使用时，返回在该日期（`YYYY-MM-DD`）售罄的认购公告 | ### 基金类别的认购公告 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/subscription_notes MÉTODO GET STATUS 200 | Query param | 描述 | |----------------------------|-------------------------------------------------------------------------------| | `limit` | 每页条目数。默认 50，最大 500 | | `page` | 页码，从 0 开始。默认 0 | | `status` | 按状态过滤。可传入多个值，以逗号分隔 | | `investor_key` | 按投资者过滤 | | `investor_document_number` | 按投资者 CPF/CNPJ 过滤 | ## Responses 案例 01：有认购公告的投资者 ```json { "data":[ { "subscription_note_key":"UUID", "quota_offering":{ "quota_offering_key":"UUID", "status":"active / closed", "original_quota_offering_value":0.00, "issued_number_of_quotas":0.00000000, "remaining_quota_offering_value":0.00, "start_date":"YYYY-MM-DD", "issuance_serie":{ "name":"1", "issuance_serie_key":"UUID", "sub_class":{ "name":"SÊNIOR", "sub_class_key":"UUID", "subordination_level":1, "fund_class":{ "fund_class_key":"UUID", "name":"SAMPLE FUND CLASS NAME", "document_number":"00.000.000/0000-00", "short_name":"SAMPLE FUND CLASS SHORT NAME" } }, "classification":"general / qualified / professional", "market_type":"primary / secondary" }, "type":"public / private", "subscription_note_template_key":"UUID", "subscription_note_generation_type":"internal / external", "regulatory_type":"exclusive_fund", "cvm_registration":{ "date":"YYYY-MM-DD", "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000" }, "lead_coordinator":{ "name":"SAMPLE LEAD COORDINATOR NAME", "address":{ "uf":"SP", "city":"São Paulo", "number":"0000", "street":"Sample street name", "complement":"Sample complement" }, "document_number":"00.000.000/0000-00" }, "status_events":[ { "status":"active", "event_datetime":"YYYY-MM-DD HH:MM:SS" } ] }, "investor":{ "distributor":{ "distributor_key":"UUID", "document_number":"00.000.000/0000-00", "name":"Sample Distributor Name" }, "investor_key":"UUID", "document_number":"00.000.000/0000-00", "name":"SAMPLE INVESTOR NAME", "person_type":"natural_person / legal_person" }, "status":"active", "transaction_type":"b3 / ted", "signature_method":"certifiqi / qi_sign / opt_in / external", "original_subscription_note_value":0.00, "issued_number_of_quotas":0.00000000, "remaining_subscription_note_value":0.00, "total_assignment_value":0.00, "start_date":"YYYY-MM-DD", "financial_application_events":[ { "financial_application_event_key":"UUID", "financial_application_key":"UUID", "type":"consume_value", "share_capital":0.00, "event_datetime":"YYYY-MM-DD HH:MM:SS" }, { "financial_application_event_key":"UUID", "financial_application_key":"UUID", "type":"update_quotas", "number_of_quotas":0.00, "event_datetime":"YYYY-MM-DD HH:MM:SS" }, { "financial_application_event_key":"UUID", "financial_application_key":"UUID", "type":"cancel", "event_datetime":"YYYY-MM-DD HH:MM:SS" } ], "status_events":[ { "status":"created", "event_datetime":"YYYY-MM-DD HH:MM:SS" }, { "status":"active", "event_datetime":"YYYY-MM-DD HH:MM:SS" } ] } ], "limit":50, "page":0, "is_last_page":true } ``` 案例 02：没有认购公告的投资者 ```json { "data":[], "limit":50, "page":0, "is_last_page":true } ``` ## Response Fields | 字段 | 类型 | 描述 | |---------------|--------|----------------------------------------------------------------| | `data` | array | **[Subscription Note](#subscription-note)** 对象列表 | | `limit` | int | 每页返回的对象数量上限 | | `page` | int | 返回的页码 | | `is_last_page`| boolean| 表示返回的页面是否为最后一页 | ## Subscription Note | 字段 | 类型 | 描述 | |---------------------------|----------|-------------------------------------------------------------------------------------------------------| | `subscription_note_key` | string | 认购公告唯一标识键 | | `quota_offering` | JSON | **[Quota Offering](#quota-offering)** 对象 | | `investor` | JSON | **[Investor](#investor)** 对象 | | `status` | string | 认购公告状态。参见 **[Subscription Note Status](#subscription-note-status)** | | `signature_method` | string | `certifiqi` / `qi_sign` / `opt_in` / `external` | | `total_assignment_value` | float | 认购公告的转让总额 | | `status_events` | array | 状态历史（`status`、`event_datetime`） | | `transaction_type` | string | `ted` / `b3` | | `original_subscription_note_value` | float | 认购公告原始金额 | | `issued_number_of_quotas` | float | 已发行份额数量 | | `remaining_subscription_note_value` | float | 认购公告剩余金额 | | `start_date` | string | 认购公告开始日期 | | `financial_application_events`| array | **[Financial Application Event](#financial-application-event)** 对象列表 | | `maturity_date` | string | 到期日期。未填写时不返回 | | `original_number_of_quotas`| float | 原始份额数量。未填写时不返回 | ## Subscription Note Status | 枚举值 | 描述 | |-----------------------------|-----------------------------------------------| | `created` | 已创建 | | `pending_batch_close` | 等待批次关闭 | | `send_to_generate_document` | 已发送生成文件 | | `pending_document` | 等待文件 | | `pending_manual_inputs` | 等待手动录入数据（外部生成） | | `pending_signature` | 等待签署 | | `active_without_signature` | 有效（未签署） | | `active` | 有效 | | `sold_off` | 已售罄 | | `processing_cancellation` | 取消中 | | `canceled` | 已取消 | | `processing_expired` | 过期处理中 | | `expired` | 已过期 | ## Quota Offering `quota_offering` 对象的字段与 [发行信息](/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas#quota-offering) 响应中的字段相同，包括嵌套的 `issuance_serie`、`sub_class` 和 `fund_class` 对象。 ## Financial Application Event | 字段 | 类型 | 描述 | |-----------------------------------|----------|-----------------------------------------------------------------------------------------| | `financial_application_key` | string | 金融申请唯一标识键 | | `financial_application_event_key` | string | 金融申请事件唯一标识键 | | `type` | string | 消耗金额 / 更新份额 / 取消 | | `event_datetime` | string | 事件日期和时间 | | `share_capital` | float | 金融申请的出资金额。仅当 `type` 为 `consume_value` 时返回 | | `number_of_quotas` | float | 金融申请的份额数量。仅当 `type` 为 `update_quotas` 时返回 | ## Investor | 字段 | 类型 | 描述 | |--------------------------|----------|---------------------------------------------------| | `name` | string | 投资者名称 | | `investor_key` | string | 投资者唯一标识键 | | `document_number` | string | 投资者 CPF/CNPJ | | `person_type` | string | 自然人 / 法人 / 基金类别 | | `distributor` | JSON | **[Distributor](#distributor)** 对象 | ## Distributor | 字段 | 类型 | 描述 | |--------------------------|----------|---------------------------------------------------| | `name` | string | 分销商名称 | | `distributor_key` | string | 分销商唯一标识键 | | `document_number` | string | 分销商 CPF/CNPJ | ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ----------------------------------------------------------------------- | | 400 | `QIT000004` | 该基金类别不由该管理人管理 | | 404 | `QOF000007` | 未找到基金类别 | | 404 | `QOF000017` | 未找到投资者 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 获取发行信息 URL: /zh-Hans/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas --- 以分页方式列出某基金类别的**份额发行**。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/quota_offerings MÉTODO GET STATUS 200 ## Query Params | 参数 | 描述 | |----------------------|------------------------------------------------------------------------------------------------------------| | `limit` | 每页条目数。默认 50，最大 500 | | `page` | 页码，从 0 开始。默认 0 | | `sub_class_key` | 子类别唯一标识键 | | `issuance_serie_key` | 发行系列唯一标识键 | | `showOffers` | `active`：仅返回有剩余金额的有效发行。`closed`：已关闭或已过到期日的发行 | ## Responses 案例 01：有发行的基金 ```json { "data":[ { "quota_offering_key":"UUID", "status":"active", "original_quota_offering_value":0.00, "issued_number_of_quotas":0.00000000, "remaining_quota_offering_value":0.00, "start_date":"YYYY-MM-DD", "issuance_serie":{ "name":"1", "issuance_serie_key":"UUID", "sub_class":{ "name":"SÊNIOR", "sub_class_key":"UUID", "subordination_level":1, "fund_class":{ "fund_class_key":"UUID", "name":"SAMPLE FUND CLASS NAME", "document_number":"00.000.000/0000-00", "short_name":"SAMPLE FUND CLASS SHORT NAME" } }, "classification":"general / qualified / professional", "market_type":"primary / secondary" }, "type":"public / private", "subscription_note_template_key":"UUID", "subscription_note_generation_type":"internal / external", "regulatory_type":"exclusive_fund", "cvm_registration":{ "date":"YYYY-MM-DD", "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000" }, "lead_coordinator":{ "name":"SAMPLE LEAD COORDINATOR NAME", "address":{ "uf":"SP", "city":"São Paulo", "number":"0000", "street":"Sample street name", "complement":"Sample complement" }, "document_number":"00.000.000/0000-00" }, "status_events":[ { "status":"active", "event_datetime":"YYYY-MM-DD HH:MM:SS" } ] } ], "limit":50, "page":0, "is_last_page":true } ``` 案例 02：没有发行的基金 ```json { "data":[], "limit":50, "page":0, "is_last_page":true } ``` ## Response Fields | 字段 | 类型 | 描述 | |---------------|--------|----------------------------------------------------------------| | `data` | array | **[Quota Offering](#quota-offering)** 对象列表 | | `limit` | int | 每页返回的对象数量上限 | | `page` | int | 返回的页码 | | `is_last_page`| boolean| 表示返回的页面是否为最后一页 | ## Quota Offering | 字段 | 类型 | 描述 | |-----------------------------------|----------|-----------------------------------------------------------------------------------------| | `quota_offering_key` | string | 发行唯一标识键 | | `status` | string | `created` / `active` / `processing_closing` / `pending_closing_at_cvm` / `pending_closing_at_anbima` / `pending_divulgation` / `closed` | | `subscription_note_generation_type` | string | `internal`（文件由 QI 生成）/ `external` | | `subscription_note_template_key` | string | 认购公告模板键 | | `regulatory_type` | string | 发行的监管类型 | | `status_events` | array | 状态历史（`status`、`event_datetime`） | | `original_quota_offering_value` | float | 发行原始金额 | | `issued_number_of_quotas` | float | 已认购份额数量 | | `remaining_quota_offering_value` | float | 发行剩余金额 | | `start_date` | string | 发行起始日期 | | `issuance_serie` | string | **[Issuance Serie](#issuance-serie)** 对象 | | `type` | string | 公开/私募发行类型 | | `cvm_registration` | JSON | CVM 登记数据。未填写时不返回 | | `lead_coordinator` | JSON | 牵头协调人数据。未填写时不返回 | | `maturity_date` | string | 到期日期。未填写时不返回 | | `original_number_of_quotas` | float | 原始份额数量。未填写时不返回 | cvm_registration ```json { "date":"YYYY-MM-DD", "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000" } ``` lead_coordinator ```json { "name":"SAMPLE LEAD COORDINATOR NAME", "address":{ "uf":"SP", "city":"São Paulo", "number":"0000", "street":"Sample street name", "complement":"Sample complement" }, "document_number":"00.000.000/0000-00" } ``` ## Issuance Serie | 字段 | 类型 | 描述 | |-------------------------------|----------|---------------------------------------------------| | `name` | string | 发行系列名称 | | `issuance_serie_key` | string | 发行系列唯一标识键 | | `sub_class` | JSON | **[Sub Class](#sub-class)** 对象 | | `classification` | string | 专业 / 合格 / 普通 | | `market_type` | string | 一级 / 二级 | | `serie` | integer | 发行系列在子类别内的顺序编号（1、2、3……），同一子类别内不重复 | ## Sub Class | 字段 | 类型 | 描述 | |-------------------------------|----------|---------------------------------------------------| | `name` | string | 子类别名称 | | `sub_class_key` | string | 子类别唯一标识键 | | `subordination_level` | int | 子类别从属级别 | | `fund_class` | JSON | **[Fund Class](#fund-class)** 对象 | ## Fund Class | 字段 | 类型 | 描述 | |-------------------------------|----------|---------------------------------------------------| | `name` | string | 基金类别名称 | | `fund_class_key` | string | 基金类别唯一标识键 | | `document_number` | string | 基金类别 CNPJ | | `short_name` | string | 基金类别简称 | ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ---------------------------------------------- | | 400 | `QIT000004` | 该基金类别不由该管理人管理 | | 404 | `QOF000007` | 未找到基金类别 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 申请认购公告 URL: /zh-Hans/documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao --- ## 简介 本资源旨在为**投资者**创建对某基金**份额发行**的**认购公告**申请。基于此申请，系统将根据发行中配置的生成类型生成认购公告文件。 ## Input / Output: 作为***输入***，需发送投资者所认购的**份额发行** UUID、**认购公告金额**、**交易类型**，以及可选的签署方式和签署人组。示例如下。 作为***输出***，将返回所创建**认购公告**的完整对象，其中包含 ***subscription_note_key***。***subscription_note_key*** 用于标识**认购公告**。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 写入 | 该发行必须属于该管理人的基金。各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_note MÉTODO POST STATUS 201 ## Path Params | 参数 | 描述 | |-------------------|-----------------------| | `INVESTOR_KEY` | 投资者的 UUID | ## Request body ```json title='请求体' { "original_subscription_note_value": 50000.00, "quota_offering_key": "UUID", "transaction_type": "ted", "signature_method": "certifiqi", "signer_group_key": "UUID" } ``` ## Subscription Note | 字段 | 类型 | 描述 | 必填 | |------------------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------|-------------| | `original_subscription_note_value` | number | 认购公告金额。最小值为 0。不得超过发行的剩余金额 | 是 | | `quota_offering_key` | string | 份额发行的 UUID（36 个字符）。该发行必须存在且状态为 `active` | 是 | | `transaction_type` | string | `ted` 或 `b3`。使用 `b3` 时，基金类别必须已登记 B3 账户 | 是 | | `signature_method` | string | 签署方式枚举值。如省略，将根据主体类型确定：`natural_person` → `qi_sign`，`legal_person` → `certifiqi` | 否 | | `signer_group_key` | string | 签署人组的 UUID（36 个字符）。如省略，则使用投资者的默认签署人组 | 否 | | `number_of_quotas` | number | 认购公告的份额数量。最小值为 0 | 否 | | `start_date` | string | 认购公告开始日期（`YYYY-MM-DD`）。如省略，则使用当前日期（UTC） | 否 | | `maturity_date` | string | 认购公告到期日期（`YYYY-MM-DD`）。不得为过去的日期 | 否 | ## Signature Method | 枚举值 | 描述 | |---------------|--------------------------------------------------------------| | `certifiqi` | 通过 CertifiQi 签署（数字证书） | | `qi_sign` | 通过 QI Sign 签署（电子签名） | ## Response ```json title='响应体' { "subscription_note_key": "UUID", "status": "send_to_generate_document", "original_number_of_quotas": 500, "original_subscription_note_value": 50000.00, "issued_number_of_quotas": 0, "remaining_subscription_note_value": 50000.00, "total_assignment_value": 0.00, "start_date": "YYYY-MM-DD", "transaction_type": "ted", "signature_method": "certifiqi", "investor": { "distributor": { "distributor_key": "UUID", "document_number": "11.222.333/0001-81", "name": "SAMPLE DISTRIBUTOR NAME" }, "investor_key": "UUID", "name": "SAMPLE INVESTOR NAME", "person_type": "natural_person / legal_person", "document_number": "00.000.000/0000-00" }, "quota_offering": { "quota_offering_key": "UUID", "status": "active", "original_quota_offering_value": 10000000.00, "issued_number_of_quotas": 25000.00, "remaining_quota_offering_value": 7500000.00, "start_date": "YYYY-MM-DD", "issuance_serie": { "name": "1", "issuance_serie_key": "UUID", "external_id": "SERIE-001", "sub_class": { "name": "SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "fund_class_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE FUND CLASS NAME", "short_name": "SAMPLE FUND CLASS SHORT NAME", "manager": { "name": "SAMPLE MANAGER NAME", "manager_key": "UUID", "document_number": "00.000.000/0000-00" }, "administrator": { "name": "SAMPLE ADMINISTRATOR NAME", "administrator_key": "UUID", "document_number": "00.000.000/0000-00", "data": {} }, "b3_account": "123456" } }, "classification": "general / qualified / professional", "market_type": "primary / secondary", "serie": 1, "issuance_serie_configuration": {} }, "type": "public / private", "subscription_note_template_key": "UUID", "subscription_note_generation_type": "internal / external", "regulatory_type": "exclusive_fund", "maturity_date": "YYYY-MM-DD", "status_events": [ { "status": "created", "event_datetime": "YYYY-MM-DD HH:MM:SS" }, { "status": "active", "event_datetime": "YYYY-MM-DD HH:MM:SS" } ] }, "financial_application_events": [], "status_events": [ { "status": "created", "event_datetime": "YYYY-MM-DD HH:MM:SS" }, { "status": "send_to_generate_document", "event_datetime": "YYYY-MM-DD HH:MM:SS" } ] } ``` **[Quota Offering](/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas#quota-offering)**、**[Investor](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#investor)** 和 **[Financial Application Event](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#financial-application-event)** 对象的详细说明请参阅 **[认购公告信息](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao)** 页面。 当发行在内部生成文件时（`subscription_note_generation_type: internal`），认购公告创建时为 `send_to_generate_document` 状态；外部生成时则为 `pending_manual_inputs`。`maturity_date` 和 `original_number_of_quotas` 仅在有值时才出现在响应中。 ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ---------------------------------------------------------------------------------------------------- | | 400 | `QIT000004` | 该发行不属于该管理人的基金 | | 400 | `QOF000020` | `maturity_date` 为过去的日期 | | 400 | `QOF000026` | 认购公告金额大于发行的可用金额 | | 400 | `QOF000043` | 未找到投资者注册信息 | | 400 | `QOF000046` | `transaction_type` 不是 `ted` 或 `b3` | | 400 | `QOF000047` | 投资者分类不允许认购该发行 | | 400 | `QOF000076` | 投资者在该发行中已有两份有效的认购公告 | | 400 | `QOF000082` | 投资者注册信息已过期 | | 400 | `QOF000090` | 投资者在该发行的系列中已有一份未签署的有效认购公告 | | 400 | `QOF000103` | 投资者没有签署人组（或 `signer_group_key` 不存在） | | 400 | `QOF000104` | 该发行为专属发行，且投资者不在允许的投资者之列 | | 400 | `QOF000130` | 投资者注册处于非运营状态 | | 404 | `QOF000017` | 未找到投资者 | | 404 | `QOF000019` | 未找到份额发行 | | 404 | `QOF000039` | 该发行未激活、已到期或没有剩余金额 | | 404 | `QOF000053` | `transaction_type` 为 `b3`，但基金类别未登记 B3 账户 | | 404 | `QOF000073` | 未找到 `signature_method` | | 409 | `QOF000025` | 投资者在该发行的系列中已有一份待签署的认购公告 | | 409 | `QOF000152` | 该发行有一份待审批的补充协议 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 获取公开份额 URL: /zh-Hans/documentation/iaas/passivo/fundos/cotas_publicas 按参考日期返回各发行系列已批准且公开的份额价值。这是公开查询：无需 API 密钥，也无需对请求签名。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ---- | ------------------- | ------------------------ | | 公开 | `api.qidtvm.com.br` | 无（无需 API 密钥） | 公开主机仅服务于**生产环境**。各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /public_dash/mark_to_market/fund_quota/mark_to_markets MÉTODO GET STATUS 200 ### Query Params | 参数 | 类型 | 描述 | |-----------------------------|----------|---------------------------------------------------------------------------------------| | `internal_codes` | list | 发行系列内部代码列表（以逗号分隔，或重复传入该参数） | | `from_reference_date` | string | 查询周期起始日期（YYYY-MM-DD） | | `to_reference_date` | string | 查询周期结束日期（YYYY-MM-DD） | | `internal_code` | string | 要查询的发行系列唯一代码 | | `fund_class_document_number`| string | 要查询的基金 CNPJ（含标点） | | `limit` | int | 每页条目数：1 至 400（默认 10） | | `page` | int | 页码，从 0 开始（默认 0） | 仅返回状态为已批准且标记为公开的份额价值。 :::caution 注意 份额价值位于**发行系列（issuance_serie）**层面，因此使用 **fund_class_document_number** 参数将返回所有系列。 建议仅将此过滤器用于映射发行系列的唯一标识符（**internal_code** 和 **issuance_serie_key**）。 ::: ## Response ```json title='响应体' { "data": [ { "issuance_serie_key": "1de4125b-48c7-40ca-b97b-0b65fb356468", "internal_code": "INTERNAL-CODE-2", "fund_class_document_number": "11.222.333/0001-81", "fund_class_name": "FUNDO DE INVESTIMENTO DE TESTES", "marks_to_market": [ { "reference_date": "2025-09-05", "before_amortization_unit_price": 1000, "unit_price": 1000 } ] }, { "issuance_serie_key": "71f7ee44-388d-4916-b068-647e82fd67c8", "internal_code": "INTERNAL-CODE-1", "fund_class_document_number": "11.222.333/0001-81", "fund_class_name": "FUNDO DE INVESTIMENTO DE TESTES", "marks_to_market": [ { "reference_date": "2025-09-04", "before_amortization_unit_price": 1000, "unit_price": 1000 } ] } ], "limit": 5, "page": 0, "is_last_page": true } ``` ### Issuance Serie | 字段 | 类型 | 描述 | |-----------------------------------|--------|--------------------------------------------------------------| | `issuance_serie_key` | string | 发行系列标识键 | | `internal_code` | string | 内部标识发行系列的代码 | | `fund_class_document_number` | string | 所查询投资基金的 CNPJ | | `fund_class_name` | string | 所查询投资基金的名称 | | `marks_to_market` | array | **[Marks To Market](#marks-to-market)** 对象列表 | ### Marks To Market | 字段 | 类型 | 描述 | |-----------------------------------|--------|--------------------------------------------------------------| | `reference_date` | string | 发行系列份额价值日期（YYYY-MM-DD） | | `before_amortization_unit_price` | float | 摊销前的发行系列份额价值 | | `unit_price` | float | 结算后的发行系列份额价值 | ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ------ | ------------------------------------------------------------------ | | 400 | — | `limit` 超出 1 至 400 范围、`page` 为负数，或日期格式无效 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 简介 URL: /zh-Hans/documentation/iaas/passivo/inicio 欢迎使用**被动业务**相关操作的集成文档。本节介绍与所提供服务交互所需的所有工具和资源，从投资者注册到执行金融操作。 ## 概述 被动业务 API 提供一套功能，旨在便于投资基金的金融操作管理和执行。通过它，可以进行投资者注册、金融申请、赎回申请、份额锁定及其他资产管理基本操作。 服务通过端点提供，使客户应用程序与平台之间能够进行安全高效的通信。 ### 服务访问 要获得服务访问权限，需要在我们的同质化环境（Sandbox）和生产环境中完成必要的开放配置。请通过电子邮件 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 联系集成团队，申请访问凭证并获取激活流程指导。 ## 可用资源 ### 投资者注册 - **创建投资者/投资者分析**：允许注册投资者并进行初始注册分析。详见：[5.9.2.1 创建投资者](/documentation/iaas/investidor/cadastro/criar_investidor) - **查询投资者信息**：查询投资者的注册信息。详见：[5.9.2.2 查询投资者信息](/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor) - **查询投资者注册分析信息**：允许查询投资者注册分析状态。详见：[5.9.2.3 查询注册分析](/documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor) - **发送注册数据**：发送补充注册数据进行分析。详见：[5.9.2.4 发送注册数据](/documentation/iaas/investidor/cadastro/enviar_dados_cadastrais) ### 金融申请 - **创建金融申请**：允许在某发行系列中创建金融申请。详见：[5.9.5.1 创建金融申请](/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira) - **查询金融申请**：允许通过键或分页搜索查询金融申请。详见：[5.9.5.2 按键查询](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave) 和 [5.9.5.3 分页查询](/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras) ### 赎回申请 - **创建赎回申请**：允许为投资者创建赎回申请。详见：[5.9.6.1 创建赎回申请](/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate) - **查询赎回申请**：通过键或分页搜索查询赎回申请。详见：[5.9.6.2 按键查询](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave)、[5.9.6.3 按投资者分页查询](/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor) 和 [5.9.6.4 按基金类别分页查询](/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo) ### 份额锁定 - **申请份额锁定**：允许申请份额锁定作为担保。详见：[5.9.8.1 申请份额锁定](/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas) - **查询份额锁定**：按投资者或分页方式查询份额锁定。详见：[5.9.8.2 查询份额锁定](/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas) ## 结语 本文档作为被动业务服务集成和使用的完整指南。如有疑问，请通过电子邮件 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 联系我们的支持团队。 --- # Consulta paginada de negociações em mercado secundário URL: /zh-Hans/documentation/iaas/passivo/mercado_secundario/consulta_negociacoes_mercado_secundario Endpoint de consulta paginada que retorna as **negociações de cotas em mercado secundário** de uma classe de fundo. Cada registro representa a transferência de uma quantidade de cotas de um cotista vendedor para um cotista comprador, com o valor de cota praticado na negociação e a tributação retida do vendedor. Cada negociação relaciona três aplicações financeiras: | Papel | Descrição | |---|---| | `sold_financial_application` | Aplicação do **vendedor**, da qual as cotas saíram. É por ela que os filtros de classe de fundo, série, investidor e depositária central são aplicados. | | `new_financial_application` | Aplicação criada para o **comprador**, com `financial_application_type` igual a `secondary_market`. | | `original_financial_application` | Aplicação que **originou a posição** no mercado primário. Em revendas sucessivas, a mesma aplicação original é propagada para todas as negociações da cadeia, permitindo rastrear a entrada original das cotas. | :::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 /quota/fund_class/{fund_class_key}/secondary_market_trades MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `50`. Máximo: `500`. | | `issuance_serie_key` | string | opcional | Filtra pelas negociações da série de emissão informada. | | `investor_key` | string | opcional | Filtra pelas negociações em que o investidor informado é o **vendedor**. | | `sold_financial_application_key` | string | opcional | Filtra pela aplicação financeira de origem das cotas negociadas. | | `central_depositary` | string | opcional | Filtra pela depositária central da aplicação de origem. Valores: `cetip` (cotas depositadas na B3) ou `unregistered` (cotas não depositadas). | Os registros são retornados em ordem cronológica de criação da negociação. ```text title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/secondary_market_trades?page=0&limit=50&issuance_serie_key=c3d4e5f6-a7b8-9012-cdef-123456789012¢ral_depositary=cetip ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "secondary_market_trade_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "original_financial_application": { "financial_application_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "share_capital": 500000.0, "status": "quoted", "redemption_keys": [ { "redemption_key": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "financial_application_type": "primary_market", "original_number_of_quotas": 500000.0, "current_principal_value": 490000.0, "acquisition_cost": 500000.0, "current_number_of_quotas": 490000.0, "quotation_date": "2026-03-02", "payment_method": "b3", "investor_key": "d4e5f6a7-b8c9-0123-def0-234567890123", "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "external_id": "ext-fa-001" }, "sold_financial_application": { "financial_application_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "share_capital": 500000.0, "status": "quoted", "redemption_keys": [ { "redemption_key": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "financial_application_type": "primary_market", "original_number_of_quotas": 500000.0, "current_principal_value": 490000.0, "acquisition_cost": 500000.0, "current_number_of_quotas": 490000.0, "quotation_date": "2026-03-02", "payment_method": "b3", "investor_key": "d4e5f6a7-b8c9-0123-def0-234567890123", "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "external_id": "ext-fa-001" }, "new_financial_application": { "financial_application_key": "f6a7b8c9-d0e1-2345-f012-456789012345", "share_capital": 10523.45, "status": "quoted", "redemption_keys": [], "financial_application_type": "secondary_market", "original_number_of_quotas": 10000.0, "current_principal_value": 1.05234567, "acquisition_cost": 1.05234567, "current_number_of_quotas": 10000.0, "quotation_date": "2026-03-02", "payment_method": "b3", "investor_key": "a7b8c9d0-e1f2-3456-0123-567890123456", "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234" }, "trade_quota_value": 1.05234567, "number_of_quotas": 10000.0, "event_datetime": "2026-07-31 00:00:00", "taxable_yield_value": 523.45, "ir_value": 78.52, "iof_value": 0.0 } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de negociações da classe de fundo. | | `page` | integer | Página atual. | | `limit` | integer | Tamanho da página solicitado. | | `is_last_page` | boolean | Indica se não há mais registros após esta página. | #### Objeto em `data` | Campo | Tipo | Descrição | |---|---|---| | `secondary_market_trade_key` | string | Chave única da negociação. | | `original_financial_application` | object | Aplicação financeira que originou a posição no mercado primário. | | `sold_financial_application` | object | Aplicação financeira do vendedor, de onde saíram as cotas. | | `new_financial_application` | object | Aplicação financeira criada para o comprador. | | `trade_quota_value` | number | Valor de cota praticado na negociação. | | `number_of_quotas` | number | Quantidade de cotas negociadas. | | `event_datetime` | string | Data e hora do evento de negociação. | | `taxable_yield_value` | number | Rendimento tributável apurado para o vendedor na negociação. Omitido quando não apurado. | | `ir_value` | number | Imposto de renda retido do vendedor. Omitido quando não apurado. | | `iof_value` | number | IOF retido do vendedor. Omitido quando não apurado. | #### Objeto de aplicação financeira | Campo | Tipo | Descrição | |---|---|---| | `financial_application_key` | string | Chave única da aplicação financeira. | | `share_capital` | number | Valor aportado na aplicação. | | `status` | string | Situação da aplicação, por exemplo `quoted`, `settled`, `redeemed`. | | `redemption_keys` | array | Chaves dos resgates associados à aplicação. Na aplicação do vendedor inclui o resgate gerado pela negociação. | | `financial_application_type` | string | `primary_market` ou `secondary_market`. | | `original_number_of_quotas` | number | Quantidade de cotas na criação da aplicação. | | `current_number_of_quotas` | number | Quantidade de cotas atual. | | `current_principal_value` | number | Valor principal atual. | | `acquisition_cost` | number | Custo de aquisição. | | `quotation_date` | string | Data de cotização. | | `payment_method` | string | Forma de liquidação, por exemplo `b3` ou `regular`. | | `investor_key` | string | Chave do investidor titular da aplicação. | | `issuance_serie_key` | string | Chave da série de emissão da aplicação. | | `external_id` | string | Identificador externo, quando informado no cadastro da aplicação. | Campos opcionais são omitidos da resposta quando não houver valor. Para consultar as aplicações financeiras em detalhe, consulte [Consulta paginada de aplicações financeiras](/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras). ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------- | | 400 | `QIT000004` | O fundo não é da gestora da integração | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 按键查询赎回申请 URL: /zh-Hans/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave 按键返回投资者的某笔赎回申请。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota/investor/INVESTOR_KEY/redemption_request/REDEMPTION_REQUEST_KEY MÉTODO GET STATUS 200 管理人只能查询其自身基金的赎回申请。 ## Responses 案例 01：查询成功 ```json { "redemption_request_key": "UUID", "redemption_request_type": "gross_redemption_value", "status": "quoted", "quotation_date": "2025-01-15", "payment_date": "2025-01-16", "payment_method": "regular", "request_datetime": "2025-01-14T13:05:00Z", "redemption_request_data": { "gross_redemption_value": 1000.0 }, "processed_value": 1000.0, "ir_value": 2.78, "iof_value": 0.0, "investor": { "investor_key": "UUID", "name": "INVESTIDOR EXEMPLO", "person_type": "natural_person", "document_number": "969.698.790-03", "distributor": { "distributor_key": "UUID", "document_number": "11.222.333/0001-81", "name": "DISTRIBUIDORA EXEMPLO", "account_data": {} } }, "issuance_serie": { "issuance_serie_key": "UUID", "name": "SERIE 1", "sub_class": { "name": "COTA SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "name": "FUNDO EXEMPLO", "fund_class_key": "UUID", "document_number": "11.222.333/0001-81" } } }, "payments": [ { "payment_key": "UUID", "origin_key": "UUID", "total_value": 997.22, "payment_type": "redemption.investor", "payment_date": "2025-01-16", "status": "paid" } ], "status_events": [ { "status": "pending_quote", "event_datetime": "2025-01-14T13:05:00Z" }, { "status": "quoted", "event_datetime": "2025-01-15T21:00:00Z" } ] } ``` ### Redemption Request {#redemption_request} | 字段 | 类型 | 描述 | | ------------------------- | ------ | ---------------------------------------------------------------------------- | | `redemption_request_key` | string | 赎回申请唯一键 | | `redemption_request_type` | string | **[Redemption Request Type](#redemption_request_type)** 枚举值 | | `status` | string | **[Redemption Request Status](#redemption_request_status)** 枚举值 | | `quotation_date` | string | 计价日期 | | `payment_date` | string | 付款日期 | | `payment_method` | string | `regular` 或 `b3` | | `request_datetime` | string | 申请创建的日期和时间（UTC） | | `redemption_request_data` | object | 创建时发送的金额（例如 `gross_redemption_value`、`net_value`） | | `processed_value` | float | 赎回已处理金额 | | `ir_value` | float | 赎回的所得税（IR） | | `iof_value` | float | 赎回的金融操作税（IOF） | | `investor` | object | 投资者：`investor_key`、`name`、`person_type`、`document_number` 和 `distributor` | | `issuance_serie` | object | 发行系列，包含 `sub_class` 和 `sub_class.fund_class` | | `payments` | array | 生成的付款（投资者、IR、IOF）：`payment_key`、`origin_key`、`total_value`、`payment_type`、`payment_date`、`status`、`status_events` | | `status_events` | array | 状态历史：`status` 和 `event_datetime`（UTC） | | `cancellation_data` | object | 取消数据，仅在申请已取消时返回 | ### Redemption Request Type {#redemption_request_type} | 枚举值 | 描述 | | ----------------------------- | -------------------------------- | | `gross_redemption_value` | 按总额赎回 | | `number_of_quotas` | 按份额数量赎回 | | `remaining_application_value` | 按剩余持仓赎回 | | `net_value_redemption` | 按净额赎回 | ### Redemption Request Status {#redemption_request_status} | 枚举值 | 描述 | | ----------------------------------- | ---------------------------------------------- | | `created` | 已创建 | | `pending_manager_approval` | 等待管理人审批 | | `pending_quote` | 待计价 | | `processing_quotation` | 计价处理中 | | `pending_quotation_date_input` | 等待设定计价日期 | | `processing_issuance_serie_impacts` | 正在处理对系列的影响 | | `quoted` | 已计价 | | `canceled` | 已取消 | | `reprocessed` | 已重新处理 | ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | ----------------------------------------------------- | | 400 | `QIT000004` | 该赎回申请不属于该管理人的基金 | | 404 | `QTA000036` | 未找到该投资者的赎回申请 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # Consulta paginada de pedidos de resgate por classe de fundo URL: /zh-Hans/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo Lista **pedidos de resgate** de uma **classe de fundo** da gestora (`fund_class_key`), com paginação e filtros opcionais. :::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 /quota/fund_class/{fund_class_key}/redemption_requests MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. | | `status` | array de strings | opcional | Um ou mais status do pedido. Repita o parâmetro para enviar mais de um. | | `quotation_date` | string | opcional | Filtra pela data de cotização (`YYYY-MM-DD`). | | `investor_name` | string | opcional | Parte do nome do investidor (sem diferenciar maiúsculas). | | `investor_document_number` | string | opcional | Filtra pelo documento do investidor, no mesmo formato em que foi cadastrado (com pontuação). | | `request_from_datetime` | string (date-time) | opcional | Pedidos com data/hora de solicitação maior ou igual ao valor, no formato `YYYY-MM-DDTHH:MM:SSZ` (UTC). | | `request_to_datetime` | string (date-time) | opcional | Pedidos com data/hora de solicitação menor ou igual ao valor, no formato `YYYY-MM-DDTHH:MM:SSZ` (UTC). | ```text title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/redemption_requests?page=0&limit=50&investor_document_number=969.698.790-03 ``` ## Response STATUS 200 Cada item de `data` é o objeto **Redemption Request** completo, descrito em [Consultar Pedido de Resgate por chave](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request) — lá estão também os [tipos](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request_type) e os [status](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request_status). ```json title="Response Body (resumido)" { "data": [ { "redemption_request_key": "UUID", "redemption_request_type": "number_of_quotas", "status": "quoted", "quotation_date": "2024-06-15", "payment_date": "2024-06-18", "payment_method": "regular", "request_datetime": "2024-06-10T14:00:00Z", "redemption_request_data": { "number_of_quotas": 500.0 }, "processed_value": 5250.5, "ir_value": 0.0, "iof_value": 0.0 } ], "limit": 20, "page": 0, "is_last_page": true } ``` | Campo | Tipo | Descrição | | -------------- | ------- | ---------------------------------- | | `data` | array | Pedidos de resgate | | `limit` | integer | Itens por página | | `page` | integer | Página retornada | | `is_last_page` | boolean | `true` quando não há mais páginas | Um valor de `status` que não existe não gera erro: a consulta apenas não encontra pedidos. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------ | | 400 | `QIT000001` | Data ou data/hora em formato inválido | | 400 | `QIT000004` | O fundo não é da gestora | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta paginada de pedidos de resgate por investidor URL: /zh-Hans/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor Retorna os **pedidos de resgate** de um investidor identificado por `investor_key`, com paginação e filtros opcionais. A lista é ordenada por fundo, subclasse, série e data de cotização (mais recente primeiro). :::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 /quota/investor/{investor_key}/redemption_requests MÉTODO GET Para a gestora, a consulta retorna apenas pedidos em fundos dela, e só de investidores aos quais ela está vinculada. ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. | | `status` | array de strings | opcional | Um ou mais status do pedido. Repita o parâmetro para enviar mais de um. | | `quotation_date` | string | opcional | Filtra pela data de cotização no formato `YYYY-MM-DD`. | | `fund_class_document_number` | string | opcional | Filtra pelo CNPJ da classe de fundo. | | `request_from_datetime` | string (date-time) | opcional | Pedidos com data/hora de solicitação maior ou igual ao valor, no formato `YYYY-MM-DDTHH:MM:SSZ` (UTC). | | `request_to_datetime` | string (date-time) | opcional | Pedidos com data/hora de solicitação menor ou igual ao valor, no formato `YYYY-MM-DDTHH:MM:SSZ` (UTC). | ```text title="Exemplo de chamada" GET /quota/investor/{investor_key}/redemption_requests?page=0&limit=20&status=quoted"ation_date=2024-06-15 ``` ## Response STATUS 200 Cada item de `data` é o objeto **Redemption Request** completo, descrito em [Consultar Pedido de Resgate por chave](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request) — lá estão também os [tipos](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request_type) e os [status](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request_status). ```json title="Response Body (resumido)" { "data": [ { "redemption_request_key": "UUID", "redemption_request_type": "number_of_quotas", "status": "quoted", "quotation_date": "2024-06-15", "payment_date": "2024-06-18", "payment_method": "regular", "request_datetime": "2024-06-10T14:00:00Z", "redemption_request_data": { "number_of_quotas": 500.0 }, "processed_value": 5250.5, "ir_value": 0.0, "iof_value": 0.0 } ], "limit": 20, "page": 0, "is_last_page": true } ``` | Campo | Tipo | Descrição | | -------------- | ------- | ---------------------------------- | | `data` | array | Pedidos de resgate | | `limit` | integer | Itens por página | | `page` | integer | Página retornada | | `is_last_page` | boolean | `true` quando não há mais páginas | Um valor de `status` que não existe não gera erro: a consulta apenas não encontra pedidos. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------ | | 400 | `QIT000001` | Data ou data/hora em formato inválido | | 400 | `QIT000004` | A gestora não está vinculada ao investidor | | 404 | `QTA000021` | Investidor não encontrado | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 创建赎回申请 URL: /zh-Hans/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate 为投资者在某发行系列中创建份额赎回申请。封闭式基金不接受赎回申请。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | -------- | | 管理人 | `manager-api` | 写入 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /quota/investor/INVESTOR_KEY/redemption_request MÉTODO POST STATUS 201 ```json title='请求体' { "issuance_serie_key": "UUID", "redemption_request_type": "gross_redemption_value", "gross_redemption_value": 1000.0, "payment_method": "regular", "disbursement_account_key": "UUID", "quotation_date": "2025-01-15" } ``` :::caution 注意 **redemption_request_type** 字段决定应发送哪个金额字段。**只**发送该字段；发送属于其他类型的字段将返回 `QTA000025`。 - `gross_redemption_value`：发送 `gross_redemption_value`。 - `remaining_application_value`：发送 `remaining_application_value`。 - `number_of_quotas`：发送 `number_of_quotas`。 - `net_value_redemption`：发送 `net_value`。 **disbursement_account_key** 字段用于指定接收付款的投资者特定账户。未提供时，使用投资者的主账户。 ::: ### Body params | 字段 | 类型 | 描述 | 必填 | | ----------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------- | | `issuance_serie_key` | string | 发行系列唯一键 | 是 | | `redemption_request_type` | string | **[赎回申请类型](#tipos_de_pedido_de_resgate)**枚举值 | 是 | | `gross_redemption_value` | float | 赎回总额，未扣除所得税（IR）和金融操作税（IOF） | 视情况 | | `net_value` | float | 赎回净额，已扣除所得税（IR）和金融操作税（IOF） | 视情况 | | `remaining_application_value` | float | 申请剩余金额 | 视情况 | | `number_of_quotas` | float | 待赎回的份额数量 | 视情况 | | `disbursement_account_key` | string | 接收付款的投资者银行账户键 | 否 | | `quotation_date` | string | 赎回计价日期（`yyyy-mm-dd`）。必须为工作日，且符合该系列的期限规定 | 否 | | `payment_method` | string | 付款方式：`regular` **（默认）** 或 `b3` | 否 | | `reference_date` | string | 赎回参考日期（`yyyy-mm-dd`） | 否 | | `redemption_request_key` | string | 申请所用的键（UUID），如需自行指定 | 否 | 不在此列表中的字段将被拒绝，并返回 `QIT000001`。 ### 赎回申请类型 {#tipos_de_pedido_de_resgate} | 枚举值 | 描述 | | ----------------------------- | -------------------------------- | | `gross_redemption_value` | 按总额赎回 | | `number_of_quotas` | 按份额数量赎回 | | `remaining_application_value` | 按剩余持仓赎回 | | `net_value_redemption` | 按净额赎回 | ## Response 响应返回所创建的赎回申请，格式与[按键查询](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave)相同。请保存 `redemption_request_key`。 ```json title='响应体（摘要）' { "redemption_request_key": "UUID", "redemption_request_type": "gross_redemption_value", "status": "pending_quote", "quotation_date": "2025-01-15", "payment_date": "2025-01-16", "payment_method": "regular" } ``` ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | --------------------------------------------------------------------------------------------------- | | 400 | `QTA000025` | 缺少所选类型对应的金额字段，或发送了其他类型的字段 | | 400 | `QTA000190` | 按净额赎回的金额不超过 R$ 10,00（免税投资者除外） | | 400 | `QTA000241` | 同一天已存在按剩余金额赎回的申请 | | 400 | `QTA000242` | 因份额被锁定，可用金额不足 | | 400 | `QTA000176` | `quotation_date` 不是工作日 | | 400 | `QTA000182` | `quotation_date` 早于基金的会计日期 | | 400 | `QTA000186` | `quotation_date` 早于该系列的最早计价日期 | | 400 | `QTA000296` | 投资者类型为 `nominee` | | 400 | `QIT000004` | 管理人未与该投资者关联 | | 404 | `QTA000015` | 未找到发行系列 | | 404 | `QTA000021` | 未找到投资者 | | 404 | `QTA000180` | 该基金为封闭式，不接受赎回申请 | | 404 | `QTA000239` | 投资者的资产不足以覆盖所有已申请的赎回 | | 404 | `QTA000243` | 投资者在该系列中没有可赎回的申请 | | 422 | `QTA000357` | 操作被禁止：该系列的份额价值为零或负数 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 发送已签署入会协议 URL: /zh-Hans/documentation/iaas/passivo/termo_de_adesao/enviar_termo_de_adesao_assinado ## 简介 本资源旨在向我们发送**投资者**对某基金**发行系列**的**入会协议**签署证明。 :::caution 注意 本资源仅适用于担任**分销商**角色的集成。 ::: ### Input / Output: 作为***输入***，需发送投资者已入会的基金**发行系列** UUID、**签署类型**，以及根据签署方式进行验证所需的内容。示例如下。 作为***输出***，将返回 ***investor_adhesion_key***。***investor_adhesion_key*** 用于标识**投资者入会**。入会创建时即为 `active` 状态。 ## Request ENDPOINT /investor_adhesion/investor/INVESTOR_KEY/signed_investor_adhesion MÉTODO POST STATUS 201 ### Request body ```json title='请求体' { "issuance_serie_key": "UUID", "signature_method": "opt_in", "opt_in_hash" : "OPT_IN_HASH" } ``` | 字段 | 类型 | 描述 | 字符数 | 必填 | |----------------------|--------|---------------------------------------------------------------------------------------------|------------|-------------| | `issuance_serie_key` | string | 投资者已入会的发行系列键 | 36 | 是 | | `signature_method` | string | 所用签署方式：`opt_in` 或 `external` | 最多100 | 是 | | `opt_in_hash` | string | opt-in 哈希值。当 `signature_method` 为 `opt_in` 时必填 | 最多500 | 否 | | `document_b64` | string | 以 base64 编码的已签署协议。当 `signature_method` 为 `external` 时必填 | - | 否 | | `signer_group_key` | string | 投资者签署人组键。如省略，则使用投资者的默认签署人组 | 36 | 否 | :::caution 注意 在集成过程中，将要求提供对所发送哈希值进行认证的方式。 ::: ## Response ```json title='响应体' { "investor_adhesion_key": "UUID" } ``` ## 错误 | 状态 | 代码 | 发生情形 | | ------ | ----------- | --------------------------------------------------------------------------------------- | | 400 | `IAD000027` | 投资者分类不允许入会该系列 | | 400 | `IAD000037` | `signature_method` 为 `opt_in`，但未发送 `opt_in_hash` | | 400 | `IAD000038` | `signature_method` 为 `external`，但未发送 `document_b64` | | 400 | `IAD000039` | 该投资者已存在对此发行系列的入会 | | 400 | `IAD000051` | 投资者没有签署人组（或 `signer_group_key` 不存在） | | 400 | `IAD000054` | 投资者处于非运营状态 | | 400 | `QIT000011` | 该集成不是该投资者的分销商 | | 404 | `IAD000012` | 未找到投资者 | | 404 | `IAD000018` | 未找到发行系列 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # Solicitar Termo de Adesão URL: /zh-Hans/documentation/iaas/passivo/termo_de_adesao/solicitar_termo_de_adesao ## Introdução Este recurso tem como objetivo criar uma solicitação de **termo de adesão** de um **investidor** a uma **série de emissão** de um fundo. A partir desta solicitação, são gerados os documentos necessários para a formalização da adesão, de acordo com as configurações da série de emissão. ### Input / Output: Como ***input*** deve ser enviado o UUID da **série de emissão** em que o investidor está aderindo e, opcionalmente, o **método de assinatura** que será utilizado para os documentos gerados. Como ***output*** será entregue uma ***investor_adhesion_key***. A ***investor_adhesion_key*** é utilizada para identificar a **adesão do investidor**. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Adesões | A série de emissão precisa ser de um fundo da gestora (ou, para a consultoria, de um fundo em que ela tenha essa permissão). URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /investor_adhesion/investor/INVESTOR_KEY/investor_adhesion MÉTODO POST STATUS 201 ### Request body ```json title='Request Body' { "issuance_serie_key": "UUID", "signature_method": "qi_sign", "signer_group_key": "UUID" } ``` ### Investor Adhesion | Campo | Tipo | Descrição | Caracteres | Obrigatório | |----------------------|--------|------------------------------------------------------------------------|------------|-------------| | `issuance_serie_key` | string | Chave da série de emissão a qual o investidor está aderindo | 36 | Sim | | `signature_method` | string | Enumerador do método de assinatura a ser utilizado nos documentos. Se omitido: `qi_sign` para pessoa física e `certifiqi` para pessoa jurídica | - | Não | | `signer_group_key` | string | Chave do grupo de signatários do investidor. Se omitido, usa o grupo de signatários padrão do investidor | 36 | Não | ### Signature Method | Enumerador | Descrição | |---------------|--------------------------------------------------------------| | `certifiqi` | Assinatura via CertifiQi (Certificado Digital) | | `qi_sign` | Assinatura via QI Sign (Assinatura Eletrônica) | ## Response ```json title='Response Body' { "investor_adhesion_key": "UUID" } ``` :::info Fluxo da adesão - Se todos os documentos exigidos pela série já existirem e estiverem vigentes, a adesão é criada direto no status `active`. - Caso contrário, a adesão é criada no status `pending_documents` e permanece assim até que os documentos exigidos sejam gerados e assinados. - Se o investidor já tiver uma adesão `active`, `pending_documents` ou `pending_batch_close` para a mesma série de emissão, a requisição é rejeitada com `IAD000014`. ::: ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------------------------------------------ | | 400 | `IAD000027` | A classificação do investidor (geral, qualificado, profissional) não permite aderir à série | | 400 | `IAD000042` | O cadastro do investidor está pendente de atualização | | 400 | `IAD000045` | O investidor não possui suitability ativo | | 400 | `IAD000051` | O investidor não possui grupo de signatários (ou o `signer_group_key` informado não existe) | | 400 | `IAD000054` | O investidor está não operacional | | 400 | `QIT000011` | A série de emissão não pertence a um fundo da gestora | | 403 | `IAD000049` | A consultoria não tem a permissão de criar adesões no fundo da série | | 404 | `IAD000012` | Investidor não encontrado (na `manager-api`, hoje a resposta vem como `IAD000010`) | | 404 | `IAD000018` | Série de emissão não encontrada | | 404 | `IAD000040` | `signature_method` não encontrado | | 409 | `IAD000014` | O investidor já tem adesão ativa ou aguardando assinatura para essa série de emissão | | 409 | `IAD000057` | O investidor já possui um vínculo com essa série de emissão | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).