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

# Sócios e documentos

> Cadastre todos os sócios da subconta, envie os documentos de cada um com um token de upload e acompanhe a análise de cada documento.

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

| Situação | Caminho |
| - | - |
| Empresa com um único representante, documentos coletados no seu servidor | Upload direto em `POST /v1/submerchants/{id}/document` ([Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)) |
| Empresa com sócios além do representante legal | Cadastro com `additionalRepresentatives` e upload com token, um token por sócio |
| Vendedor envia os documentos pelo navegador, no seu formulário de cadastro | Upload com token, mesmo com um único representante |
| Conferir quais documentos de cada sócio já foram enviados e analisados | `GET /v1/submerchants/{merchantId}/legal-representatives?include=documents` |

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

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
sequenceDiagram
    autonumber
    box rgb(255,246,229) Vendedor
        participant V as Navegador do sócio
    end
    box rgb(243,245,248) Sua aplicação
        participant S as Seu servidor (master)
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    S->>F: POST /v1/submerchants (legalRepresentative e additionalRepresentatives)
    F-->>S: 201 · id · legalRepresentatives[] com isPrimary
    Note over S: Guarde o id de cada sócio
    loop Para cada sócio, a cada envio
        V->>S: Escolhe os arquivos e pede um token
        S->>F: POST .../document/upload-token (legalRepresentativeId)
        F-->>S: 201 · token · expiresIn 300
        S-->>V: Só o token, nunca a chave secreta
        V->>F: POST /v1/document-uploads · Bearer token · multipart
        alt Envio aceito
            F-->>V: 201 sem corpo
        else Token vencido ou inválido
            F-->>V: 401
        else Token já usado
            F-->>V: 403
        else Arquivo recusado
            F-->>V: 400, 413, 415 ou 422 com o código em error
        end
    end
    S->>F: GET legal-representatives com include=documents
    F-->>S: Documentos por sócio · approved, rejected ou pending
```

**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

| Regra | Detalhe |
| - | - |
| Representante legal | `legalRepresentative` é obrigatório e é sempre o representante legal da subconta (`isPrimary: true`) |
| Sócios adicionais | Opcionais. Mesmo formato do representante legal. São cadastrados como sócios não representantes |
| Documentos no cadastro | Não vão no corpo da criação. São enviados depois, pelas rotas de upload |
| Upload direto | `POST /v1/submerchants/{id}/document` vincula documentos de pessoa sempre ao representante legal |
| Token sem `legalRepresentativeId` | Os documentos de pessoa vinculam ao representante legal |
| `legalRepresentativeId` de outra subconta | Resposta `404` com "Representante legal não encontrado" |
| Validade do token | 300 segundos (5 minutos), uso único |
| Reenvio | Reenviar um documento de pessoa substitui apenas o documento daquele sócio. A listagem mostra só o mais recente de cada tipo, por sócio |
| Documentos antigos | Documentos enviados antes do cadastro de sócios ficam com o representante legal |
| Documentos de empresa | `cnpj_card`, `social_contract` e `irs_letter` valem para a subconta inteira, por qualquer rota |
| Arquivos | JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF, até 50 MB cada |
| Subconta aprovada | Os documentos não podem mais ser alterados (`422`) |
| URLs dos documentos | Assinadas e válidas por 1 hora. Não armazene |

## Documentos de empresa e de pessoa

| Campo (fieldname) | Documento | Tipo | Vínculo |
| - | - | - | - |
| `cnpj_card` | Cartão CNPJ | Empresa | Subconta inteira |
| `social_contract` | Contrato social | Empresa | Subconta inteira |
| `irs_letter` | IRS letter, usada no fluxo de cadastro de LLC | Empresa | Subconta inteira |
| `responsible_document_front` | Documento de identidade, frente | Pessoa | Sócio do token (ou representante legal) |
| `responsible_document_back` | Documento de identidade, verso | Pessoa | Sócio do token (ou representante legal) |
| `selfie_with_document` | Selfie segurando o documento | Pessoa | Sócio do token (ou representante legal) |

> [!NOTE]
>
> 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](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md).

O desenho abaixo mostra a quem cada documento fica vinculado, conforme o tipo e a rota de envio.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    DOC{"Tipo do<br/>documento?"}:::decisao
    SUB(["Vale para a<br/>subconta inteira"]):::ok
    ROTA{"Rota de<br/>envio?"}:::decisao
    TK{"Token com<br/>o id do sócio?"}:::decisao
    RL(["Fica com o<br/>representante legal"]):::alerta
    SOC(["Fica com o<br/>sócio do token"]):::ok
    DOC -->|"empresa: cnpj_card,<br/>social_contract ou irs_letter<br/>por qualquer rota"| SUB
    DOC -->|"pessoa: identidade<br/>frente e verso ou selfie"| ROTA
    ROTA -->|"direta<br/>.../{id}/document"| RL
    ROTA -->|"com token<br/>/v1/document-uploads"| TK
    TK -->|"não"| RL
    TK -->|"sim, legalRepresentativeId"| SOC
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
```

