跳到主要内容

合并费用文件

为基金类别的某笔费用附加证明文件（发票、计算说明、合同、Boleto），并查询已附加的文件。expense_key 来自合并费用查询。

文件分两步发送：API 先登记文件并返回一个上传 URL；然后由您将文件直接发送到该 URL。

附加文件​

适用范围
角色主机所需权限
管理人manager-api写入

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

ENDPOINT
/expense/fund_class/{fund_class_key}/expense/{expense_key}/document
MÉTODO
POST

Path params​

参数类型描述
fund_class_keystring基金类别的 key（UUID）。
expense_keystring费用的 key（UUID）。

请求体属性​

字段类型是否必填描述
namestring必填文件名称。最多 255 个字符。
document_typestring必填invoice（发票）、calculation_memory（计算说明）、contract（合同）或 bank_slip（Boleto）。

不接受其他任何字段。

Request Body
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "document_type": "invoice"
}

Response​

STATUS
201
Response Body
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "document_type": "invoice",
    "upload_url": {
        "url": "https://<link-temporario-de-envio>",
        "fields": {
            "key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "policy": "<policy>",
            "x-amz-algorithm": "AWS4-HMAC-SHA256",
            "x-amz-credential": "<credential>",
            "x-amz-date": "20260701T120000Z",
            "x-amz-signature": "<signature>"
        }
    }
}
字段类型描述
document_keystring文件的 key（UUID）。之后可用它查询该文件。
expense_keystring文件所属费用的 key。
upload_url.urlstring文件应发送到的地址。
upload_url.fieldsobject必须随文件一起发送的字段。请全部发送，不得修改名称或值；具体字段集合可能有所不同。

发送文件​

向 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 indica upload concluído

如果 URL 在发送前已失效，请重新附加该文件以获取新的 URL。

列出费用的文件​

基金类别中不存在的 expense_key 会返回空的 data，而不是 404。

适用范围
角色主机所需权限
管理人manager-api读取

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

ENDPOINT
/expense/fund_class/{fund_class_key}/expense/{expense_key}/documents
MÉTODO
GET

该列表不分页，也不返回下载 URL；如需下载文件，请按 key 查询该文件。

Response Body
{
    "data": [
        {
            "name": "NF-e 001234 - Auditoria jun/2026",
            "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
            "document_type": "invoice"
        }
    ]
}

按 key 查询文件​

适用范围
角色主机所需权限
管理人manager-api读取

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

ENDPOINT
/expense/fund_class/{fund_class_key}/expense/{expense_key}/document/{document_key}
MÉTODO
GET
Response Body
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "document_type": "invoice",
    "document_url": "https://<link-temporario-de-download>"
}
字段类型描述
document_urlstring用于下载文件的预签名 URL，有效期 24 小时。如需新的 URL，请重新查询该文件。

错误​

状态码代码触发条件
400EXP000069该基金类别不属于您 API 密钥所对应的管理人。
400QIT000001请求体无效：缺少 name 或 document_type，document_type 不在列表中，或包含未定义的字段。
404EXP000072该费用已取消（canceled），不再接受新文件。
404EXP000071该费用下不存在此 document_key。
500QIT000500附加文件：该基金类别中不存在此 expense_key。请在费用查询中核对。

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