供应商关联方

关联方是与法人供应商相关的人员：股东、管理人员、董事、代理人和控股公司。自然人供应商没有关联方（400，VRG000054）。

提交审核时，法人供应商需要：

• 至少一个未停用的关联方（pending_registry 或 active）；
• 至少一个 is_representative: true 的关联方；
• 每位代表人一份身份证件；
• 每位代理人（attorney）一份授权委托书（power_of_attorney）。

参见文件。

请在审核填写期间申报关联方

存在进行中的审核时，只有在 pending_submission 状态下才能创建、修改、启用或停用关联方。在供应商没有进行中的审核时创建的关联方，不会自动纳入下一次审核：请先开启新的审核，再申报关联方。如果关联方是此前创建的，在您修改其信息时，它会纳入处于 pending_submission 的审核。

生命周期

状态	说明
pending_registry	已申报，等待审核通过。重新启用的关联方也处于此状态。
active	在审核通过时确认。
inactive	被管理人停用；或在某次未包含它的审核通过时被丢弃；或在审核被拒绝时处于 pending_registry。

关联方类型

related_party_type	说明
partner	股东
administrator	管理人员
director	董事
president	总裁
manager	经理
attorney	代理人。需要有自己的 power_of_attorney 文件。
parent_company	控股公司。唯一的法人类型（CNPJ）；不能作为代表人。

is_representative 与类型无关：它标记的是在法律上代表供应商并为其签署的人员。

申报关联方

适用范围

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

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

ENDPOINT

/vendor_registry/vendor/{vendor_key}/related_party

方法

POST

路径参数

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

Corpo da requisição

{
    "name": "João da Silva",
    "related_party_type": "administrator",
    "document_number": "123.456.789-09",
    "email": "joao.silva@auditoresexemplo.com.br",
    "nationality": "BRA",
    "ownership_percentage": 50.0,
    "is_representative": true
}

请求体属性

字段	类型	必填	说明
name	string	是	姓名，1 至 255 个字符。
related_party_type	string	是	关联方类型。参见类型。
document_number	string	条件必填	CPF（parent_company 为 CNPJ），可带或不带标点，11 至 18 个字符。当 nationality 为 BRA、is_representative 为 true 或类型为 attorney 时必填（满足任一条件即可）。仅当 nationality 为 BRA 时才按 CPF（或 CNPJ）校验。之后不可修改。
nationality	string	否	ISO 3166-1 alpha-3 国家代码。默认值：BRA。
passport_number	string	否	护照号，1 至 18 个字符。用于识别没有 CPF 的外籍关联方。保存后不可修改。
email	string	条件必填	邮箱，最多 255 个字符。当 is_representative 为 true 时必填。
ownership_percentage	number	否	持股比例，0 至 100，按两位小数存储。
is_representative	boolean	否	供应商的法定代表人。默认值：false。parent_company 不能作为代表人。

外籍关联方通过 document_number 或 passport_number 识别；两者至少需要提供一个。如果已存在具有相同 CPF（或护照号）的 inactive 关联方，该关联方会以新的信息在同一个 related_party_key 下重新启用。

响应

STATUS

201

Corpo da resposta

{
    "related_party_key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "João da Silva",
    "document_number": "123.456.789-09",
    "email": "joao.silva@auditoresexemplo.com.br",
    "related_party_type": "administrator",
    "is_representative": true,
    "ownership_percentage": 50.0,
    "nationality": "BRA",
    "passport_number": null,
    "status": "pending_registry"
}

响应属性

字段	类型	说明
related_party_key	string	关联方的 key（UUID）。用于关联方的文件和修改操作。
name	string	姓名。
document_number	string	带标点的 CPF 或 CNPJ；仅通过护照识别的外籍关联方为 null。
email	string	邮箱，或 null。
related_party_type	string	关联方类型。
is_representative	boolean	法定代表人。
ownership_percentage	number	持股比例，或 null。
nationality	string	ISO 3166-1 alpha-3 国家代码。
passport_number	string	护照号，或 null。
status	string	pending_registry、active 或 inactive。

修改关联方信息

仅修改提交的字段；其他字段保持不变。要求存在处于 pending_submission 的进行中审核。document_number 不可提交，也不可修改。

适用范围

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

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

ENDPOINT

/vendor_registry/vendor/{vendor_key}/related_party/{related_party_key}/data

方法

PUT

Corpo da requisição

{
    "email": "joao.silva@auditoresexemplo.com.br",
    "ownership_percentage": 60.0
}

接受的字段均为可选，规则与创建时相同：name、related_party_type、nationality、passport_number（仅在尚未保存时）、email、ownership_percentage、is_representative。

响应

STATUS

200

返回更新后的关联方，结构与创建相同。

启用或停用关联方

停用已退出供应商组织架构的关联方，或重新纳入已停用的关联方。如有进行中的审核，该审核必须处于 pending_submission。

适用范围

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

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

ENDPOINT

/vendor_registry/vendor/{vendor_key}/related_party/{related_party_key}

方法

PUT

Corpo da requisição

{
    "status": "inactive"
}

字段	类型	必填	说明
status	string	是	inactive 或 active。规则见下方。

• inactive 停用该关联方。
• active 将处于 inactive 的关联方重新纳入填写中的审核。它会回到 pending_registry，只有在审核通过时才变为 active。
• 如果该供应商已有另一个使用相同证件号或护照号的 active 或 pending_registry 关联方，重新启用会被拒绝（400，VRG000052）。
• 对已为 active 或 pending_registry 的关联方提交 active 时，不做任何变更：响应按原样返回该关联方。

响应

STATUS

200

返回关联方，结构与创建相同。status 为 inactive 或 pending_registry；对不处于 inactive 的关联方提交 active 时，status 保持不变。

错误

STATUS

409

登记已提交审核

存在进行中的审核，但不处于 pending_submission。修改信息时，如果供应商没有进行中的审核，也会返回此错误。

{
  "title": "Vendor Registration Already Submitted",
  "description": "The current analysis of the vendor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 is no longer pending submission, so the registration cannot be edited.",
  "translation": "Cadastro ja enviado para analise.",
  "code": "VRG000072"
}

STATUS

400

code	发生情形
VRG000054	供应商为自然人，不能有关联方。
VRG000002	nationality 为 BRA 时，document_number 不是有效的 CPF（parent_company 则为有效的 CNPJ）。
VRG000084	nationality 不是 ISO 3166-1 alpha-3 代码。
VRG000085	BRA 关联方没有 document_number，或外籍关联方既没有 document_number 也没有 passport_number。
VRG000086	没有 document_number 的外籍关联方被标记为代表人或类型为 attorney。
VRG000087	parent_company 设置了 is_representative: true。
VRG000052	该供应商中已存在使用此证件号（或无证件号时使用此护照号）的 active 或 pending_registry 关联方。重新启用 inactive 关联方时同样适用。
VRG000055	代表人没有 email。
VRG000092	您尝试修改已保存的 passport_number。

Exemplo

{
  "title": "Related Party Email Required",
  "description": "A related party of type administrator must declare an email.",
  "translation": "Uma parte relacionada do tipo administrator precisa declarar um e-mail.",
  "code": "VRG000055"
}

STATUS

404

code	发生情形
VRG000014	该 vendor_key 不存在，或您看不到该供应商。
VRG000053	该 related_party_key 不属于此供应商。

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

下一步

文件：上传公司章程（contrato social）和每位代表人的身份证件。