Skip to main content
Empresas com mais de um sócio podem ser cadastradas com todos eles de uma vez. Cada sócio recebe um identificador próprio, e os documentos de pessoa (identidade e selfie) ficam vinculados ao sócio certo. Para coletar esses documentos, a Finvia oferece um token de upload: uma credencial temporária, de 5 minutos, que permite enviar os arquivos direto do navegador do vendedor sem expor a sua chave secreta.

Quando usar

Para o negócio: com o token, o arquivo vai do computador ou celular do vendedor direto para a Finvia. A sua plataforma não precisa receber nem armazenar fotos de documentos de identidade, e a chave secreta continua guardada no seu servidor.

Como funciona

A sequência abaixo mostra o envio com token: o seu servidor emite o token e o navegador do sócio manda os arquivos direto para a Finvia.
1

Cadastre os sócios

Na criação da subconta, envie o representante legal em legalRepresentative e os demais sócios em additionalRepresentatives.
2

Guarde os ids

A resposta traz legalRepresentatives[]: o representante legal primeiro, com isPrimary: true, e depois os sócios na ordem enviada, com isPrimary: false.
3

Emita um token por sócio

No seu servidor, chame POST /v1/submerchants/{merchantId}/document/upload-token com o legalRepresentativeId do sócio. O token vale 300 segundos.
4

Envie os arquivos com o token

O navegador (ou o seu servidor) envia os arquivos para POST /v1/document-uploads com Authorization: Bearer e o token. A subconta e o sócio vêm de dentro do token.
5

Confira os documentos

Liste os representantes com include=documents para ver o que foi enviado e o status de análise de cada documento.

Regras de negócio

Documentos de empresa e de pessoa

O nome de cada campo do formulário multipart é o próprio nome do documento. Use exatamente os nomes da tabela acima: outro nome é recusado com 400. Não há campo para o certificado de MEI; para enviá-lo, fale com o suporte da Finvia. A lista de documentos que o credenciamento exige está em Regras de credenciamento.
O desenho abaixo mostra a quem cada documento fica vinculado, conforme o tipo e a rota de envio. Na listagem de representantes, os documentos de pessoa aparecem com outros nomes de chave em documents: Os documentos de empresa não aparecem nessa listagem.

Passo a passo

1. Crie a subconta com os sócios

Trecho do corpo de POST /v1/submerchants com o bloco de sócios. Os demais campos obrigatórios (empresa, endereço, telefones, conta bancária, acesso ao painel) estão em Subcontas e KYC.
O CPF de cada pessoa (idNumber) é validado com dígitos verificadores quando issuingCountry é BRA ou não é enviado. Use o CPF real de cada pessoa. O país vai em ISO 3166-1 alpha-3 (BRA); BR é recusado. Resposta 201:
Para o desenvolvedor: relacione cada id de legalRepresentatives ao sócio correspondente no seu banco. A ordem é sempre o representante legal primeiro e depois os sócios na ordem em que você enviou. Se perder os ids, recupere com GET /v1/submerchants/{merchantId}/legal-representatives.

2. Emita o token de upload (no servidor)

Resposta 201:
Para vincular os documentos ao representante legal, envie a requisição sem corpo ou sem o campo legalRepresentativeId.

3. Envie os arquivos direto do navegador

O navegador usa o token no cabeçalho Authorization: Bearer. A chave de API não aparece em nenhum momento no front-end.
Navegador (fetch + FormData)
O mesmo envio pelo terminal, útil para testar:
cURL
A resposta de sucesso é 201, sem corpo.
Peça o token no momento do envio, depois que o vendedor escolheu os arquivos. O token expira em 5 minutos e vale para um único envio. Token vencido volta 401 “Token de upload inválido ou expirado”; token já usado volta 403 “Token de upload expirado ou já utilizado”.

4. Liste os sócios e os documentos

cURL
200
Como ler a resposta:
Não grave a url dos documentos no seu banco. Ela expira em 1 hora. Quando precisar mostrar o arquivo, consulte a listagem de novo.
Para o desenvolvedor: use esta listagem para montar uma tela de pendências por sócio: documento ausente, em análise, aprovado ou rejeitado com motivo. Quando um documento de pessoa for rejeitado, emita um token para aquele sócio e reenvie só o documento rejeitado. O reenvio substitui apenas o documento daquele sócio.

Erros comuns

Perguntas frequentes

Não. Com um único representante, o upload direto em POST /v1/submerchants/{id}/document resolve. O token é útil quando há sócios adicionais ou quando você quer receber os arquivos direto do navegador, sem passar pelo seu servidor.
Não. cnpj_card, social_contract e irs_letter valem para a subconta inteira e podem ser enviados por qualquer uma das duas rotas, com ou sem legalRepresentativeId.
Não. O sócio vem de dentro do token, e o token vale para um único envio. Emita um token para cada sócio e para cada envio.
Não. Em POST /v1/document-uploads, a subconta e o sócio vêm sempre do token, nunca do corpo.
Não. O token é emitido pelo seu servidor com a chave secreta, mas só serve para enviar documentos daquela subconta (e daquele sócio) por 5 minutos.

Como testar

No roteiro de homologação, o cenário FC-02 pede a evidência de cada upload (tipo enviado e resposta). Se a sua integração usa sócios adicionais, inclua também:
  • a criação com additionalRepresentatives e a resposta com legalRepresentatives[];
  • a emissão do token com legalRepresentativeId e o upload correspondente;
  • a listagem com include=documents mostrando os documentos de cada sócio.

Veja também

Subcontas e KYC

Cadastro completo e status de aprovação.

Criar token de upload

Referência da rota do token.

Enviar documentos com token

Referência do upload com token.

Listar representantes

Referência da listagem de sócios e documentos.