合并分析

合并分析是发票环节：管理人或顾问发送费用的发票，QI Tech 在合并和付款前核对发票、金额和付款数据。每笔费用都有一个当前有效的分析（analysis_number 1、2……）。被拒绝的分析会由新的分析取代。

通过此处接收发票的费用：

• 管理人或顾问录入的费用；
• 由 QI Tech 计算、但发票由管理人提供的费用：
  • 来源为 manual、performance_fee 和 expense_control；
  • 来源为 quota_fee，custody_tax 和 administration_tax 除外；
  • 来源为 recurring_expense，由管理人合并且不通过自动扣款支付。

流程：

1. 费用处于 pre_approved 或 in_provision，分析处于 pending_submission。
2. 将发票和其他文件附加到分析。
3. 发送发票：分析进入 in_manual_analysis。
4. QI Tech 批准（分析为 approved，费用变为 consolidated）或拒绝（reproved）。顾问提交的发票会先经过管理人决定（pending_manager_approval）。
5. 被拒绝时，如果费用仍处于 pre_approved 或 in_provision，请开启新的分析，并从第 2 步重新开始。如果费用也变为 reproved（费用当时仍处于 in_manual_analysis 或 pending_manager_approval），请录入另一笔费用。

发票也可以在录入费用时一并发送：合并分析会与费用一起提交。

查询当前有效的分析

适用范围

角色	主机	所需权限
管理人	manager-api	读取
顾问	consultant-api	读取费用或读取合并

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

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/consolidation_analysis

方法

GET

返回该费用当前有效的分析。

STATUS

200

Corpo da resposta

{
    "consolidation_analysis_key": "e3f4a5b6-c7d8-4e9f-8a0b-1c2d3e4f5a6b",
    "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
    "analysis_number": 2,
    "status": "pending_submission",
    "expense_description": "Auditoria do exercício 2026",
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "44.555.666/0001-81"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "7",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60701190"
        }
    },
    "payment_date": "2026-11-20",
    "payment_value": 15000.0,
    "total_rebate_value": null,
    "is_reimbursement": false,
    "reimbursement_recipient": null,
    "reproval_reason": null,
    "reproval_details": null,
    "last_updated": "2026-11-09T14:10:00Z",
    "documents": [
        {
            "name": "nfe_001234.pdf",
            "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
            "consolidation_analysis_key": "e3f4a5b6-c7d8-4e9f-8a0b-1c2d3e4f5a6b",
            "document_type": "invoice",
            "status": "in_manual_analysis"
        }
    ]
}

分析的属性

字段	类型	描述
consolidation_analysis_key	string	分析的 key（UUID）。
expense_key	string	费用的 key。
analysis_number	integer	分析编号，从 1 开始。
status	string	参见分析状态。
expense_description	string	费用描述。
payment_method	string	transfer、pix、bank_slip 或 automatic_debit。
payment	object	付款数据，结构与录入相同。
payment_date	string	付款日期，YYYY-MM-DD。
payment_value	number	应付金额。对于管理费，为支付给管理人的净额，不含返佣。
total_rebate_value	number	仅限管理费：该管理费的返佣总额，在发送发票时记录，并在批准时按已批准的返佣重新计算。payment_value + total_rebate_value 即管理费的总额。其他费用以及发送之前为 null。
is_reimbursement	boolean	当该费用为报销时为 true。
reimbursement_recipient	string	manager、consultant 或 null。
reproval_reason	string	invalid_documents、missing_documents、incorrect_value、incorrect_payment_data、incorrect_information、manager_reproval、rebate_inconsistency 或 null。
reproval_details	string	拒绝的详细说明，或 null。
last_updated	string	最后修改时间，UTC 的 ISO 8601。
documents	array	分析的文件，包括已取消的文件：name、document_key、consolidation_analysis_key、document_type、status。
rebates	array	仅在查询 management_tax 的当前有效分析时返回：未取消的返佣，包含 expense_key、status、payment_value、consolidation_analysis_status、reproval_reason、reproval_details。

为分析附加文件

适用范围

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

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

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/consolidation_analysis/document

方法

POST

将发票或其他文件附加到分析。适用于分析处于 pending_submission 或 reproved 的情形。被拒绝后，请先开启新的分析，并将文件附加到新的分析：新的分析不会复制上一次分析的文件。

Corpo da requisição

{
    "name": "nfe_001234.pdf",
    "document_type": "invoice",
    "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
}

字段	类型	是否必填	描述
name	string	是	文件名，1 至 255 个字符。
document_type	string	是	invoice（发票）、bank_slip（Boleto）、calculation_memory（计算说明）、payment_receipt（付款凭证）、settlement_term（结清确认书）、variance_justification（金额差异说明）或 extra_document（附加文件）。
document_b64	string	是	Base64 内容，最大 20 MB。

STATUS

201

Corpo da resposta

{
    "name": "nfe_001234.pdf",
    "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
    "consolidation_analysis_key": "e3f4a5b6-c7d8-4e9f-8a0b-1c2d3e4f5a6b",
    "document_type": "invoice",
    "status": "in_manual_analysis"
}

查询和取消分析的文件

下载分析的文件：

适用范围

角色	主机	所需权限
管理人	manager-api	读取
顾问	consultant-api	读取费用或读取合并

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

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/consolidation_analysis/document/{document_key}

方法

GET

在该费用的所有分析中（而不仅是当前有效的分析）查找该文件，并返回带有 document_url 的文件：该下载链接有效期 24 小时，文件以 application/pdf 提供。

取消分析的文件：

适用范围

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

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

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/consolidation_analysis/document/{document_key}

方法

DELETE

将当前有效分析中的某个文件标记为 canceled。适用于分析处于 pending_submission 或 reproved 的情形。返回 200 及该文件。

开启新的分析

被拒绝后，开启下一个处于 pending_submission 的分析。金额、日期和付款数据从上一个分析复制而来；文件不会复制。适用于当前有效的分析为 reproved、费用处于 pre_approved 或 in_provision 的情形。对于返佣，复制的金额必须在管理费的余额之内。

适用范围

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

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

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/consolidation_analysis

方法

POST

此调用没有请求体。

STATUS

201

返回新的分析，结构与分析的属性相同，不含 rebates。

错误

状态	code	发生情形
400	EXP000164	该费用不接受合并分析，或分析或费用不处于该调用要求的状态。
400	EXP000163	新的分析：当前有效的分析不是 reproved，或费用既不处于 pre_approved，也不处于 in_provision。
400	EXP000087	新的返佣分析：金额超过管理费的余额。
400	EXP000136	文件不是有效的 Base64。
400	EXP000137	文件超过 20 MB。
400	QIT000001	请求体无效：缺少必填字段、document_type 不在列表中或包含未定义的字段。
400	EXP000069	该基金类别不属于该管理人。
403	EXP000156	该费用不是您录入的：由顾问录入而调用方为管理人，或反之。只有录入方可以发送发票、附加和取消文件以及开启新的分析。
404	EXP000010	该费用在基金中不存在。
404	EXP000071	该文件在分析中不存在。

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