录入费用

录入一笔基金费用。不使用 submit 时，费用停留在 pending_submission，直到您通过提交发送；使用 submit: true 时，费用会在同一次调用中直接提交审核。

录入前，请在费用类型中查看哪些类型需要合同、哪些合同接受该类型。完整流程参见费用生命周期。管理费返佣使用同一调用，其专门规则参见管理费返佣。

录入费用

适用范围

角色	主机	所需权限
管理人	manager-api	写入
顾问	consultant-api	录入和编辑费用或提交合并

各主机的 Base URL：环境（主机）。

ENDPOINT

/expense/fund_class/{fund_class_key}/expense

方法

POST

路径参数

参数	类型	描述
fund_class_key	string	基金类别的 key（UUID）。

Corpo da requisição — despesa com contrato, paga na conta do fornecedor

{
    "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
    "expense_type": "audit_tax",
    "contract_key": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "description": "Auditoria do exercício 2026",
    "payment_value": 15000.00,
    "payment_date": "2026-11-24",
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "44.555.666/0001-81"
        },
        "vendor_bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c"
    },
    "documents": [
        {
            "name": "memoria_de_calculo.pdf",
            "document_type": "calculation_memory",
            "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
        }
    ],
    "consolidation_analysis_documents": [
        {
            "name": "nfe_001234.pdf",
            "document_type": "invoice",
            "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
        }
    ],
    "submit": true
}

Corpo da requisição — despesa sem contrato, por Pix, com provisão

{
    "expense_type": "notary",
    "description": "Registro de ata em cartório",
    "payment_value": 850.00,
    "payment_date": "2026-11-30",
    "start_deferral_date": "2026-11-03",
    "end_deferral_date": "2026-11-30",
    "payment_method": "pix",
    "payment": {
        "target": {
            "name": "CARTORIO EXEMPLO",
            "document_number": "11.222.333/0001-81"
        },
        "target_pix_key": "11222333000181"
    }
}

请求体属性

字段	类型	是否必填	描述
expense_key	string	否	由您指定的费用 key（UUID）。可用它安全地重发：基金中已使用过的 key 会返回 409（EXP000080）。不提供时由 QI Tech 生成。
expense_type	string	条件必填	费用类型。参见类型。必填，返佣除外（返佣始终为 distribution_fee）。不接受 pass_through_agent_fee。由 QI Tech 计算的类型（cetip_tax、selic_tax、custody_tax、administration_tax、management_tax 和 performance_fee）会以 EXP000218 被拒绝。
contract_key	string	条件必填	供应商合同（UUID）。需要合同的类型必填。notary、court_fee、cvm_tax、anbima_tax 和返佣禁止提供。接受该类型的合同参见费用类型。
description	string	是	描述，1 至 200 个字符。
payment_value	number	是	金额，大于零。
payment_date	string	条件必填	付款日期，YYYY-MM-DD，须为工作日，且不早于今天。必填，返佣除外（返佣禁止提供）。
start_deferral_date	string	否	计提开始日期，YYYY-MM-DD，须为工作日。须与 end_deferral_date 一起发送，或两者都不发送。返佣禁止提供。
end_deferral_date	string	否	计提结束日期，YYYY-MM-DD，须为工作日，等于或晚于开始日期。
payment_method	string	是	transfer（TED）、pix、bank_slip（Boleto）或 automatic_debit（自动扣款）。
payment	object	是	收款人和付款目标。参见付款数据。
is_reimbursement	boolean	否	当该费用用于向管理人或顾问报销其已支付的款项时为 true。返佣禁止使用。默认：false。
reimbursement_recipient	string	条件必填	manager 或 consultant。is_reimbursement: true 时必填。
rebated_expense_key	string	否	该返佣所抵扣的基金管理费（management_tax）的 key。提供后该费用成为返佣。参见管理费返佣。
documents	array	否	费用的文件，1 至 20 个。参见录入时的文件。
consolidation_analysis_documents	array	否	合并分析的文件（发票和凭证），1 至 20 个。
submit	boolean	否	true 时在同一次调用中将费用提交审核。返佣始终会被提交。默认：false。

不接受其他任何字段。

录入时的文件

documents 和 consolidation_analysis_documents 中的每一项包含：

字段	类型	是否必填	描述
name	string	是	文件名，1 至 255 个字符。
document_type	string	是	类型。在 documents 中：invoice、calculation_memory、contract、bank_slip、payment_receipt、evidence、extra_document、settlement_term 或 variance_justification。在 consolidation_analysis_documents 中：同上，但不含 contract 和 evidence。
document_b64	string	是	Base64 内容，每个文件最大 20 MB。

