跳到主要内容

开具银行关系证明函

银行关系证明函（"Declaração de Relacionamento"）是由 QI SCD 数字签名的 PDF 文件，用于证明客户与本机构之间有效的银行关系，并包含账户信息。开具完成后，已签名的文件会通过电子邮件发送至请求中指定的收件人。

Request​

ENDPOINT
/account/ACCOUNT_KEY/ownership_letter
MÉTODO
POST

Path parameters​

字段类型描述
ACCOUNT_KEYUUID需要开具证明函的账户密钥

Body parameters​

字段类型描述最大字符数
emails *string 数组接收已签名 PDF 的电子邮件列表。至少 1 个地址。-
Request Body
{
  "emails": ["contact@customer.com", "finance@customer.com"]
}

Response​

STATUS
200
Response Body
{
  "document_key": "f1b8e3a2-c5d4-4e9f-a1b2-3c4d5e6f7a8b",
  "account_key": "3e4b8746-da58-4799-bcd0-063326428d3f",
  "document_type": "ownership_letter",
  "document_status": "pending",
  "external_identifier_key": "certifiqi-batch-group-key",
  "file_url": "https://api.certifiqi.com.br/events/certifiqi-batch-group-key",
  "payload": {
    "emails": ["contact@customer.com", "finance@customer.com"]
  },
  "created_at": "2026-05-28T19:50:47",
  "updated_at": "2026-05-28T19:50:47"
}

Response Body parameters​

字段类型描述最大字符数
document_keyUUID文档在 QI 内部的唯一标识符。36
account_keyUUID来源账户的密钥。36
document_typestring文档类型。此接口固定为 ownership_letter。-
document_statusstring文档当前状态。参见 document_status 枚举值。-
external_identifier_keystring签名批次的外部标识符。300
file_urlstring文档当前 URL。处于 pending 时指向签名跟踪页面；变为 sent 后指向已签名 PDF。-
payloadobject请求体的回显。-
created_atdatetime Zulu文档创建时间。20
updated_atdatetime Zulu文档最后更新时间。20

document_status 枚举值​

枚举值描述
pending文档已创建，正在等待签名完成。
sent文档已签名，电子邮件已发送给收件人。

获取已签名文档链接​

签名完成后（状态为 sent），使用此接口获取由 CertifIQI 按需生成的、用于下载已签名 PDF 的带时效链接。当文档仍处于 pending 时——即尚未收到签名 webhook——该 URL 尚不存在，接口将返回错误。

Request​

ENDPOINT
/account/ACCOUNT_KEY/document/DOCUMENT_KEY/url
方法
GET

Path parameters​

字段类型描述
ACCOUNT_KEYUUID文档所属账户的密钥。
DOCUMENT_KEYUUID开具信函时返回的文档标识符（document_key）。

Response​

STATUS
200
Response Body
{
  "document_key": "f1b8e3a2-c5d4-4e9f-a1b2-3c4d5e6f7a8b",
  "document_type": "ownership_letter",
  "document_status": "sent",
  "url": "https://api.certifiqi.com.br/expirable/signed_document.pdf?token=abc123"
}

Response Body parameters​

字段类型描述最大字符数
document_keyUUIDQI 内部文档标识符。36
document_typestring文档类型。银行信函为 ownership_letter。-
document_statusstring文档当前状态。仅当为 sent 时才返回 URL。-
urlstring用于下载已签名 PDF 的带时效链接。按需生成，短时间后过期。-

可能的错误​

状态描述
404未找到对应标识符的账户或文档。
409文档仍在签名中（pending）；已签名 URL 尚不可用。