Na listagem de representantes, os documentos de pessoa aparecem com outros nomes de chave em `documents`:

| Fieldname do upload | Chave em `documents` |
| - | - |
| `responsible_document_front` | `idFront` |
| `responsible_document_back` | `idBack` |
| `selfie_with_document` | `selfie` |

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](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md).

```json theme={null}
{
  "legalRepresentative": {
    "fullName": "Ana Lima",
    "idNumber": "52998224725",
    "idType": "cpf",
    "issuingCountry": "BRA",
    "dateOfBirth": "1985-04-20",
    "nationality": "Brasileira",
    "email": "ana@email.com",
    "motherName": "Maria Souza Lima",
    "gender": "F",
    "phones": [{ "type": "mobile", "number": "+5511987654321" }]
  },
  "additionalRepresentatives": [
    {
      "fullName": "Joao Silva",
      "idNumber": "11144477735",
      "idType": "cpf",
      "issuingCountry": "BRA",
      "dateOfBirth": "1985-05-10",
      "nationality": "Brasileira",
      "email": "joao@email.com",
      "motherName": "Maria Silva",
      "gender": "M",
      "phones": [{ "type": "mobile", "number": "+5511912345678" }]
    }
  ]
}
```

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`:

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "legalRepresentatives": [
    { "id": "2vorkEaaaBbbCccDddEeeFffGgg", "fullName": "Ana Lima", "isPrimary": true },
    { "id": "2vorkEbbbCccDddEeeFffGggHhh", "fullName": "Joao Silva", "isPrimary": false }
  ]
}
```

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

```http REST (JSON) theme={null}
POST /v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }'
```