整个请求体最大 100 MB。

提交时（在此处或在提交中）所需的文件：

• 计算说明（calculation_memory），放在两个列表中任意一个：始终需要，返佣也不例外。
• 付款凭证（payment_receipt），放在 consolidation_analysis_documents 中：用于附发票（无合同类型为 Boleto）的报销，以及 cvm_tax 或 anbima_tax 的报销。

录入时发票（invoice）是可选的。如放在 consolidation_analysis_documents 中发送，就无需稍后再发送发票：合并分析会与费用一并提交。对于无合同的类型和返佣，Boleto（bank_slip）也可以，放在两个列表中任意一个均可。cvm_tax 和 anbima_tax 不需要发票。

响应

STATUS

201

返回该费用，结构与按 key 查询相同，permission_type: owner，不含 status_events 和 consolidation_status_events。状态为 pending_submission；当 submit 为 true 时，为提交的结果：

提交时的情形	费用状态
无计提，合同为 active 或无合同	pre_approved
有计提（start_deferral_date 和 end_deferral_date）	in_manual_analysis
无计提，合同仍在审核中	pending_contract_analysis

费用变为 pre_approved 或 in_manual_analysis 时，满足以下条件之一，合并分析（consolidation_analysis.status）也会变为 in_manual_analysis：

• 已发送发票（无合同类型为 Boleto）；或
• 类型为 cvm_tax 或 anbima_tax。

返佣保持 pre_approved，其分析只会随管理费的分析一起推进。参见管理费返佣。

错误

状态	code	发生情形
400	QIT000001	请求体无效：缺少必填字段、日期格式错误、该情形下禁止提供的字段（例如返佣带日期）或未定义的字段。
400	EXP000069	该基金类别不属于该管理人。
400	EXP000136	某个文件不是有效的 Base64。
400	EXP000137	某个文件超过 20 MB。
400	EXP000218	该类型由 QI Tech 计算：cetip_tax、selic_tax、custody_tax、administration_tax、management_tax 或 performance_fee。
400	EXP000120	该类型需要合同，但未发送 contract_key。
400	EXP000125	在无合同类型中发送了 contract_key。
400	EXP000134	is_reimbursement: true 但未提供 reimbursement_recipient。
400	EXP000121	payment_date 早于今天。
400	EXP000122	payment_date 不是工作日。
400	EXP000161	只发送了一个计提日期。
400	EXP000009	end_deferral_date 早于 start_deferral_date。
400	EXP000027	某个计提日期不是工作日。
400	EXP000126	该合同在基金中不存在。
400	EXP000128	该合同不涵盖该费用类型。
400	EXP000130	该合同已被拒绝或已取消。
400	EXP000129	该合同为 expired、amended 或其他不接受费用的状态。
400	EXP000131	在该合同中，该类型是自动计算的。
400	EXP000159	合同在计提结束日期之前到期（无计提时，在付款日期之前到期）。
400	EXP000178 至 EXP000183、EXP000208 至 EXP000211 及其他 payment 错误	参见付款数据。
400, 404	EXP000087、EXP000089、EXP000090、EXP000133、EXP000166、EXP000206、EXP000010 及其他返佣错误	参见管理费返佣。
400	EXP000138	提交时没有计算说明。
400	EXP000135	提交报销时没有付款凭证，且已发送发票（无合同类型为 Boleto）或类型为 cvm_tax 或 anbima_tax。
400	EXP000153	提交时：该合同已不再接受此费用。
403	EXP000124	顾问与该基金没有有效关联。通常 consultant-api 会先以 401（CIT000018）拒绝。
404	EXP000001	该基金类别不存在。
409	EXP000080	该 expense_key 已在基金中使用过。请查询已存在的费用。
413	EXP000177	请求体超过 100 MB。
503	EXP000132	API 无法读取该合同。请重试。

Exemplo

{
  "title": "Payment Target Must Be Contract Vendor",
  "description": "The payment target must be the vendor of the contract 0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d (document 44.555.666/0001-81).",
  "translation": "O favorecido do pagamento deve ser o fornecedor do contrato 0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d (documento 44.555.666/0001-81).",
  "code": "EXP000208"
}

认证、权限和主机相关错误：参见 API 错误。

下一步

• 处于 pending_submission 的费用：提交。
• 处于 pre_approved 且没有发票的费用：合并分析，用于发送发票。