> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar documentos com token

> Envia documentos da subconta usando um token de upload, sem a chave secreta, inclusive do navegador e por sócio.

Esta rota recebe os documentos de uma subconta autenticada por um **token de upload**, gerado antes em [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md). 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

| Situação | Como usar esta rota |
| - | - |
| Documentos pessoais de um sócio adicional | Use um token emitido com o `legalRepresentativeId` do sócio |
| Upload pelo navegador ou aplicativo do vendedor | Seu servidor gera o token; o front-end envia os arquivos com ele |
| Substituir o documento de um sócio | Reenvie o documento com um token daquele sócio. Só o documento dele é substituído |
| Upload feito pelo seu servidor, só com representante legal | Você também pode usar [Enviar documentos](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos.md) com a chave secreta |

## Antes de chamar

* Gere o token com [`POST /v1/submerchants/{merchantId}/document/upload-token`](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload). 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](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md). 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.

**Authorization** `string` *required*

`Bearer` seguido do token devolvido em `token` por [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md). 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`).

**cnpj\_card** `file`

Cartão CNPJ da empresa (tipo `string`, formato `binary`). Documento de empresa.

**social\_contract** `file`

Contrato social da empresa (tipo `string`, formato `binary`). Documento de empresa.

**responsible\_document\_front** `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.

**responsible\_document\_back** `file`

Verso do documento de identificação (tipo `string`, formato `binary`). Documento de pessoa.

**selfie\_with\_document** `file`

Selfie segurando o documento (tipo `string`, formato `binary`). Documento de pessoa.

**irs\_letter** `file`

IRS letter, usada no fluxo de cadastro de LLC (tipo `string`, formato `binary`). Documento de empresa.

> [!NOTE]
>
> 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.

| Tipo | Campos | Vinculado a |
| - | - | - |
| Documentos de empresa | `cnpj_card`, `social_contract`, `irs_letter` | Subconta como um todo. Não usam o vínculo por sócio |
| Documentos de pessoa | `responsible_document_front`, `responsible_document_back`, `selfie_with_document` | Sócio do token (`legalRepresentativeId`) ou, sem sócio, representante legal |

## Respostas

A resposta `201` não tem corpo.

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Documentos enviados | Sem conteúdo |
| `400` | `NO_FILE_SENT`: nenhum arquivo | `{"error": "NO_FILE_SENT", "message": "Nenhum arquivo foi enviado."}` |
| `400` | `INVALID_DOCUMENT_NAME`: nome de campo fora da lista | `{"error": "INVALID_DOCUMENT_NAME", "message": "Tipo de documento inválido para este envio."}` |
| `401` | Token ausente, com assinatura inválida ou vencido | `{"statusCode": 401, "message": "Token de upload inválido ou expirado"}` |
| `403` | Token já usado | `{"statusCode": 403, "message": "Token de upload expirado ou já utilizado"}` |
| `413` | `FILE_TOO_LARGE`: arquivo acima de 50 MB | `{"error": "FILE_TOO_LARGE", "message": "O arquivo excede o tamanho máximo de 50 MB.", "details": {...}}` |
| `415` | `UNSUPPORTED_FILE_TYPE`: tipo de arquivo não aceito | `{"error": "UNSUPPORTED_FILE_TYPE", "message": "Tipo de arquivo não suportado. Envie PDF ou imagem (JPG, PNG, GIF, BMP ou WebP).", "details": {...}}` |
| `422` | `DOCUMENT_NOT_EDITABLE`: subconta já aprovada | `{"error": "DOCUMENT_NOT_EDITABLE", "message": "Este documento não pode mais ser alterado no cadastro atual."}` |

### 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`.

> [!WARNING]
>
> 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.

> [!TIP]
>
> Depois do `201`, confira em [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md) com `include=documents`: o sócio passa a ter `idFront`, `idBack` e `selfie` com o status de análise.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401` "Token de upload inválido ou expirado" | Token vencido (300 segundos), ausente ou inválido | Gere um token novo e envie logo em seguida |
| `401` usando a chave secreta | Esta rota não aceita a chave de API | Use `Authorization: Bearer` com o token de upload |
| `403` "Token de upload expirado ou já utilizado" | O token já foi usado em outro envio | Gere um token para cada envio |
| `400` `NO_FILE_SENT` | Nenhum arquivo no multipart, ou campos sem arquivo | Envie pelo menos um arquivo nos campos aceitos |
| `400` `INVALID_DOCUMENT_NAME` | Nome de campo fora da lista | Use um dos seis nomes desta página |
| `413` `FILE_TOO_LARGE` | Arquivo acima de 50 MB | Reduza a resolução ou comprima o PDF |
| `415` `UNSUPPORTED_FILE_TYPE` | Formato fora da lista (ex.: HEIC, DOCX) | Converta para JPG, PNG ou PDF |
| `422` `DOCUMENT_NOT_EDITABLE` | Subconta já aprovada | Fale com a Finvia se precisar atualizar documentos |

> [!TIP]
>
> **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.

```http REST (JSON) theme={null}
POST /v1/document-uploads HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Bearer <token de upload>
Content-Type: multipart/form-data; boundary=----FinviaBoundary

------FinviaBoundary
Content-Disposition: form-data; name="responsible_document_front"; filename="rg-frente.jpg"

<conteúdo de rg-frente.jpg>
------FinviaBoundary
Content-Disposition: form-data; name="responsible_document_back"; filename="rg-verso.jpg"

<conteúdo de rg-verso.jpg>
------FinviaBoundary
Content-Disposition: form-data; name="selfie_with_document"; filename="selfie.jpg"

