转让文件

关于转让协议书的三项查询：批次协议书的链接、某一基金类别的协议书列表，以及电子签署链接。

转让协议书链接

获取转让协议书的下载链接——包括原始版本和已签署版本。该端点自协议书生成之时起可用；在此之前返回 TRC000099。

适用范围

角色	主机	所需权限
管理人	`manager-api`	读取
顾问	`consultant-api`	View Assignments
转让方	`assignor-api`	读取

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

适用场景

收到状态为 pending_assignment_term_signature 的 webhook 后，可使用该端点获取转让协议书的链接，并跟踪签署是否已完成。

Request

ENDPOINT

/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assignment_term_link

MÉTODO

GET

Path params

参数	类型	描述
`fund_class_key`	string	基金的唯一 key（UUID）。
`assignment_configuration_key`	string	转让配置的 key（UUID）。
`assignment_external_id`	string	创建批次时提供的 `external_id`。

Response

STATUS

200

Response Body
{
    "assignment_term_url": "https://storage.example.com/term/abc123.pdf",
    "signed_assignment_term_url": "https://storage.example.com/term/abc123_signed.pdf"
}

响应属性

字段	类型	描述
`assignment_term_url`	string	用于下载协议书的 URL。
`signed_assignment_term_url`	string	用于下载已签署转让协议书的预签名 URL。只有在各方全部签署后，文件才可用。

说明

两个 URL 均为预签名 URL，1 小时后失效。再次调用该端点即可生成新的链接。

signed_assignment_term_url 字段始终返回，但只有在转让协议书由所有相关方签署后，文件才存在。在此之前，访问该 URL 会返回错误。签署完成后，批次根据转让配置进入 pending_payment（发送 webhook）或 pending_custody（不发送 webhook）。后一种情况请通过批次查询跟踪。

转让协议书列表

分页查询端点，返回某一基金类别下各批次的转让协议书，并提供原始协议书和已签署协议书的预签名下载链接。可使用筛选条件按转让日期、时间段、状态或特定批次查找协议书。

适用范围

角色	主机	所需权限
管理人	`manager-api`	读取
顾问	`consultant-api`	View Assignments

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

按基金类别的端点

与批次列表一样，该端点的 URL 中只使用 fund_class_key——无需提供 assignment_configuration_key。如需获取特定批次的协议书，请以该批次的 external_id 作为筛选条件。

只返回已生成转让协议书、且属于已认证代理方（与该基金类别关联的管理人或顾问）的批次。

Request

ENDPOINT

/trade_receivables/fund_class/{fund_class_key}/assignment_terms

MÉTODO

GET

Path params

参数	类型	描述
`fund_class_key`	string	基金的唯一 key（UUID）。

Query params

参数	类型	是否必填	描述
`assignment_date`	string	可选	按转让日期筛选，格式为 `YYYY-MM-DD`。
`start_date`	string	可选	返回转让日期等于或晚于所指定日期的批次，格式为 `YYYY-MM-DD`。
`end_date`	string	可选	返回转让日期等于或早于所指定日期的批次，格式为 `YYYY-MM-DD`。
`external_id`	string	可选	按创建批次时提供的 `external_id` 筛选。
`assignment_key`	string	可选	按批次的 key（UUID）筛选。
`assignment_status`	string	可选	按批次的特定状态筛选。
`in_status`	string	可选	以逗号分隔的状态列表。只返回处于其中某一状态的批次。
`not_in_status`	string	可选	以逗号分隔的状态列表。排除处于这些状态的批次。
`assignor_document_number`	string	可选	按转让方的证件号（CPF/CNPJ）筛选。必须带标点发送（例如：`11.222.333/0001-81` 或 `969.698.790-03`）。
`origin_type`	string	可选	按批次来源筛选（例如：`client`）。
`page`	integer	可选	页码（从 0 开始）。默认：`0`。
`limit`	integer	可选	每页记录数。默认：`25`。最大：`155`。

调用示例——某一日期的协议书
GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms?assignment_date=2024-04-01&page=0&limit=25

调用示例——按 external_id 查询某一批次的协议书
GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms?external_id=931e9437-d025-41ab-bb53-6b94e10fd361

Response

STATUS

200

