费用文件

为基金费用附加发票、计算说明及其他凭证，并列出、下载或取消已附加的文件。expense_key 来自查询费用。用于合并费用的发票应附加在合并分析中：提交发票时只考虑该分析的文件。

附加方式取决于费用的来源（origin.origin_type）：

来源	附加方式	谁可以附加、何时
由管理人或顾问录入（`expense_contract`、`expense`、`reimbursement`、`rebate_fee`）	在请求体中以 Base64 提供文件（`document_b64`）。	仅录入该费用的一方（`permission_type: owner`），且费用处于 `pending_submission` 或 `pre_approved`、合并分析不在复核中。
由 QI Tech 计算或登记（其他来源）	在请求体中以 Base64 提供文件，或分两步上传：API 登记文件并返回上传 URL，然后您将文件直接上传到该 URL。	仅管理人，且不接受 `canceled` 的费用。

顾问可以为自己录入的费用附加和取消文件。费用文件的列表和下载仅对管理人开放：顾问可在费用查询结果的 documents 中查看文件，并下载合并分析的文件。

文件类型

`document_type`	描述
`invoice`	发票
`calculation_memory`	计算说明
`contract`	合同
`bank_slip`	Boleto
`payment_receipt`	付款凭证
`evidence`	证明材料
`settlement_term`	结清确认书
`variance_justification`	金额差异说明
`extra_document`	补充文件

文件状态

状态	描述
`in_manual_analysis`	已以 Base64 发送，等待 QI Tech 审核。
`valid`	在费用或分析获批时被接受。
`invalid`	被 QI Tech 拒绝。
`canceled`	已取消。
`null`	通过两步上传登记。

附加文件

适用范围

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

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

ENDPOINT

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

方法

POST

路径参数

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

Corpo da requisição — arquivo em Base64
{
    "name": "nfe_001234.pdf",
    "document_type": "invoice",
    "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..."
}

Corpo da requisição — envio em duas etapas
{
    "name": "nfe_001234.pdf",
    "document_type": "invoice"
}

请求体属性

字段	类型	是否必填	描述
`name`	string	是	文件名称，最多 255 个字符。
`document_type`	string	是	文件类型。参见类型。
`document_b64`	string	条件必填	Base64 格式的文件内容，最大 20 MB。由管理人或顾问录入的费用必填。不提供时，API 返回两步上传的 URL。

不接受其他任何字段。

响应

STATUS

201

Corpo da resposta — arquivo em Base64
{
    "name": "nfe_001234.pdf",
    "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
    "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
    "document_type": "invoice",
    "status": "in_manual_analysis"
}

Corpo da resposta — envio em duas etapas
{
    "name": "nfe_001234.pdf",
    "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
    "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "document_type": "invoice",
    "status": null,
    "upload_url": {
        "url": "https://<link-temporario-de-envio>",
        "fields": {
            "key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
            "policy": "<policy>",
            "x-amz-algorithm": "AWS4-HMAC-SHA256",
            "x-amz-credential": "<credential>",
            "x-amz-date": "20261109T120000Z",
            "x-amz-signature": "<signature>"
        }
    }
}

字段	类型	描述
`name`	string	文件名称。
`document_key`	string	文件的 key（UUID）。
`expense_key`	string	费用的 key。
`document_type`	string	文件类型。
`status`	string	以 Base64 发送时为 `in_manual_analysis`；两步上传时为 `null`。
`upload_url.url`	string	仅限两步上传：文件应上传到的地址。
`upload_url.fields`	object	仅限两步上传：随文件一起提交的字段。请全部发送，不要修改名称或值；具体字段集合可能会变化。

两步上传文件

向 upload_url.url 发起 multipart/form-data 格式的 POST，包含：

upload_url.fields 中的所有字段；
file 字段中的文件，作为表单的最后一个字段。

