Partes relacionadas do fornecedor

Partes relacionadas são as pessoas ligadas a um fornecedor pessoa jurídica: sócios, administradores, diretores, procuradores e a empresa controladora. Fornecedor pessoa física não tem partes relacionadas (400, VRG000054).

Para enviar a análise, o fornecedor pessoa jurídica precisa de:

• ao menos uma parte relacionada não inativa (pending_registry ou active);
• ao menos uma parte com is_representative: true;
• um documento de identificação para cada representante;
• uma procuração (power_of_attorney) para cada procurador (attorney).

Veja Documentos.

Declare as partes com a análise em preenchimento

Com uma análise em curso, a parte só pode ser criada, alterada, ativada ou desativada em pending_submission. Uma parte criada quando o fornecedor não tem análise em curso não entra sozinha na próxima análise: abra a nova análise primeiro e declare as partes depois. Se a parte já foi criada antes, ela entra na análise em pending_submission quando você altera os dados dela.

Ciclo de vida

Status	Descrição
pending_registry	Declarada, aguardando a aprovação da análise. Também é o status de uma parte reativada.
active	Confirmada na aprovação da análise.
inactive	Desativada pela gestora; descartada na aprovação de uma análise que não a incluía; ou ainda em pending_registry quando a análise foi reprovada.

Tipos de parte relacionada

related_party_type	Descrição
partner	Sócio
administrator	Administrador
director	Diretor
president	Presidente
manager	Gerente
attorney	Procurador. Precisa de documento power_of_attorney próprio.
parent_company	Empresa controladora. Único tipo pessoa jurídica (CNPJ); não pode ser representante.

is_representative é independente do tipo: marca quem representa legalmente o fornecedor e assina por ele.

Declarar parte relacionada

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/related_party

MÉTODO

POST

Parâmetros de caminho

Parâmetro	Tipo	Descrição
vendor_key	string	Chave do fornecedor (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
}

Atributos do corpo

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome, de 1 a 255 caracteres.
related_party_type	string	Sim	Tipo da parte. Ver tipos.
document_number	string	Condicional	CPF (CNPJ para parent_company), com ou sem pontuação, de 11 a 18 caracteres. Obrigatório quando nationality é BRA, quando is_representative é true ou quando o tipo é attorney. Só é validado como CPF (ou CNPJ) quando nationality é BRA. Não pode ser alterado depois.
nationality	string	Não	País no código ISO 3166-1 alpha-3. Padrão: BRA.
passport_number	string	Não	Passaporte, de 1 a 18 caracteres. Identifica a parte estrangeira sem CPF. Não pode ser alterado depois de gravado.
email	string	Condicional	E-mail, máximo de 255 caracteres. Obrigatório quando is_representative é true.
ownership_percentage	number	Não	Participação societária, de 0 a 100, gravada com duas casas decimais.
is_representative	boolean	Não	Representante legal do fornecedor. Padrão: false. parent_company não pode ser representante.

Uma parte estrangeira é identificada por document_number ou por passport_number; ao menos um dos dois é obrigatório. Se já existir uma parte inactive com o mesmo CPF (ou passaporte), ela é reativada na mesma related_party_key com os novos dados.

Resposta

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"
}

Atributos da resposta

Campo	Tipo	Descrição
related_party_key	string	Chave da parte relacionada (UUID). Use nos documentos da parte e nas alterações.
name	string	Nome.
document_number	string	CPF ou CNPJ com pontuação, ou null para estrangeira identificada só por passaporte.
email	string	E-mail, ou null.
related_party_type	string	Tipo da parte.
is_representative	boolean	Representante legal.
ownership_percentage	number	Participação, ou null.
nationality	string	País ISO 3166-1 alpha-3.
passport_number	string	Passaporte, ou null.
status	string	pending_registry, active ou inactive.

Alterar dados da parte relacionada

Altera só os campos enviados; os demais ficam como estão. Exige uma análise em curso, em pending_submission. document_number não pode ser enviado nem alterado.

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

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

MÉTODO

PUT

Corpo da requisição

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

Campos aceitos, todos opcionais e com as mesmas regras da criação: name, related_party_type, nationality, passport_number (só se ainda não gravado), email, ownership_percentage, is_representative.

Resposta

STATUS

200

A parte relacionada atualizada, na mesma estrutura da criação.

Ativar ou desativar parte relacionada

Desativa uma parte que deixou o quadro do fornecedor, ou volta a incluir uma parte desativada. Se houver análise em curso, ela precisa estar em pending_submission.

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

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

MÉTODO

PUT

Corpo da requisição

{
    "status": "inactive"
}

Campo	Tipo	Obrigatório	Descrição
status	string	Sim	inactive ou active. Ver as regras abaixo.

• inactive desativa a parte.
• active reinclui uma parte inactive na análise em preenchimento. Ela volta como pending_registry e só fica active na aprovação.
• A reativação é recusada se o fornecedor já tiver outra parte active ou pending_registry com o mesmo documento ou passaporte (400, VRG000052).
• active enviado para uma parte que já está active ou pending_registry não muda nada: a resposta traz a parte como está.

Resposta

STATUS

200

A parte relacionada, na mesma estrutura da criação. O status vem inactive ou pending_registry, ou inalterado quando active foi enviado para uma parte que não estava inactive.

Erros

STATUS

409

Cadastro já enviado para análise

Há uma análise em curso fora de pending_submission. Na alteração de dados, o erro aparece também quando o fornecedor não tem análise em curso.

{
  "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	Quando acontece
VRG000054	O fornecedor é pessoa física e não pode ter partes relacionadas.
VRG000002	Com nationality BRA, document_number não é um CPF válido (ou CNPJ válido, para parent_company).
VRG000084	nationality não é um código ISO 3166-1 alpha-3.
VRG000085	Parte BRA sem document_number, ou parte estrangeira sem document_number e sem passport_number.
VRG000086	Parte estrangeira sem document_number marcada como representante ou do tipo attorney.
VRG000087	parent_company com is_representative: true.
VRG000052	Já existe uma parte active ou pending_registry com esse documento (ou, sem documento, com esse passaporte) neste fornecedor. Vale também na reativação de uma parte inactive.
VRG000055	Representante sem email.
VRG000092	Você tentou alterar um passport_number já gravado.

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	Quando acontece
VRG000014	A vendor_key não existe ou o fornecedor não é visível para você.
VRG000053	A related_party_key não pertence a este fornecedor.

Erros de autenticação, permissão e host: veja Erros da API.

Próximo passo

Documentos: envie o contrato social e a identificação de cada representante.