> ## 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 da subconta

> Envia os documentos da empresa e do representante legal para a análise de credenciamento da subconta.

Depois de criar a subconta, a Finvia precisa dos documentos da empresa e do representante legal para fazer o credenciamento (KYC). Esta rota recebe esses arquivos direto do seu servidor, autenticada com a chave secreta da conta master. Os documentos de pessoa enviados aqui ficam sempre ligados ao **representante legal** (principal).

## Quando usar

| Situação | Rota indicada |
| - | - |
| Subconta com um único representante, upload feito pelo seu servidor | Esta rota |
| Documentos de empresa (`cnpj_card`, `social_contract`, `irs_letter`) | Esta rota ou o fluxo com token: valem para a subconta como um todo |
| Documentos pessoais de um **sócio adicional** | [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md) com o `legalRepresentativeId` do sócio e [Enviar documentos com token](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token.md) |
| Upload feito do navegador do vendedor, sem expor a chave secreta | Fluxo com token |

> [!NOTE]
>
> Se a subconta tem só um representante (sem `additionalRepresentatives`), esta rota é tudo o que você precisa. Integrações que já usam esta rota continuam funcionando sem mudança.

## Antes de chamar

* Tenha o `id` da subconta, devolvido em [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md).
* Autentique com a chave secreta (`sk_`) da **conta master** ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* Os arquivos precisam estar em **JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF**, com no máximo **50 MB** cada.
* Envie antes da aprovação: depois que a subconta é aprovada, novos uploads são bloqueados (`422`).
* Confira quais documentos o credenciamento exige em [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md).

## Parâmetros de caminho

**id** `string` *required*

Identificador único da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`.

## Corpo da requisição

Formato `multipart/form-data`, obrigatório. O nome de cada campo é o tipo do documento. Nenhum campo é obrigatório sozinho, mas a requisição precisa ter **pelo menos um arquivo** (`minProperties: 1`). Você pode enviar vários documentos na mesma chamada ou um por chamada.

**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 do representante legal (tipo `string`, formato `binary`). Documento de pessoa.

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

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

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

Selfie do representante legal 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.

| Documento | Campo | Vinculado a |
| - | - | - |
| Cartão CNPJ | `cnpj_card` | Subconta |
| Contrato social | `social_contract` | Subconta |
| IRS letter (LLC) | `irs_letter` | Subconta |
| Documento, frente | `responsible_document_front` | Representante legal |
| Documento, verso | `responsible_document_back` | Representante legal |
| Selfie com documento | `selfie_with_document` | Representante legal |

Qualquer outro nome de campo é recusado com `400` `Invalid document name`. Não há campo para o certificado de MEI: para enviar esse documento, fale com o suporte da Finvia.

> [!WARNING]
>
> Esta rota **não** diferencia sócios. Documentos de pessoa enviados aqui sempre ficam no representante legal. Se você enviar aqui a identidade de um sócio adicional, ela será registrada como documento do representante principal. Para sócios, use o fluxo com token.

## Respostas

A resposta `201` não tem corpo. O sucesso é indicado pelo código HTTP.

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Documentos enviados | Sem conteúdo |
| `400` | Tipo de arquivo não aceito, arquivo acima de 50 MB ou nenhum arquivo | Mensagem padrão de validação. Ex.: `Validation failed (current file type is text/plain, expected type is ...)` ou `File is required` |
| `400` | Nome de campo fora da lista | `{"statusCode": 400, "message": "Invalid document name", "error": "Bad Request"}` |
| `400` | Subconta que não pertence à conta master | `{"statusCode": 400, "message": "Bad Request"}` |
| `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` |
| `422` | Subconta já aprovada: os documentos não podem mais ser alterados | `{"statusCode": 422, "message": "Unprocessable Entity"}` |

Esta rota usa o corpo de erro padrão (`statusCode`, `message`, `error`), sem os códigos próprios da [rota com token](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token.md). Trate o erro pelo código HTTP.

> [!TIP]
>
> Cada arquivo foi aceito quando a resposta é `201`. Para conferir os documentos de pessoa e o status de análise de cada um, use [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md) com `include=documents`.

> [!NOTE]
>
> **Para o negócio:** no roteiro de homologação, o cenário FC-02 pede um envio por tipo: contrato social, cartão CNPJ, documento do responsável (frente e verso) e selfie com documento. Peça esses arquivos ao vendedor já no cadastro, para enviar tudo logo depois de criar a subconta.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` `Validation failed (...)` | Formato fora da lista aceita (ex.: HEIC, DOCX) ou arquivo acima de 50 MB | Converta para JPEG, PNG ou PDF e reduza o tamanho |
| `400` `File is required` | Requisição sem arquivo | Envie pelo menos um dos seis campos |
| `400` `Invalid document name` | Nome de campo fora da lista (ex.: `mei_certificate`) | Use um dos seis nomes desta página |
| `422` `Unprocessable Entity` | Subconta já aprovada | Fale com a Finvia se precisar atualizar documentos |
| Documento do sócio ficou no representante principal | Rota direta usada para sócio adicional | Use o fluxo com token e o `legalRepresentativeId` do sócio |

