跳到主要内容

创建补充协议申请

提交补充协议申请时，需要在请求中使用代表基金的唯一 key（fund_class_key，由 QI Tech 提供）以及代表补充协议流程配置的唯一 key（amendment_configuration_key，由 QI Tech 提供）。

通过该系统办理的补充协议，可以变更付款计划、合同名义利率，或两者同时变更。也可以约定在补充协议生效的同时由债务人支付一笔首付款。

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

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

Request​

ENDPOINT
/asset_amendment/fund_class/FUND_CLASS_KEY/amendment_configuration/AMENDMENT_CONFIGURATION_KEY/asset_amendment
MÉTODO
POST
Request Body
{
    "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "asset_type": "ccb",
    "amendment_date": "2024-04-01",
    "amendment_type": "all_contract",
    "down_payment_value": 400.23,
    "installments": [
        {
            "maturity_date": "2025-01-31",
            "face_value": 1000.31,
            "installment_number": 1
        },
        {
            "maturity_date": "2025-02-28",
            "face_value": 1000.31,
            "installment_number": 2
        }
    ],
    "pre_fixed": {
        "monthly_rate": 0.02,
        "calendar_base": "workdays"
    }
}

Body Params​

字段类型描述必填
asset_external_idstring被补充协议变更的合同的标识，与其纳入投资组合时使用的标识相同。最多 50 个字符。二选一：asset_external_id 或 contract_number
contract_numberstring被变更合同的编号，可替代 asset_external_id。最多 50 个字符。二选一：asset_external_id 或 contract_number
asset_typestring被变更资产的类型：ccb 或 structured_cci是
amendment_datestring办理补充协议的日期（格式：YYYY-MM-DD）是
amendment_typestring要办理的补充协议类型。见补充协议类型枚举值是
down_payment_valuenumber补充协议生效时债务人需支付的首付款金额（大于或等于 0）否
installmentsarray补充协议生效后合同的分期列表取决于 amendment_type
installments[].maturity_datestring分期到期日（格式：YYYY-MM-DD）是
installments[].face_valuenumber分期面值（大于或等于 0）是
installments[].installment_numberinteger分期序号，从 1 开始是
installments[].external_idstring该分期在您系统中的标识否
pre_fixedobject固定利率配置取决于 amendment_type
pre_fixed.monthly_ratenumber适用的月利率是
pre_fixed.calendar_basestring计算所用的日历基准。唯一可接受的值：workdays是
合同标识

在 asset_external_id 和 contract_number 中只能发送一个。两者都不发送时，API 返回 AAM000041；两者都发送时，返回 AAM000042。

Response​

STATUS
201
Response Body
{
    "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
    "status": "pending_document",
    "amendment_type": "all_contract",
    "amendment_configuration": {
        "amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22",
        "fund_class": {
            "fund_class_key": "<fund_class_key>",
            "document_number": "11.222.333/0001-81",
            "name": "FUNDO EXEMPLO FIDC",
            "manager": {
                "manager_key": "<manager_key>",
                "document_number": "22.333.444/0001-81",
                "manager_name": "GESTORA EXEMPLO LTDA"
            },
            "accounting_date": "2024-04-01"
        },
        "requires_document": true
    },
    "asset_type": "ccb",
    "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10",
    "amendment_date": "2024-04-01",
    "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "source": "api_integration",
    "status_history": [
        {
            "status": "pending_document",
            "event_datetime": "2024-04-01T13:02:45Z"
        }
    ]
}

初始状态取决于由 QI Tech 定义的补充协议流程配置：

  • pending_document——流程要求补充协议书（amendment_configuration.requires_document: true，默认）。补充协议只有在发送文件后才会推进。
  • pending_processing——流程不要求文件（requires_document: false）。补充协议直接进入处理。
管理人与要求文件的流程

manager-api 不提供补充协议书的发送功能。如果管理人在要求文件的流程中创建补充协议，该补充协议会停留在 pending_document。解决方法：由与该流程关联的顾问或转让方发送补充协议书，或由管理人通过 integracao.dtvm@qitech.com.br 向 QI Tech 申请一个不要求文件的补充协议流程。


补充协议类型枚举值​

枚举值描述
payment_flow仅变更付款计划
nominal_rate仅变更合同名义利率
all_contract同时变更付款计划和合同名义利率
注意

是否发送 installments 和 pre_fixed 字段取决于补充协议类型，见下表。组合不符时返回 AAM000008。

补充协议类型installmentspre_fixed
all_contract必填必填
nominal_rate不得发送必填
payment_flow必填不得发送

补充协议状态​

状态含义
pending_document等待补充协议书
pending_approval已收到协议书，等待审批
pending_processing处理中
pending_conciliation等待首付款（down_payment_value）计入基金账户
pending_wallet_update正在更新基金投资组合中的合同
completed补充协议已应用到合同
denied补充协议被拒绝；原因见 denial_reason

Webhook​

当补充协议达到 completed 或 denied 时，QI Tech 会向基金管理人以及与该流程关联的转让方和顾问中已配置 webhook 的一方发送 asset_amendment.status_change webhook。配置由 QI Tech 完成：请发送邮件至 integracao.dtvm@qitech.com.br 申请。签名验证参见 Webhook 认证。

Webhook Body
{
    "webhook_type": "asset_amendment.status_change",
    "webhook_datetime": "2024-04-02T10:15:00Z",
    "data": {
        "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
        "amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22",
        "fund_class_key": "<fund_class_key>",
        "fund_class_document_number": "11.222.333/0001-81",
        "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10",
        "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
        "asset_type": "ccb",
        "amendment_type": "all_contract",
        "amendment_date": "2024-04-01",
        "status": "completed",
        "down_payment_value": 400.23
    }
}

down_payment_value 仅在补充协议包含首付款时返回；denial_reason 仅在状态为 denied 时返回。

错误​

状态码代码触发条件
400QIT000001请求体不符合接口契约：缺少必填字段、未知字段、日期无效、值不在枚举范围内
400AAM000041既未发送 asset_external_id，也未发送 contract_number
400AAM000042同时发送了 asset_external_id 和 contract_number
400AAM000008installments/pre_fixed 与 amendment_type 不匹配
404AAM000003不存在使用该 fund_class_key 的基金
404AAM000024未找到该基金的 amendment_configuration_key
404AAM000006asset_type 不存在
404AAM000007基金投资组合中没有与该 asset_external_id 和 asset_type 对应的有效资产
404AAM000043没有与该 contract_number 和 asset_type 对应的有效资产
409AAM000044有多个有效资产使用同一 contract_number：请使用 asset_external_id
4xxWLT... 或 AAM000030基金投资组合在校验时拒绝了该补充协议。代码和描述由投资组合返回；投资组合未返回代码时，返回 AAM000030

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