该 URL 在 10 分钟后过期，接受最大 50 MB 的文件。此调用直接发送到存储服务，不携带 QI Tech 的认证请求头。

import requests

upload = response_body["upload_url"]

with open("nfe_001234.pdf", "rb") as arquivo:
    resposta = requests.post(
        upload["url"],
        data=upload["fields"],
        files={"file": arquivo},
    )

resposta.raise_for_status()

返回 204 表示上传完成。如果 URL 在上传前过期，请重新附加该文件以获取新的 URL。

列出文件

返回该费用的所有文件，包含任意状态，不含下载 URL，且不分页。基金类别中不存在的 expense_key 会返回空的 data，不报错。

适用范围

角色	主机	所需权限
管理人	`manager-api`	读取

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

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/documents

方法

GET

Corpo da resposta
{
    "data": [
        {
            "name": "nfe_001234.pdf",
            "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
            "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
            "document_type": "invoice",
            "status": "in_manual_analysis"
        }
    ]
}

按 key 查询文件

返回该文件，并附带用于下载文件的临时链接。

适用范围

角色	主机	所需权限
管理人	`manager-api`	读取

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

ENDPOINT

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

方法

GET

Corpo da resposta
{
    "name": "nfe_001234.pdf",
    "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
    "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
    "document_type": "invoice",
    "status": "valid",
    "document_url": "https://<link-temporario-de-download>"
}

字段	类型	描述
`document_url`	string	用于下载文件的预签名 URL，有效期 24 小时。无论上传时是何种格式，文件都以 `application/pdf` 提供。如需新的 URL，请重新查询。

取消文件

将您（管理人或顾问，permission_type: owner）录入的费用中的某个文件标记为 canceled。适用于费用处于 pending_submission 或 pre_approved，且合并分析不在复核中的情形。

适用范围

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

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

ENDPOINT

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

方法

DELETE

STATUS

200

返回 status: canceled 的文件，结构与列表相同。

错误

状态	`code`	发生情形
400	`EXP000069`	该基金类别不属于该管理人。
400	`EXP000072`	附加时：该费用由管理人或顾问录入，且既不处于 `pending_submission`，也不处于 `pre_approved`。
400	`EXP000166`	当前有效的合并分析正在复核中（`in_manual_analysis` 或 `pending_manager_approval`）。
400	`EXP000136`	`document_b64` 不是有效的 Base64，或在管理人或顾问录入的费用中被省略。
400	`EXP000137`	文件超过 20 MB。
400	`EXP000144`	取消时：该费用既不处于 `pending_submission`，也不处于 `pre_approved`。
400	`QIT000001`	请求体无效：缺少 `name` 或 `document_type`、`document_type` 不在允许列表中，或包含未定义的字段。
400	`QIT000011`	顾问尝试为 QI Tech 计算的费用附加文件。
403	`EXP000124`	顾问与该基金没有有效关联。通常 `consultant-api` 会先以 `401`（`CIT000018`）拒绝。
403	`EXP000156`	该费用不是由您录入的（`permission_type` 不是 `owner`）。取消文件时，QI Tech 计算的费用也适用。
404	`EXP000010`	该 `expense_key` 在此基金类别中不存在（附加和取消时）。
404	`EXP000072`	附加时：该费用由 QI Tech 计算，且状态为 `canceled`。
404	`EXP000071`	该 `document_key` 在此费用中不存在。

Exemplo
{
  "title": "Invalid Status For Expense Document",
  "description": "Cannot create an expense document on an expense in status in_provision.",
  "translation": "Nao e possivel criar um documento em uma despesa no status in_provision.",
  "code": "EXP000072"
}

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

文件类型​

文件状态​

附加文件​

路径参数​

请求体属性​

响应​

两步上传文件​

列出文件​

按 key 查询文件​

取消文件​

错误​

文件类型

文件状态

附加文件

路径参数

请求体属性

响应

两步上传文件

列出文件

按 key 查询文件

取消文件

错误