```http REST (JSON) theme={null}
POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: multipart/form-data; boundary=----FinviaBoundary

------FinviaBoundary
Content-Disposition: form-data; name="cnpj_card"; filename="cartao-cnpj.pdf"

<conteúdo de cartao-cnpj.pdf>
------FinviaBoundary
Content-Disposition: form-data; name="social_contract"; filename="contrato-social.pdf"

<conteúdo de contrato-social.pdf>
------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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document" \
  -u "$FINVIA_API_KEY:" \
  -F "cnpj_card=@./cartao-cnpj.pdf" \
  -F "social_contract=@./contrato-social.pdf" \
  -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}
import { readFile } from 'node:fs/promises';

const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const id = '36OO3bcGjhPjjF3tzrqOGcmQuKo';

const form = new FormData();
form.append('cnpj_card', new Blob([await readFile('./cartao-cnpj.pdf')], { type: 'application/pdf' }), 'cartao-cnpj.pdf');
form.append('social_contract', new Blob([await readFile('./contrato-social.pdf')], { type: 'application/pdf' }), 'contrato-social.pdf');
form.append('responsible_document_front', new Blob([await readFile('./rg-frente.jpg')], { type: 'image/jpeg' }), 'rg-frente.jpg');
form.append('responsible_document_back', new Blob([await readFile('./rg-verso.jpg')], { type: 'image/jpeg' }), 'rg-verso.jpg');
form.append('selfie_with_document', new Blob([await readFile('./selfie.jpg')], { type: 'image/jpeg' }), 'selfie.jpg');

// Não defina Content-Type: o fetch monta o boundary do multipart
const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants/${id}/document`, {
  method: 'POST',
  headers: { Authorization: `Basic ${credentials}` },
  body: form,
});

if (response.status !== 201) {
  console.error(await response.json());
}
```

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

import requests

files = {
    "cnpj_card": open("./cartao-cnpj.pdf", "rb"),
    "social_contract": open("./contrato-social.pdf", "rb"),
    "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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_POSTFIELDS => [
        'cnpj_card' => new CURLFile('./cartao-cnpj.pdf', null, 'cartao-cnpj.pdf'),
        'social_contract' => new CURLFile('./contrato-social.pdf', null, 'contrato-social.pdf'),
        '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.util.Base64;
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 credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String boundary = "FinviaBoundary";
        ByteArrayOutputStream form = new ByteArrayOutputStream();
        String[][] files = {
            {"cnpj_card", "./cartao-cnpj.pdf"},
            {"social_contract", "./contrato-social.pdf"},
            {"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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document"))
            .header("Authorization", "Basic " + credentials)
            .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;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("./cartao-cnpj.pdf")), "cnpj_card", "cartao-cnpj.pdf");
form.Add(new ByteArrayContent(File.ReadAllBytes("./contrato-social.pdf")), "social_contract", "contrato-social.pdf");
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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document");
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{
		{"cnpj_card", "./cartao-cnpj.pdf"},
		{"social_contract", "./contrato-social.pdf"},
		{"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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document", &form)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request.set_form(
  [
    ["cnpj_card", File.open("./cartao-cnpj.pdf")],
    ["social_contract", File.open("./contrato-social.pdf")],
    ["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}
{ "statusCode": 400, "message": "Invalid document name", "error": "Bad Request" }
```

```json 401 theme={null}
{ "statusCode": 401, "message": "Unauthorized" }
```

```json 422 theme={null}
{ "statusCode": 422, "message": "Unprocessable Entity" }
```

## Veja também

> [card] [Sócios e documentos](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md)
>
> Quando usar a rota direta e quando usar o token.

> [card] [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md)
>
> Token para sócios e uploads pelo navegador.

> [card] [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md)
>
> Status de análise de cada documento.

> [card] [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
>
> Fluxo completo de credenciamento.


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