合同查询

费用合同的读取调用：

按 key 查询合同：单个合同，包含状态历史和下载链接。
列出基金的合同和所有基金的合同：带筛选条件的分页列表。
合同汇总：按状态统计的合同数量。
补充协议历史：原始合同及其补充协议。

按 key 查询合同

返回合同及其状态历史，以及下载文件和附件的链接。

适用范围

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

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

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contract/{contract_key}

方法

GET

路径参数

参数	类型	说明
`fund_class_key`	string	基金类别的 key（UUID）。
`contract_key`	string	合同的 key（UUID）。

响应

STATUS

200

返回合同，结构见合同字段，并附加以下字段。

Trecho da resposta
{
    "contract_key": "3f2b8c1e-7d4a-4e9b-9a61-0c5d2e8f4b17",
    "status": "in_manual_analysis",
    "ai_analysis": {
        "ai_analysis_key": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
        "status": "valid",
        "analysis_result": {
            "document_numbers": {
                "fund_class": "33.444.555/0001-81",
                "vendor": "44.555.666/0001-81"
            },
            "expense_types": ["audit_tax"],
            "expiration_date": "2027-12-31",
            "recurrences": [
                {
                    "expense_type": "audit_tax",
                    "amount": 2500.0,
                    "start_date": "2027-01-01",
                    "end_date": "2027-12-31",
                    "periodicity": "monthly"
                }
            ],
            "prohibited_clauses": []
        }
    },
    "attachments": [
        {
            "attachment_key": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
            "status": "active",
            "created_at": "2026-11-09T14:20:11.004512",
            "download_url": "https://<link-temporario-de-download>"
        }
    ],
    "status_events": [
        {
            "status": "created",
            "event_datetime": "2026-11-09T14:03:22.498765",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "pending_submission",
            "event_datetime": "2026-11-09T14:03:22.498901",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "sent_to_analysis",
            "event_datetime": "2026-11-09T14:10:05.120034",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "in_manual_analysis",
            "event_datetime": "2026-11-09T14:11:40.774210",
            "author_type": "qitech",
            "author_name": null
        }
    ],
    "download_url": "https://<link-temporario-de-download>",
    "signed_download_url": null
}

字段	类型	说明
`status_events`	array	状态变更。每项包含 `status`、`event_datetime`、`author_type` 和 `author_name`。操作人说明见下文。
`download_url`	string	下载合同文件的 URL，有效期 24 小时。提交审核前指向最后上传的文件；之后指向冻结的文件。即使尚未上传任何文件也会返回该字段。
`signed_download_url`	string	下载已签署文件的 URL，有效期 24 小时；在该文件生成之前为 `null`。
`attachments[].download_url`	string	下载各附件的 URL，有效期 24 小时。
`ai_analysis.analysis_result`	object	从文件中读取的数据：`document_numbers`（`fund_class`、`vendor`）、`expense_types`、`expiration_date`、`recurrences` 和 `prohibited_clauses`。读取尚未完成或失败时为 `null`。

status_events 中的操作人：

author_type 为 manager 或 consultant，姓名在 author_name 中：由门户用户执行的操作。
author_type 为 qitech，且 author_name: null：其他所有情况，包括使用集成密钥通过 API 发起的调用。

ai_analysis.status: inconclusive 表示文件与合同数据之间存在差异。由 QI Tech 审核作出决定。

列出基金的合同

列出某一基金的合同，支持筛选和分页。

适用范围

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

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

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contracts

方法

GET

路径参数

参数	类型	说明
`fund_class_key`	string	基金类别的 key（UUID）。

查询参数

参数	类型	是否必填	说明
`status`	string	否	合同状态。可传入多个值，以逗号分隔。未知值不会报错，也不会匹配任何合同。
`expense_type`	string	否	声明了该费用类型的合同。
`vendor_key`	string	否	该供应商的合同。
`termination_status`	string	否	解除申请处于该状态的合同：`pending_analysis`、`approved` 或 `reproved`。
`limit`	integer	否	每页条数，`1` 至 `100`。默认：`10`。
`page`	integer	否	页码，从 `0` 开始。默认：`0`。

响应

STATUS

200

Corpo da resposta
{
    "data": [],
    "limit": 10,
    "page": 0,
    "is_last_page": true,
    "total": 0
}

data 中的每一项都是一个合同，结构见合同字段，不包含 status_events 和下载链接。total 为符合筛选条件的合同数量。

列表按合同从新到旧排列，合同链中的每个版本都作为单独的条目出现：被替代的合同（amended）、被驳回或取消的补充协议以及生效中的补充协议。对于补充协议，amended_contract_key 表示它所替代的合同。

列出所有基金的合同

列出管理人所有基金的合同。顾问则只包含其拥有“读取费用合同”权限的基金。

筛选条件和响应与基金合同列表相同。附加参数 fund_class_key 可限定为某一基金；超出该范围的基金返回空列表。

ENDPOINT

/expense_contract/contracts

方法

GET

权限：管理人（manager-api）：读取。顾问（consultant-api）：有效集成；结果只包含其拥有“读取费用合同”权限的基金。

合同汇总

统计在该期间内创建的合同数量，按当前状态分组。

ENDPOINT

/expense_contract/contracts/summary

方法

GET

权限：管理人（manager-api）：读取。顾问（consultant-api）：有效集成；结果只包含其拥有“读取费用合同”权限的基金。

参数	类型	是否必填	说明
`fund_class_key`	string	否	限定为某一基金。
`date_range_start`	string	否	创建期间的开始日期，`YYYY-MM-DD`。
`date_range_end`	string	否	创建期间的结束日期，`YYYY-MM-DD`。

未提供两个日期时，期间为当月第一天至今天。只提供一个日期时会被忽略。
基金范围与所有基金的列表相同。超出该范围的 fund_class_key 返回全为零的计数。

Corpo da resposta
{
    "period": {
        "start": "2026-11-01",
        "end": "2026-11-09"
    },
    "contracts": {
        "total": 7,
        "pending_submission": 2,
        "pending_vendor_approval": 0,
        "sent_to_analysis": 1,
        "in_compliance_analysis": 0,
        "in_manual_analysis": 1,
        "pending_manager_approval": 0,
        "pending_signature": 1,
        "active": 2,
        "expired": 0,
        "amended": 0,
        "reproved": 0,
        "canceled": 0
    }
}

补充协议历史

返回原始合同以及链中的所有补充协议，按从旧到新排列。可从链中的任意合同发起查询。

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contract/{contract_key}/history

方法

GET

权限：管理人（manager-api）：读取。顾问（consultant-api）：读取费用合同。

响应为 {"data": [...]}，不分页，其中的合同结构见合同字段。

错误

状态	`code`	发生情形
400	`QIT000010`	`limit`、`page` 或日期格式不正确。
400	`ECT000067`	汇总：`date_range_start` 晚于 `date_range_end`。
404	`ECT000005`	基金类别不存在，或您无权访问该基金类别。
404	`ECT000009`	该基金类别中不存在此合同。
404	`ECT000001`	所有基金的列表或汇总：管理人或顾问尚未在合同服务中注册。

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

按 key 查询合同​

路径参数​

响应​

列出基金的合同​

路径参数​

查询参数​

响应​

列出所有基金的合同​

合同汇总​

补充协议历史​

错误​

按 key 查询合同

路径参数

响应

列出基金的合同

路径参数

查询参数

响应

列出所有基金的合同

合同汇总

补充协议历史

错误