Documentos e Endereços
Como gerenciar documentos e endereços de submerchants
Sócios e Representantes Legais (PJ)
Submerchants do tipo Pessoa Jurídica (PJ) podem ter um ou mais sócios/representantes legais cadastrados, espelhando o fluxo de onboarding de merchant.
Campos do Sócio
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome completo do sócio (ou nome do responsável, se PJ) |
document | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos) — chave de idempotência |
entity_type | "pf" | "pj" | Não | Tipo do sócio. Default pf |
legal_name | string | Não | Razão social, quando o sócio é PJ |
birth_date | string | Não | Data de nascimento (YYYY-MM-DD) |
mother_name | string | Não | Nome completo da mãe (PF) |
email, phone | string | Não | Contato |
role | enum | Não | legal_representative, individual_owner, corporate_owner ou admin |
qualification | enum | Não | DIRECTOR, ADMIN, OWNER, OWNER-ADMIN, ATTORNEY |
participation_percentage | number | Não | Participação societária (0-100) |
is_admin | boolean | Não | Marca o sócio como administrador da conta |
Adicionando um Sócio
Cada POST adiciona um novo sócio. Se já existir um com o mesmo document para o submerchant, o registro é atualizado em vez de duplicado (upsert idempotente).
curl -X POST https://api.payhubrasil.com.br/v1/submerchants/{id}/legal-representatives \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"name": "João Silva",
"document": "12345678901",
"birth_date": "1985-03-20",
"phone": "11999998888",
"mother_name": "Maria Silva",
"role": "legal_representative",
"participation_percentage": 60,
"is_admin": true,
"entity_type": "pf"
}'Listando os Sócios
curl -X GET https://api.payhubrasil.com.br/v1/submerchants/{id}/legal-representatives \
-H "Authorization: Basic {credentials}"Removendo um Sócio
curl -X DELETE https://api.payhubrasil.com.br/v1/submerchants/{id}/legal-representatives/{repId} \
-H "Authorization: Basic {credentials}"Documentos pessoais ligados ao sócio (legal_representative_id) são removidos em cascata.
Pelo menos um sócio é obrigatório para que um submerchant PJ possa ser enviado para análise via POST /v1/submerchants/{id}/submit-for-review.
Documentos
Documentos são arquivos comprobatórios exigidos para a análise e ativação do submerchant. Você deve fazer o upload do arquivo para um serviço de armazenamento e enviar a URL para a API.
Os documentos exigidos variam conforme o tipo de entidade (entity_type) do submerchant.
Documentos por tipo de entidade
Submerchants com entity_type: "pj" enviam documentos da empresa e documentos pessoais de cada sócio (estes vinculados via legal_representative_id).
Documentos da empresa:
Tipo (type) | Documento | Obrigatório |
|---|---|---|
social_contract | Contrato Social ou Requerimento de Empresário | Sim |
contract_amendment | Última alteração contratual | Não |
cnpj_card | Cartão CNPJ | Sim |
proof_of_residence_company | Comprovante de endereço da empresa | Sim |
Documentos por sócio (enviar para cada legal_representative_id):
Tipo (type) | Documento | Obrigatório |
|---|---|---|
partner_front_id | RG/CNH do sócio — frente | Sim |
partner_back_id | RG/CNH do sócio — verso | Sim |
partner_selfie_with_id | Selfie do sócio com o documento | Sim |
partner_proof_of_residence | Comprovante de residência do sócio | Sim |
Submerchants com entity_type: "pf" enviam apenas documentos pessoais:
Tipo (type) | Documento | Obrigatório |
|---|---|---|
front_id | RG/CNH — frente | Sim |
back_id | RG/CNH — verso | Sim |
selfie_with_id | Selfie com o documento | Sim |
proof_of_residence | Comprovante de residência | Sim |
Formatos aceitos
Os arquivos devem estar em um dos seguintes formatos:
- Imagens: PNG, JPG, JPEG
- Documentos: PDF
Adicionando um documento
curl -X POST https://api.payhubrasil.com.br/v1/submerchants/{id}/documents \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "social_contract",
"file_url": "https://storage.exemplo.com/docs/contrato.pdf",
"file_name": "contrato_social.pdf",
"file_size": 204800,
"mime_type": "application/pdf"
}'curl
Campos do documento
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | Sim | Tipo do documento (ver tabelas acima por entidade) |
number | string | Não | Número do documento (ex: número do RG) |
file_url | string | Sim | URL do arquivo já hospedado |
file_name | string | Sim | Nome do arquivo com extensão |
file_size | integer | Sim | Tamanho do arquivo em bytes (mínimo: 1) |
mime_type | string | Sim | Tipo MIME (application/pdf, image/png, image/jpeg) |
expires_at | string | Não | Data de validade do documento (ISO 8601) |
notes | string | Não | Anotações livres sobre o documento |
legal_representative_id | uuid | Condicional | Obrigatório quando type começa com partner_. Proibido nos demais. |
Reenviar um documento com o mesmo type (e mesmo legal_representative_id, no caso de docs de sócio) marca o anterior como substituído (replaced_at). A consulta de documentos para análise usa apenas o registro vigente.
Status do documento
Cada documento passa por uma verificação individual:
| Status | Descrição |
|---|---|
pending | Aguardando análise |
approved | Documento aprovado |
rejected | Documento rejeitado — verifique o motivo e reenvie |
expired | Documento expirado — envie uma versão atualizada |
Listando documentos
curl -X GET https://api.payhubrasil.com.br/v1/submerchants/{id}/documents \
-H "Authorization: Basic {credentials}"Endereços
Submerchants podem ter múltiplos endereços, cada um com um tipo específico.
Tipos de Endereço
| Tipo | Descrição |
|---|---|
billing | Endereço de faturamento |
shipping | Endereço de entrega |
both | Usado para faturamento e entrega |
Adicionando um Endereço
curl -X POST https://api.payhubrasil.com.br/v1/submerchants/{id}/addresses \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "billing",
"street": "Rua das Flores",
"number": "123",
"complement": "Sala 45",
"neighborhood": "Centro",
"city": "São Paulo",
"state": "SP",
"zip_code": "01001000",
"country": "BR",
"is_primary": true
}'Campos do Endereço
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | Não | billing, shipping ou both |
street | string | Sim | Logradouro |
number | string | Sim | Número |
complement | string | Não | Complemento |
neighborhood | string | Sim | Bairro |
city | string | Sim | Cidade |
state | string | Sim | UF (2 caracteres) |
zip_code | string | Sim | CEP (8-10 caracteres) |
country | string | Não | País (padrão: BR) |
is_primary | boolean | Não | Se é o endereço principal |
Atualizando um Endereço
Envie apenas os campos que deseja alterar:
curl -X PATCH https://api.payhubrasil.com.br/v1/submerchants/{id}/addresses/{addressId} \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"number": "456",
"complement": "Andar 2"
}'Removendo um Endereço
curl -X DELETE https://api.payhubrasil.com.br/v1/submerchants/{id}/addresses/{addressId} \
-H "Authorization: Basic {credentials}"