供应商签署人组

签署人组定义了在费用合同中由谁代表供应商签署，以及需要多少个签署即可（minimum_required_signers）。

自然人供应商：创建时会自动获得一个以其本人为成员的默认组，每次审核通过时还会获得一个新的默认组。无需申报任何内容。
法人供应商：通常从其审核中获得签署人组，由 QI Tech 根据公司文件推断，或由分析师申报。如需自行申报签署人组，请使用此调用。

通过此调用申报的签署人组以 valid 状态产生，不依赖审核。每个供应商最多只有一个默认组（is_default: true）。

审核通过时：

expiration_date 早于审核通过日期的组不计入，无论是审核自身的组还是默认组：既不会被提升，也不会被复制。
审核中有自身签署人组的法人：该审核的最后一个组成为默认组，原默认组不再是默认组。
审核中没有自身签署人组的法人：当前默认组会被复制为一个与该审核关联的新默认组。
没有任何处于有效期内的组的法人：审核不会通过，停留在人工审核中。

申报签署人组

适用范围

角色	主机	所需权限
管理人	`manager-api`	写入
顾问	`consultant-api`	有效集成

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

ENDPOINT

/vendor_registry/vendor/{vendor_key}/signer_group

方法

POST

路径参数

参数	类型	说明
`vendor_key`	string	供应商的 key（UUID）。

Corpo da requisição
{
    "minimum_required_signers": 1,
    "signers": [
        {
            "name": "João da Silva",
            "document_number": "123.456.789-09",
            "email": "joao.silva@auditoresexemplo.com.br"
        },
        {
            "name": "Maria Souza",
            "document_number": "987.654.321-00",
            "email": "maria.souza@auditoresexemplo.com.br"
        }
    ],
    "is_default": true,
    "expiration_date": "2027-12-31"
}

请求体属性

字段	类型	必填	说明
`minimum_required_signers`	integer	是	需要多少个签署即可。最小为 `1`，最大为 `signers` 的数量。
`signers`	array	是	至少一位签署人。
`signers[].name`	string	是	姓名，1 至 255 个字符。
`signers[].document_number`	string	是	带标点的 CPF（`123.456.789-09`）。必须是供应商某个 `active` 或 `pending_registry` 关联方的 CPF；对于自然人供应商，则为供应商本人的 CPF。`name` 和 `email` 按提交内容保存。
`signers[].is_required_signer`	boolean	否	可以提交，但会被忽略：由 QI Tech 重新计算（参见响应属性）。
`signers[].email`	string	是	邮箱，1 至 255 个字符。
`is_default`	boolean	否	将此组设为默认组，原默认组随之降级。默认值：`false`。供应商的第一个组始终是默认组。
`expiration_date`	string	否	组的有效期，`YYYY-MM-DD`。不得早于当天日期（UTC）（`400`，`VRG000096`）；当天日期本身可以接受。

响应

STATUS

201

Corpo da resposta
{
    "signer_group_key": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
    "minimum_required_signers": 1,
    "is_default": true,
    "signers": [
        {
            "name": "João da Silva",
            "document_number": "123.456.789-09",
            "email": "joao.silva@auditoresexemplo.com.br",
            "is_required_signer": false
        },
        {
            "name": "Maria Souza",
            "document_number": "987.654.321-00",
            "email": "maria.souza@auditoresexemplo.com.br",
            "is_required_signer": false
        }
    ],
    "status": "valid",
    "analysis_key": null,
    "expiration_date": "2027-12-31"
}

响应属性

字段	类型	说明
`signer_group_key`	string	组的 key（UUID）。
`minimum_required_signers`	integer	所需签署数。
`is_default`	boolean	供应商的默认组。
`signers`	array	签署人。`is_required_signer` 由 QI Tech 计算：当签署人数等于最低要求数时，所有人均为 `true`；其他情况下所有人均为 `false`。
`status`	string	通过此调用申报的组为 `valid`。来自审核的组先处于 `pending`，在审核通过时变为 `valid`，在审核被拒绝、取消或撤出队列时变为 `invalid`。
`analysis_key`	string	产生该组的审核；通过此调用申报的组以及自然人供应商创建时自动生成的组为 `null`。
`expiration_date`	string	有效期，`YYYY-MM-DD`。仅在提供时返回。

列出签署人组

适用范围

角色	主机	所需权限
管理人	`manager-api`	读取
顾问	`consultant-api`	有效集成

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

ENDPOINT

/vendor_registry/vendor/{vendor_key}/signer_group

方法

GET

查询参数

参数	类型	必填	说明
`limit`	integer	否	每页条数，`0` 至 `1000`。默认值：`10`。
`page`	integer	否	页码，从 `0` 开始。默认值：`0`。

返回供应商的所有组，包含任意状态，按从旧到新排序。

响应

STATUS

200

Corpo da resposta
{
    "data": [
        {
            "signer_group_key": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
            "minimum_required_signers": 1,
            "is_default": true,
            "signers": [
                {
                    "name": "João da Silva",
                    "document_number": "123.456.789-09",
                    "email": "joao.silva@auditoresexemplo.com.br",
                    "is_required_signer": true
                }
            ],
            "status": "valid",
            "analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

错误

STATUS

400

签署人数不足

signers 中的签署人数少于 minimum_required_signers。

{
  "title": "Signer Group Quorum Not Met",
  "description": "At least 2 signers are required, but only 1 were sent.",
  "translation": "Sao necessarios pelo menos 2 signatarios, mas apenas 1 foram enviados.",
  "code": "VRG000049"
}

有效期早于今天

expiration_date 早于当天日期（UTC）。

{
  "title": "Signer Group Expiration Date In Past",
  "description": "The signer group expiration date (2026-11-08) cannot be earlier than today.",
  "translation": "A data de expiracao do grupo de assinantes (2026-11-08) nao pode ser anterior a hoje.",
  "code": "VRG000096"
}

签署人的 CPF 不属于该供应商

某位签署人的 CPF 既不属于供应商处于 active 或 pending_registry 的关联方，也不属于自然人供应商本人。

{
  "title": "Signer Document Number Not Found",
  "description": "The document number (123.456.789-09) does not match the vendor's own document number or any of its active related parties.",
  "translation": "O numero de documento (123.456.789-09) nao corresponde ao documento do proprio fornecedor nem ao de nenhuma de suas partes relacionadas ativas.",
  "code": "VRG000050"
}

STATUS

404

未找到供应商

该 vendor_key 不存在，或您看不到该供应商。

{
  "title": "Vendor not found",
  "description": "Vendor with the key 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 was not found.",
  "translation": "O fornecedor com a chave 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 nao foi encontrada.",
  "code": "VRG000014"
}

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

下一步

提交审核。

申报签署人组​

路径参数​

请求体属性​

响应​

响应属性​

列出签署人组​

查询参数​

响应​

错误​

下一步​

申报签署人组

路径参数

请求体属性

响应

响应属性

列出签署人组

查询参数

响应

错误

下一步