```javascript Node.js (rota do seu backend) theme={null}
// Exemplo com Express: o front pede um token para um sócio específico
app.post('/api/subcontas/:subcontaId/socios/:socioId/upload-token', async (req, res) => {
  // Confira aqui se o usuário logado pode enviar documentos dessa subconta
  const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

  const response = await fetch(
    `https://api-global.fastpaybrasil.com/v1/submerchants/${req.params.subcontaId}/document/upload-token`,
    {
      method: 'POST',
      headers: {
        Authorization: `Basic ${credentials}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ legalRepresentativeId: req.params.socioId }),
    },
  );

  const { token, expiresIn } = await response.json();
  res.json({ token, expiresIn }); // nunca devolva a chave secreta ao front
});
```

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

import requests

payload = {
    "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

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

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

$payload = [
    'legalRepresentativeId' => '2vorkEbbbCccDddEeeFffGggHhh',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$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;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String payload = """
            {
              "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .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);

var payload = """
{
  "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

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

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

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	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 "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "legalRepresentativeId" => "2vorkEbbbCccDddEeeFffGggHhh",
})

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

puts response.code
puts response.body
```

Resposta `201`:

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300
}
```

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.

```javascript Navegador (fetch + FormData) theme={null}
async function enviarDocumentosDoSocio(subcontaId, socioId, arquivos) {
  // 1. Pede ao seu backend um token novo (válido por 300 segundos)
  const tokenResp = await fetch(
    `/api/subcontas/${subcontaId}/socios/${socioId}/upload-token`,
    { method: 'POST' },
  );
  const { token } = await tokenResp.json();

  // 2. Monta o multipart: o nome do campo é o nome do documento
  const form = new FormData();
  form.append('responsible_document_front', arquivos.frente);
  form.append('responsible_document_back', arquivos.verso);
  form.append('selfie_with_document', arquivos.selfie);

  // 3. Envia direto para a Finvia. Não defina Content-Type: o navegador monta o boundary
  const resp = await fetch('https://api-global.fastpaybrasil.com/v1/document-uploads', {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: form,
  });

  if (resp.status === 201) return;
  const erro = await resp.json();
  // Erros do arquivo trazem o código em `error` (ex.: FILE_TOO_LARGE); erros do token, o formato padrão
  throw new Error(`${resp.status}: ${erro.error ?? ''} ${erro.message}`);
}

// Uso com inputs de arquivo do formulário
const arquivos = {
  frente: document.querySelector('#doc-frente').files[0],
  verso: document.querySelector('#doc-verso').files[0],
  selfie: document.querySelector('#selfie').files[0],
};
await enviarDocumentosDoSocio('2vorkDcXyvzifL63YX09S9VqcnI', '2vorkEbbbCccDddEeeFffGggHhh', arquivos);
```

O mesmo envio pelo terminal, útil para testar:

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

A resposta de sucesso é `201`, sem corpo.

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

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/legal-representatives?include=documents" \
  -u "$FINVIA_API_KEY:"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "2vorkEaaaBbbCccDddEeeFffGgg",
      "fullName": "Ana Lima",
      "idNumber": "52998224725",
      "email": "ana@email.com",
      "isPrimary": true,
      "documents": {
        "idFront": {
          "id": "2vorkEdddEeeFffGggHhhIiiJjj",
          "url": "https://<armazenamento>/documents/abc123?X-Amz-Signature=...",
          "status": "approved",
          "rejectionReason": null,
          "createdAt": "2026-08-05T14:30:00.000Z"
        },
        "idBack": {
          "id": "2vorkEeeeFffGggHhhIiiJjjKkk",
          "url": "https://<armazenamento>/documents/def456?X-Amz-Signature=...",
          "status": "approved",
          "rejectionReason": null,
          "createdAt": "2026-08-05T14:30:00.000Z"
        },
        "selfie": {
          "id": "2vorkEfffGggHhhIiiJjjKkkLll",
          "url": "https://<armazenamento>/documents/ghi789?X-Amz-Signature=...",
          "status": "rejected",
          "rejectionReason": "Selfie sem o documento visível",
          "createdAt": "2026-08-05T14:30:00.000Z"
        }
      }
    },
    {
      "id": "2vorkEbbbCccDddEeeFffGggHhh",
      "fullName": "Joao Silva",
      "idNumber": "11144477735",
      "email": "joao@email.com",
      "isPrimary": false,
      "documents": {
        "idFront": {
          "id": "2vorkEgggHhhIiiJjjKkkLllMmm",
          "url": "https://<armazenamento>/documents/jkl012?X-Amz-Signature=...",
          "status": "pending",
          "rejectionReason": null,
          "createdAt": "2026-08-05T14:30:00.000Z"
        }
      }
    }
  ]
}
```

Como ler a resposta:

| Campo | Significado |
| - | - |
| `isPrimary` | `true` só no representante legal |
| `documents` | Aparece apenas com `include=documents` e pode vir vazio (`{}`) |
| `documents.idFront`, `idBack`, `selfie` | Documento de identidade frente, verso e selfie. **Chave ausente significa documento não enviado.** No exemplo, Joao Silva ainda não enviou o verso nem a selfie |
| `status` | Situação da análise do documento: `approved` se aprovado, `rejected` se reprovado, `pending` nos demais casos |
| `rejectionReason` | Motivo da rejeição, quando `status` é `rejected` |
| `url` | Link assinado para ver o arquivo. Expira em 1 hora |

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

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

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` com "Representante legal não encontrado" ao emitir o token | `legalRepresentativeId` não pertence à subconta | Use um id devolvido em `legalRepresentatives` ou na listagem de representantes da mesma subconta |
| `401` no `POST /v1/document-uploads` | Token vencido, inválido ou ausente | Emita um token novo logo antes do envio e use `Authorization: Bearer` |
| `403` "Token de upload expirado ou já utilizado" | O token já foi usado | Emita um token para cada envio |
| `400` `NO_FILE_SENT` ou `INVALID_DOCUMENT_NAME` | Nenhum arquivo no multipart, ou nome de campo fora da lista | Confira se os campos têm arquivo e se o nome do campo é um dos seis documentos |
| `413` `FILE_TOO_LARGE` ou `415` `UNSUPPORTED_FILE_TYPE` | Arquivo acima de 50 MB ou formato não aceito | Use PDF ou imagem (JPG, PNG, GIF, BMP ou WebP) até 50 MB |
| `422` `DOCUMENT_NOT_EDITABLE` | Subconta já aprovada | Fale com a Finvia se precisar atualizar documentos |
| Documentos do sócio aparecem no representante legal | Upload feito pela rota direta ou token emitido sem `legalRepresentativeId` | Emita o token com o id do sócio e reenvie |
| `404` com "Merchant não encontrado" na listagem | A subconta não pertence à master autenticada | Confira o `merchantId` e a chave usada |
| Link do documento não abre | URL assinada expirou (1 hora) | Consulte a listagem de novo |

## Perguntas frequentes

> [accordion] 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.

> [accordion] 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`.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](https://docs.fastpaybrasil.com/homologacao/roteiro.md), 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

> [card] [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
>
> Cadastro completo e status de aprovação.

> [card] [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md)
>
> Referência da rota do token.

> [card] [Enviar documentos com token](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token.md)
>
> Referência do upload com token.

> [card] [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md)
>
> Referência da listagem de sócios e documentos.


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