跳到主要内容

创建付款批次

这是资产清算流程的第一步。创建付款批次会预留一个分组，后续步骤中待处理的清算都将插入该分组。

适用范围
角色主机所需权限
管理人manager-api写入
顾问consultant-apiCreate Batches
转让方assignor-api写入

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

前提条件

创建批次前，您需要准备好 fund_class_key——即资产将在其中清算的基金的唯一 key。该 key 是整个 API 所用端点的组成部分：

/settlement/fund_class/{fund_class_key}

完整流程的更多详情，参见简介页面。

注意

每个批次在同一基金内都必须拥有唯一的 external_id。

如发生错误，请重发请求。重复（SET000009）表示该批次已存在：请通过批次查询获取它，而不是重新创建。参见重发与重复。

Request​

ENDPOINT
/settlement/fund_class/{fund_class_key}/payment_batch
MÉTODO
POST
Request Body
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "account": {
        "account_number": "123456",
        "account_digit": "0",
        "account_branch": "0001",
        "financial_institution_code": "329"
    }
}

请求体属性​

字段类型是否必填描述
external_idstring必填该批次在集成合作伙伴系统中的唯一标识 key。最多 50 个字符。
descriptionstring可选清算批次的描述。最多 255 个字符。
accountobject可选清算入账账户的数据。未提供时，清算将在基金主账户中生成。参见 account 属性。
account_keystring可选清算入账账户的 key（UUID，36 个字符）。可替代 account 字段。
reference_datestring可选批次的参考日期，格式为 YYYY-MM-DD。省略时为当前日期（巴西利亚时间）。不得早于基金当前的会计日期。
end_to_end_idstring可选清算资金交易对手 Pix 的 end-to-end 标识（32 个字符，以 E 开头）。
source_document_numberstring可选清算资金交易对手的 CPF 或 CNPJ，带标点（例如：11.222.333/0001-81 或 969.698.790-03）。省略时，可能由基金清算配置中的默认证件号填充。
settlement_expensesarray可选在批次中扣除的清算费用，每种类型最多一项。参见 settlement_expenses 属性。
注意

account 和 account_key 字段不得同时传入（SET000034）。两者都未提供时，清算将在基金主账户中生成。该账户必须属于该基金，或以该基金为授权代理方（SET000032）。

account 属性​

字段类型是否必填描述
account_numberstring必填账号。最多 20 个字符。
account_digitstring必填账户校验位。1 个字符。
account_branchstring必填账户所属分行。最多 4 个字符。
financial_institution_codestring必填金融机构代码。最多 20 个字符。

settlement_expenses 属性​

字段类型是否必填描述
amountnumber必填费用金额。
expense_typestring必填bank_account（银行费用）或 collection_agent_fee（收款代理费）。
descriptionstring可选费用描述。最多 255 个字符。

Response​

STATUS
201
Response Body
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
        "manager": {
            "name": "EXEMPLO CAPITAL",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "22.333.444/0001-81"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "11.222.333/0001-81",
        "accounting_date": "2025-01-01",
        "payment_batch_automatic_discard": false
    },
    "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b",
    "status": "pending_settlements_insertion",
    "reference_date": "2025-01-01",
    "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
}

响应属性​

字段类型描述
external_idstring与请求中提供的外部 key 相同。
descriptionstring批次描述。
fund_classobject与批次关联的基金数据。参见 fund_class 属性。
payment_batch_keystringQI Tech 生成的批次唯一标识（UUID）。
statusstring批次的初始状态。始终返回 pending_settlements_insertion，表示批次已可接收清算。
reference_datestring批次的参考日期，格式为 YYYY-MM-DD。
account_keystring与批次关联的账户 key（UUID）。
settlement_expensesarray已创建的清算费用，包含 settlement_expense_key、amount、status、description 和 type。仅在提供时返回。

响应还会回显请求体中发送的其他字段（例如 account、source_document_number、end_to_end_id）。

fund_class 属性​

字段类型描述
namestring基金名称。
managerobject基金管理人的数据。参见 manager 属性。
fund_class_keystring基金的唯一 key（UUID）。
document_numberstring基金的 CNPJ。
accounting_datestring基金当前的会计日期，格式为 YYYY-MM-DD。
payment_batch_automatic_discardboolean指示该基金是否会自动废弃未关闭的批次。

manager 属性​

字段类型描述
namestring管理人名称。
manager_keystring管理人的唯一 key（UUID）。
document_numberstring管理人的 CNPJ。

后续步骤​

创建批次后，流程继续：

  1. 插入清算——将清算（分期付款、摊销等）添加到批次中。
  2. 关闭批次——表明所有清算均已插入，以便开始处理。

错误​

状态码代码触发条件
409SET000009该基金中已存在使用此 external_id 的批次。请查询该批次，而不是重新创建。
404SET000005该 fund_class_key 不存在。
403SET000028该基金不属于您的角色（基金的管理人、关联的顾问或相关的转让方）。
400SET000044reference_date 早于基金当前的会计日期。
404SET000031未找到所提供的账户（account_key 或 account）。
400SET000032所提供的账户不属于该基金。
400SET000034同时发送了 account 和 account_key。
403SET000085该 escrow 账户未获授权为此基金操作。
400SET000001source_document_number 不是有效的 CPF/CNPJ。
400SET000050 / SET000051expense_type 无效，或同一类型的费用超过一项。
400QIT000001请求体无效（缺少必填字段、格式无效或包含不接受的字段）。

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