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.documents:
Os documentos de empresa não aparecem nessa listagem.
Passo a passo
1. Crie a subconta com os sócios
Trecho do corpo dePOST /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.
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:
2. Emita o token de upload (no servidor)
201:
legalRepresentativeId.
3. Envie os arquivos direto do navegador
O navegador usa o token no cabeçalhoAuthorization: Bearer. A chave de API não aparece em nenhum momento no front-end.
Navegador (fetch + FormData)
cURL
201, sem corpo.
4. Liste os sócios e os documentos
cURL
200
Erros comuns
Perguntas frequentes
Preciso usar o token se a empresa tem um só sócio?
Preciso usar o token se a empresa tem um só sócio?
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.Os documentos da empresa precisam de token por sócio?
Os documentos da empresa precisam de token por sócio?
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.Posso usar o mesmo token para dois sócios?
Posso usar o mesmo token para dois sócios?
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.
Posso informar a subconta ou o sócio no corpo do upload?
Posso informar a subconta ou o sócio no corpo do upload?
Não. Em
POST /v1/document-uploads, a subconta e o sócio vêm sempre do token, nunca do corpo.O token expõe a minha chave secreta?
O token expõe a minha chave secreta?
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
additionalRepresentativese a resposta comlegalRepresentatives[]; - a emissão do token com
legalRepresentativeIde o upload correspondente; - a listagem com
include=documentsmostrando 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.