Response Body
{
  "data": [
    {
      "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
      "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
      "name": "CESSÃO #12345",
      "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
      "assignment_number": "00012345",
      "assignment_date": "2024-04-01",
      "status": "completed",
      "assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "assignment_term_url": "https://storage.example.com/term/abc123.pdf",
      "signed_assignment_term_url": "https://storage.example.com/term/abc123_signed.pdf"
    }
  ],
  "limit": 25,
  "page": 0,
  "is_last_page": true
}

响应属性

字段	类型	描述
`data`	array	转让协议书列表。见下表。
`page`	integer	当前页码。
`limit`	integer	每页记录数。
`is_last_page`	boolean	指示是否为结果的最后一页。

每份协议书的属性（data 中的对象）

字段	类型	描述
`assignment_key`	string	批次的唯一标识（UUID）。
`external_id`	string	合作伙伴提供的外部 key。
`name`	string	转让的标识名称。
`assignment_configuration_key`	string	批次所属转让配置的 key（UUID）。
`assignment_number`	string	转让批次编号。
`assignment_date`	string	转让日期，格式为 `YYYY-MM-DD`。
`status`	string	批次当前状态。参见批次状态枚举值。
`assignment_term_key`	string	转让协议书的 key（UUID）。
`assignment_term_url`	string	用于下载原始转让协议书的预签名 URL。
`signed_assignment_term_url`	string	用于下载已签署转让协议书的预签名 URL。只有在各方全部签署后，文件才可用。

说明

这些 URL 均为预签名 URL，1 小时后失效。如需获取新的链接，请再次调用该端点。

批次按从新到旧排列。尚未生成转让协议书的批次不会出现在列表中。

签署链接

获取访问 CertifiQI 中转让协议书签署界面的链接，以及批次信息和文件下载链接。该端点自协议书生成之时起可用。当签署通过 QCertifica 进行，或转让配置无需签署时不可用（TRC000131）。

适用范围

角色	主机	所需权限
顾问	`consultant-api`	View Assignments

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

Request

ENDPOINT

/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assignment_signature_url

MÉTODO

GET

Path params

参数	类型	描述
`fund_class_key`	string	基金的唯一 key（UUID）。
`assignment_configuration_key`	string	转让配置的 key（UUID）。
`assignment_external_id`	string	创建批次时提供的 `external_id`。

Response

STATUS

200

Response Body
{
    "batches": [
        {
            "name": "Termo de Cessão - Lote 001",
            "document_type": "assignment_term",
            "status": "pending",
            "document_key": "doc-uuid-example",
            "related_parties": []
        }
    ],
    "signature_url": "https://certifiqi.com/events/{external_batch_group_key}",
    "download_url": "https://storage.example.com/term/abc123.pdf"
}

响应属性

字段	类型	描述
`batches`	array	与转让协议书关联的批次列表。
`batches[].name`	string	批次名称。
`batches[].document_type`	string	文件类型（例如：`assignment_term`、`duplicata`）。
`batches[].status`	string	该批次当前的签署状态。
`batches[].document_key`	string	文件的标识 key。
`batches[].related_parties`	array	参与该批次签署的各方。
`signature_url`	string	访问 CertifiQI 签署界面的 URL。
`download_url`	string	用于下载转让协议书的预签名 URL。

说明

当批次处于 pending_send_to_signature 或 pending_assignment_term_signature 时，download_url 字段指向原始（未签署）文件。各方全部签署后，改为指向已签署的转让协议书。该 URL 为预签名 URL，1 小时后失效。

错误

状态码	代码	端点	触发条件
400	`TRC000099`	协议书链接、签署链接	该批次的转让协议书尚未生成。
400	`TRC000131`	签署链接	该转让配置不使用带链接的电子签署（例如通过 QCertifica 签署或无需签署），或链接尚不可用。
400	—	协议书列表	`limit` 超过 155 或 `page` 为负数（参数校验）。
404	`TRC000018`	协议书链接、签署链接	该转让配置中没有使用此 `external_id` 的批次。

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

转让协议书链接​

Request​

Path params​

Response​

响应属性​

转让协议书列表​

Request​

Path params​

Query params​

Response​

响应属性​

签署链接​

Request​

Path params​

Response​

响应属性​

错误​

转让协议书链接

Request

Path params

Response

响应属性

转让协议书列表

Request

Path params

Query params

Response

响应属性

签署链接

Request

Path params

Response

响应属性

错误