<conteúdo de selfie.jpg>
------FinviaBoundary--
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/document-uploads" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -F "responsible_document_front=@./rg-frente.jpg" \
  -F "responsible_document_back=@./rg-verso.jpg" \
  -F "selfie_with_document=@./selfie.jpg"
```

```javascript Node.js theme={null}
// No navegador: uploadToken foi gerado pelo seu servidor
const form = new FormData();
form.append('responsible_document_front', fileInputFront.files[0]);
form.append('responsible_document_back', fileInputBack.files[0]);
form.append('selfie_with_document', fileInputSelfie.files[0]);

const response = await fetch('https://api-global.fastpaybrasil.com/v1/document-uploads', {
  method: 'POST',
  headers: { Authorization: `Bearer ${uploadToken}` },
  body: form,
});

if (response.status === 401 || response.status === 403) {
  // token vencido ou já usado: peça um novo ao seu servidor e tente de novo
} else if (response.status !== 201) {
  const { error } = await response.json(); // ex.: FILE_TOO_LARGE, UNSUPPORTED_FILE_TYPE
  console.error(error);
}
```

```python Python theme={null}
import os

import requests

files = {
    "responsible_document_front": open("./rg-frente.jpg", "rb"),
    "responsible_document_back": open("./rg-verso.jpg", "rb"),
    "selfie_with_document": open("./selfie.jpg", "rb"),
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/document-uploads",
    headers={"Authorization": f"Bearer {os.environ['UPLOAD_TOKEN']}"},
    files=files,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/document-uploads');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('UPLOAD_TOKEN')],
    CURLOPT_POSTFIELDS => [
        'responsible_document_front' => new CURLFile('./rg-frente.jpg', null, 'rg-frente.jpg'),
        'responsible_document_back' => new CURLFile('./rg-verso.jpg', null, 'rg-verso.jpg'),
        'selfie_with_document' => new CURLFile('./selfie.jpg', null, 'selfie.jpg'),
    ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.ByteArrayOutputStream;
import java.nio.file.Files;
import java.nio.file.Path;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String boundary = "FinviaBoundary";
        ByteArrayOutputStream form = new ByteArrayOutputStream();
        String[][] files = {
            {"responsible_document_front", "./rg-frente.jpg"},
            {"responsible_document_back", "./rg-verso.jpg"},
            {"selfie_with_document", "./selfie.jpg"},
        };
        for (String[] file : files) {
            Path path = Path.of(file[1]);
            form.write(("--" + boundary + "\r\n"
                + "Content-Disposition: form-data; name=\"" + file[0] + "\"; filename=\""
                + path.getFileName() + "\"\r\n"
                + "Content-Type: application/octet-stream\r\n\r\n").getBytes());
            form.write(Files.readAllBytes(path));
            form.write("\r\n".getBytes());
        }
        form.write(("--" + boundary + "--\r\n").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/document-uploads"))
            .header("Authorization", "Bearer " + System.getenv("UPLOAD_TOKEN"))
            .header("Content-Type", "multipart/form-data; boundary=" + boundary)
            .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray()))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UPLOAD_TOKEN"));

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-frente.jpg")), "responsible_document_front", "rg-frente.jpg");
form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-verso.jpg")), "responsible_document_back", "rg-verso.jpg");
form.Add(new ByteArrayContent(File.ReadAllBytes("./selfie.jpg")), "selfie_with_document", "selfie.jpg");

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/document-uploads");
request.Content = form;

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
)

func main() {
	var form bytes.Buffer
	writer := multipart.NewWriter(&form)
	files := [][2]string{
		{"responsible_document_front", "./rg-frente.jpg"},
		{"responsible_document_back", "./rg-verso.jpg"},
		{"selfie_with_document", "./selfie.jpg"},
	}
	for _, file := range files {
		part, err := writer.CreateFormFile(file[0], filepath.Base(file[1]))
		if err != nil {
			panic(err)
		}
		content, err := os.ReadFile(file[1])
		if err != nil {
			panic(err)
		}
		part.Write(content)
	}
	writer.Close()

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/document-uploads", &form)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("UPLOAD_TOKEN"))
	req.Header.Set("Content-Type", writer.FormDataContentType())

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/document-uploads")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("UPLOAD_TOKEN")}"
request.set_form(
  [
    ["responsible_document_front", File.open("./rg-frente.jpg")],
    ["responsible_document_back", File.open("./rg-verso.jpg")],
    ["selfie_with_document", File.open("./selfie.jpg")],
  ],
  "multipart/form-data"
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```text 201 theme={null}
(sem corpo)
```

```json 400 theme={null}
{ "error": "NO_FILE_SENT", "message": "Nenhum arquivo foi enviado." }
```

```json 401 theme={null}
{ "statusCode": 401, "message": "Token de upload inválido ou expirado", "error": "Unauthorized" }
```

```json 403 theme={null}
{ "statusCode": 403, "message": "Token de upload expirado ou já utilizado", "error": "Forbidden" }
```

```json 413 theme={null}
{
  "error": "FILE_TOO_LARGE",
  "message": "O arquivo excede o tamanho máximo de 50 MB.",
  "details": { "maxMb": 50, "actualMb": 62.4 }
}
```

```json 422 theme={null}
{
  "error": "DOCUMENT_NOT_EDITABLE",
  "message": "Este documento não pode mais ser alterado no cadastro atual."
}
```

## Veja também

> [card] [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md)
>
> Gere o token antes de enviar.

> [card] [Sócios e documentos](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md)
>
> Fluxo completo de documentos por sócio.

> [card] [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md)
>
> Confira os documentos enviados.

> [card] [Enviar documentos](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos.md)
>
> Upload direto com a chave secreta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.