Skip to main content
GET
Esta rota mostra quem são as pessoas cadastradas em uma subconta: o representante legal (sempre o primeiro da lista) e os sócios adicionais. Com include=documents, ela também mostra os documentos pessoais de cada um e em que ponto está a análise de cada arquivo. É a forma de saber quais documentos faltam e quais foram rejeitados.

Quando usar

Antes de chamar

  • Tenha o id da subconta (merchantId), devolvido em Criar subconta.
  • Autentique com a chave secreta (sk_) da conta master à qual a subconta pertence (Credenciais e ambientes). A master precisa ter o Connect habilitado; sem isso, a resposta é 403.

Parâmetros

string
required
Id da subconta. Ex.: 36OO3bcGjhPjjF3tzrqOGcmQuKo.
string
Use documents para incluir os documentos de cada sócio. É o único valor aceito: qualquer outro devolve 400.

Respostas

object[]
Representantes e sócios da subconta: o representante legal primeiro (isPrimary: true) e depois os sócios, por data de cadastro.

Documento (RepresentativeDocument)

Cada item de documents tem estes campos:
string
Identificador do documento. Ex.: 2vorkEdddEeeFffGggHhhIiiJjj.
string
URL assinada para visualizar o arquivo. Expira em 1 hora: não armazene. Ex.: https://<armazenamento>/documents/abc123?X-Amz-Signature=....
string
Status de análise do documento: approved se aprovado, rejected se reprovado e pending nos demais casos.
string | null
Motivo da rejeição, quando status é rejected. Ex.: null.
string
Data de envio (formato date-time). Ex.: 2026-08-05T14:30:00.000Z.

Como mapear os documentos

A correspondência entre o nome do campo usado no upload (fieldname) e a chave em documents é fixa: Só esses três documentos de pessoa aparecem. Os documentos da empresa (cnpj_card, social_contract, irs_letter) não são retornados por esta rota.

A qual sócio cada documento fica ligado

Um reenvio substitui o anterior: aparece só o documento mais recente de cada tipo, por sócio.
As url dos documentos são assinadas e expiram em 1 hora. Não grave a URL no seu banco nem a envie por e-mail. Quando precisar exibir o arquivo, consulte esta rota de novo.
Para o negócio: com include=documents, o time de operações vê, por sócio, o que já foi enviado, o que está em análise e o que foi rejeitado (com o motivo). Isso permite cobrar do vendedor só o documento que falta.

Erros comuns

Veja também

Sócios e documentos

Fluxo de documentos por sócio.

Criar token de upload

Token vinculado a um sócio.

Enviar documentos com token

Upload dos documentos do sócio.

Subcontas e KYC

Credenciamento da subconta.