创建供应商

根据 CPF 或 CNPJ 及名称创建供应商，并以 pending_submission 状态开启第一次登记审核。响应返回的是审核，而不是供应商：请保存 analysis_key 用于后续步骤，并保存 vendor.vendor_key 用于识别供应商。

人员类型由证件号决定：CPF 创建 natural_person；CNPJ 创建 legal_person。

如需续期或修正已存在的供应商，请使用开启新的审核。

创建供应商

适用范围

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

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

ENDPOINT

/vendor_registry/vendor

方法

POST

Corpo da requisição
{
    "document_number": "44.555.666/0001-81",
    "name": "AUDITORES EXEMPLO S.A.",
    "email": "contato@auditoresexemplo.com.br"
}

请求体属性

字段	类型	必填	说明
`document_number`	string	是	供应商的 CPF 或 CNPJ，可带或不带标点。11 至 18 个字符。接受字母数字 CNPJ。
`name`	string	是	姓名或公司名称。最多 255 个字符。
`email`	string	否	供应商的邮箱。最多 255 个字符。可稍后在登记信息中提供；提交审核时为必填项。
`person_type`	string	否	`natural_person` 或 `legal_person`。如提供，必须与证件号一致。

不接受其他任何字段。

响应

STATUS

201

Corpo da resposta
{
    "analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
    "analysis_number": 1,
    "agent": {
        "agent_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
        "agent_type": "manager",
        "name": "EXEMPLO GESTORA LTDA",
        "document_number": "22.333.444/0001-81"
    },
    "status": "pending_submission",
    "reproval_reason": null,
    "reproval_details": null,
    "last_updated": "2026-11-09 14:03:21.123456+00:00",
    "signer_groups": [],
    "vendor": {
        "vendor_key": "5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "44.555.666/0001-81",
        "email": "contato@auditoresexemplo.com.br",
        "address": null,
        "person_type": "legal_person",
        "status": "pending_analysis",
        "block_reason": null,
        "expiration_date": null,
        "agents": [
            {
                "agent_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                "agent_type": "manager",
                "name": "EXEMPLO GESTORA LTDA",
                "document_number": "22.333.444/0001-81",
                "permission_type": "owner"
            }
        ],
        "related_parties": [],
        "bank_accounts": [],
        "signer_groups": [],
        "last_analysis": {
            "analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
            "analysis_number": 1,
            "status": "pending_submission",
            "analysis_related_parties": [],
            "documents": [],
            "annotations": [],
            "last_updated": "2026-11-09 14:03:21.123456+00:00",
            "reproval_reason": null,
            "reproval_details": null,
            "signer_groups": []
        }
    },
    "analysis_data": {
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "44.555.666/0001-81",
        "email": "contato@auditoresexemplo.com.br",
        "address": null,
        "ai_pending_reasons": null,
        "ai_pending_reason_details": null
    },
    "related_parties": [],
    "annotations": []
}

响应属性

字段	类型	说明
`analysis_key`	string	审核的 key（UUID）。用于登记信息、文件、提交和取消等调用。
`analysis_number`	integer	该供应商下审核的顺序编号，从 `1` 开始。
`agent`	object	拥有该供应商的主体（管理人或顾问）：`agent_key`、`agent_type`（`manager` 或 `consultant`）、`name`、`document_number`。
`status`	string	审核状态。创建时始终为 `pending_submission`。参见审核状态。
`reproval_reason`	string	拒绝原因，或 `null`。
`reproval_details`	string	拒绝详情，或 `null`。
`last_updated`	string	审核的最后修改时间。
`signer_groups`	array	与该审核关联的签署人组。参见签署人组。
`vendor`	object	完整的供应商信息。参见供应商属性。
`analysis_data`	object	该审核中正在填写的信息：`name`、`document_number`、`email`、`address`（参见登记信息）、`ai_pending_reasons` 和 `ai_pending_reason_details`（自动校验指出的待处理事项，或 `null`）。
`related_parties`	array	与该审核关联的关联方。参见关联方。
`annotations`	array	该审核的审核意见。参见审核意见。

ai_pending_reasons 的可能取值：signer_not_identified、signature_rule_unclear、signer_contradiction_between_documents、mandate_expired_or_undated、societary_amendment_not_provided、company_document_mismatch、company_identification_unconfirmed、societary_data_incomplete、document_illegible。ai_pending_reason_details 给出每项对应的葡萄牙语说明。

