Documentos e Endereços

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.accithus.com/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.accithus.com/v1/submerchants/{id}/legal-representatives \
  -H "Authorization: Basic {credentials}"

Removendo um Sócio

curl -X DELETE https://api.accithus.com/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

Pessoa Jurídica (PJ)
Pessoa Física (PF)

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

Para pessoa física, os documentos da empresa e os documentos por sócio não são necessários.

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.accithus.com/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 -X POST https://api.accithus.com/v1/submerchants/{id}/documents \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "partner_front_id",
    "legal_representative_id": "{repId}",
    "file_url": "https://storage.exemplo.com/docs/rg_socio_frente.jpg",
    "file_name": "rg_socio_frente.jpg",
    "file_size": 153600,
    "mime_type": "image/jpeg"
  }'

curl -X POST https://api.accithus.com/v1/submerchants/{id}/documents \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "front_id",
    "file_url": "https://storage.exemplo.com/docs/rg_frente.jpg",
    "file_name": "rg_frente.jpg",
    "file_size": 153600,
    "mime_type": "image/jpeg"
  }'

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.accithus.com/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.accithus.com/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.accithus.com/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.accithus.com/v1/submerchants/{id}/addresses/{addressId} \
  -H "Authorization: Basic {credentials}"

Começando

Cobranças

Submerchants

Financeiro

Configuração

SDK de Segurança

Webhooks

Documentos e Endereços

Sócios e Representantes Legais (PJ)

Campos do Sócio

Adicionando um Sócio

Listando os Sócios

Removendo um Sócio

Documentos

Documentos por tipo de entidade

Formatos aceitos

Adicionando um documento

Campos do documento

Status do documento

Listando documentos

Endereços

Tipos de Endereço

Adicionando um Endereço

Campos do Endereço

Atualizando um Endereço

Removendo um Endereço

​Sócios e Representantes Legais (PJ)

​Campos do Sócio

​Adicionando um Sócio

​Listando os Sócios

​Removendo um Sócio

​Documentos

​Documentos por tipo de entidade

​Formatos aceitos

​Adicionando um documento

​Campos do documento

​Status do documento

​Listando documentos

​Endereços

​Tipos de Endereço

​Adicionando um Endereço

​Campos do Endereço

​Atualizando um Endereço

​Removendo um Endereço

Sócios e Representantes Legais (PJ)

Campos do Sócio

Adicionando um Sócio

Listando os Sócios

Removendo um Sócio

Documentos

Documentos por tipo de entidade

Formatos aceitos

Adicionando um documento

Campos do documento

Status do documento

Listando documentos

Endereços

Tipos de Endereço

Adicionando um Endereço

Campos do Endereço

Atualizando um Endereço

Removendo um Endereço