Skip to main content
POST
Esta rota recebe os documentos de uma subconta autenticada por um token de upload, gerado antes em Criar token de upload. A subconta e o eventual sócio são lidos de dentro do token; o corpo leva só os arquivos. Por isso a chamada pode sair do navegador do vendedor sem expor a chave secreta, e é por ela que os documentos de cada sócio adicional chegam à Finvia.

Quando usar

Antes de chamar

  • Gere o token com POST /v1/submerchants/{merchantId}/document/upload-token. Ele expira em 300 segundos e vale para um único envio.
  • Os arquivos precisam estar em PDF ou imagem (JPG, PNG, GIF, BMP ou WebP), com no máximo 50 MB cada.
  • Confira quais documentos o credenciamento exige em Regras de credenciamento. Não há campo para o certificado de MEI: para esse documento, fale com o suporte da Finvia.

Autenticação

Envie o token de upload no cabeçalho Authorization: Bearer. Esta rota não aceita a chave de API.
string
required
Bearer seguido do token devolvido em token por Criar token de upload. Ex.: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....

Corpo da requisição

Formato multipart/form-data, obrigatório. O nome de cada campo é o nome do documento. Nenhum campo é obrigatório sozinho, mas a requisição precisa ter pelo menos um arquivo (minProperties: 1).
file
Cartão CNPJ da empresa (tipo string, formato binary). Documento de empresa.
file
Contrato social da empresa (tipo string, formato binary). Documento de empresa.
file
Frente do documento de identificação (tipo string, formato binary). Documento de pessoa: fica no sócio do token ou, sem sócio, no representante legal.
file
Verso do documento de identificação (tipo string, formato binary). Documento de pessoa.
file
Selfie segurando o documento (tipo string, formato binary). Documento de pessoa.
file
IRS letter, usada no fluxo de cadastro de LLC (tipo string, formato binary). Documento de empresa.
O contrato descreve os campos de pessoa como documentos “do representante legal” porque o esquema é o mesmo da rota direta. Nesta rota, eles vão para o sócio indicado no token.

Respostas

A resposta 201 não tem corpo.

Dois formatos de erro

  • Erros do arquivo (400, 413, 415, 422) vêm como { "error": "<CÓDIGO>", "message": "...", "details": { ... } }, sem statusCode. Decida pelo campo error, que é estável. No 413, details traz maxMb e actualMb; no 415, allowed e actualType.
  • Erros do token (401, 403) vêm no formato padrão { statusCode, message, error }.
Trate o erro pelo código HTTP e pelo campo error, não pelo texto de message.
Reenviar um documento de pessoa substitui apenas o documento daquele sócio. Se o token foi emitido para o sócio errado, o documento substituído será o desse sócio. Confira o legalRepresentativeId antes de gerar o token.
Depois do 201, confira em Listar representantes com include=documents: o sócio passa a ter idFront, idBack e selfie com o status de análise.

Erros comuns

Para o desenvolvedor: ao usar FormData, não defina o cabeçalho Content-Type manualmente. O fetch monta o valor multipart/form-data com o separador (boundary) correto.

Veja também

Criar token de upload

Gere o token antes de enviar.

Sócios e documentos

Fluxo completo de documentos por sócio.

Listar representantes

Confira os documentos enviados.

Enviar documentos

Upload direto com a chave secreta.