开启新的审核

为已存在的供应商开启下一次审核。适用于：

续期处于 active 或 expired 的供应商；
修正最近一次审核因登记类原因被拒绝（reproved）或已取消（canceled）的登记。

新审核以 pending_submission 状态产生，并复制上一次审核的以下内容：

登记信息；
处于 valid 或 in_manual_analysis 的文件；
未停用的关联方，每个关联方连同其处于上述状态的文件。

登记类拒绝时，尚未确认的关联方（pending_registry）变为 inactive，审核中的文件变为 invalid，且新审核不会复制它们。被拒绝后，请重新启用关联方，并重新提交变为 invalid 的文件。除此之外，只需修改有变化的内容后提交。

适用范围

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

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

ENDPOINT

/vendor_registry/vendor/{vendor_key}/analysis

方法

POST

路径参数

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

此调用不带请求体。请求体中包含任何字段都会返回 400（QIT000001）。

响应

STATUS

201

响应为新的审核，结构与创建供应商相同，analysis_number 递增。处于 active 或 expired 的供应商在新审核期间保持原状态；从未通过审核的供应商为 pending_analysis。

错误

创建供应商

STATUS

409

管理人已登记该供应商

您已能访问使用该 CPF 或 CNPJ 的供应商：可能是您自己创建的、通过顾问的合同看到的，或代表您所属管理人自身、在其登记到服务时自动创建的供应商。响应会返回已有供应商的 vendor_key 和 document_number：请使用该供应商，而不要再创建一个。

{
  "title": "Agent Already Registered Vendor",
  "description": "The selected agent has already registered a vendor with the document number 44.555.666/0001-81.",
  "translation": "O agente selecionado ja registrou um fornecedor com o documento 44.555.666/0001-81.",
  "code": "VRG000015",
  "vendor_key": "5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57",
  "document_number": "44.555.666/0001-81"
}

STATUS

400

证件号无效

document_number 既不是有效的 CPF 也不是有效的 CNPJ，或者 person_type 与证件号不符。

{
  "title": "Invalid document number",
  "description": "The document number 44.555.666/0001-00 is invalid.",
  "translation": "O documento 44.555.666/0001-00 e invalido.",
  "code": "VRG000002"
}

STATUS

404

管理人未在服务中登记

您所属的管理人尚未在供应商服务中登记。请联系 integracao.dtvm@qitech.com.br。

{
  "title": "Agent not found",
  "description": "Agent with the key a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c was not found.",
  "translation": "O agente com a chave a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c nao foi encontrado.",
  "code": "VRG000043"
}

开启新的审核

STATUS

409

已有一个填写中的审核

该供应商已有一个处于 pending_submission 的审核。请先提交或取消该审核，再开启新的审核。

{
  "title": "Vendor Analysis Already Open",
  "description": "The vendor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 already has an analysis pending submission; a new analysis can only be opened after the current one ends.",
  "translation": "Este fornecedor ja tem um cadastro em preenchimento. Envie ou cancele o cadastro atual antes de abrir uma nova analise.",
  "code": "VRG000106"
}

登记正在 QI Tech 审核中

当前审核处于 sent_to_analysis、in_manual_analysis 或 in_compliance_analysis。请等待审核结果，或取消审核。

{
  "title": "Vendor Registration Under Analysis",
  "description": "The registration of the vendor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 is under analysis by QI Tech and cannot be changed until the analysis ends.",
  "translation": "O cadastro deste fornecedor esta em analise pela QI Tech e nao pode ser alterado ate a analise terminar.",
  "code": "VRG000104"
}

STATUS

403

供应商被合规部门拒绝

合规部门已最终拒绝该供应商（compliance_reproval）。该供应商处于 inactive，不再接受新的审核。

{
  "title": "Vendor Definitively Reproved",
  "description": "The vendor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 was definitively reproved by compliance and cannot open a new analysis.",
  "translation": "O fornecedor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 foi reprovado definitivamente pelo compliance e nao pode abrir uma nova analise.",
  "code": "VRG000063"
}

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 错误。

下一步

登记信息：提交供应商的邮箱和地址。

创建供应商​

请求体属性​

响应​

响应属性​

开启新的审核​

路径参数​

响应​

错误​

创建供应商​

开启新的审核​

下一步​

创建供应商

请求体属性

响应

响应属性

开启新的审核

路径参数

响应

错误

创建供应商

开启新的审核

下一步