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

# Listar representantes da subconta

> Lista o representante legal e os sócios de uma subconta e, se pedido, os documentos de cada um com o status de análise.

Esta rota mostra quem são as pessoas cadastradas em uma subconta: o representante legal (sempre o primeiro da lista) e os sócios adicionais. Com `include=documents`, ela também mostra os documentos pessoais de cada um e em que ponto está a análise de cada arquivo. É a forma de saber quais documentos faltam e quais foram rejeitados.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Recuperar o `id` de um sócio para gerar um token de upload | Chame sem `include` |
| Saber quais documentos pessoais ainda faltam | Chame com `include=documents` e confira as chaves ausentes em `documents` |
| Mostrar ao vendedor o motivo de rejeição de um documento | Use `status` e `rejectionReason` de cada documento |
| Exibir o documento enviado para conferência interna | Use a `url` assinada, que vale por 1 hora |

## Antes de chamar

* Tenha o `id` da subconta (`merchantId`), devolvido em [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md).
* Autentique com a chave secreta (`sk_`) da **conta master** à qual a subconta pertence ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)). A master precisa ter o Connect habilitado; sem isso, a resposta é `403`.

## Parâmetros

**merchantId** `string` *required*

Id da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`.

**include** `string`

Use `documents` para incluir os documentos de cada sócio. É o único valor aceito: qualquer outro devolve `400`.

## Respostas

**data** `object[]`

Representantes e sócios da subconta: o **representante legal primeiro** (`isPrimary: true`) e depois os sócios, por data de cadastro.

**propriedades**

**id** `string`

Identificador do representante ou sócio. É o valor usado em `legalRepresentativeId` ao [criar um token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md). Ex.: `2vorkEaaaBbbCccDddEeeFffGgg`.

**fullName** `string`

Nome completo. Ex.: `Ana Lima`.

**idNumber** `string | null`

Número do documento de identificação (CPF, no Brasil). Ex.: `52998224725`.

**email** `string`

E-mail. Ex.: `ana.lima@email.com`.

**isPrimary** `boolean`

`true` apenas no representante legal da empresa.

**documents** `object`

Presente somente com `include=documents`, e pode vir vazio (`{}`). Chave ausente significa documento **não enviado**.

**propriedades**

**idFront** `object`

Frente do documento de identificação (esquema `RepresentativeDocument`, abaixo).

**idBack** `object`

Verso do documento de identificação (esquema `RepresentativeDocument`).

**selfie** `object`

Selfie com documento (esquema `RepresentativeDocument`).

### Documento (`RepresentativeDocument`)

Cada item de `documents` tem estes campos:

**id** `string`

Identificador do documento. Ex.: `2vorkEdddEeeFffGggHhhIiiJjj`.

**url** `string`

URL **assinada** para visualizar o arquivo. Expira em **1 hora**: não armazene. Ex.: `https://<armazenamento>/documents/abc123?X-Amz-Signature=...`.

**status** `string`

Status de análise do documento: `approved` se aprovado, `rejected` se reprovado e `pending` nos demais casos.

**rejectionReason** `string | null`

Motivo da rejeição, quando `status` é `rejected`. Ex.: `null`.

**createdAt** `string`

Data de envio (formato `date-time`). Ex.: `2026-08-05T14:30:00.000Z`.

### Como mapear os documentos

A correspondência entre o nome do campo usado no upload (fieldname) e a chave em `documents` é fixa:

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

Só esses três documentos de pessoa aparecem. Os documentos da empresa (`cnpj_card`, `social_contract`, `irs_letter`) não são retornados por esta rota.

### A qual sócio cada documento fica ligado

| Como o documento foi enviado | Fica com |
| - | - |
| Token de upload gerado com `legalRepresentativeId` | O sócio daquele `legalRepresentativeId` |
| Token de upload gerado sem `legalRepresentativeId` | O representante legal (`isPrimary: true`) |
| Rota [`POST /v1/submerchants/{id}/document`](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos) | O representante legal |
| Documentos antigos, enviados antes do cadastro de sócios | O representante legal |

Um reenvio substitui o anterior: aparece só o documento mais recente de cada tipo, por sócio.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Lista de representantes | `data` |
| `400` | `include` com valor diferente de `documents` | `{"statusCode": 400, "message": "...", "error": "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."}` |
| `404` | Subconta não encontrada ou que não pertence à conta master autenticada | `{"statusCode": 404, "message": "Merchant não encontrado"}` |

> [!WARNING]
>
> As `url` dos documentos são assinadas e **expiram em 1 hora**. Não grave a URL no seu banco nem a envie por e-mail. Quando precisar exibir o arquivo, consulte esta rota de novo.

> [!NOTE]
>
> **Para o negócio:** com `include=documents`, o time de operações vê, por sócio, o que já foi enviado, o que está em análise e o que foi rejeitado (com o motivo). Isso permite cobrar do vendedor só o documento que falta.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` "Merchant não encontrado" | `merchantId` de outra conta master, inexistente ou de outro ambiente | Use a chave da conta master dona da subconta, no mesmo ambiente |
| `400` no `include` | Valor diferente de `documents` | Use `include=documents` |
| `documents` ausente | Chamada sem `include=documents` | Acrescente `?include=documents` |
| Falta `idBack` ou `selfie` em `documents` | Documento ainda não enviado | Envie o arquivo pelo fluxo com token, com o `id` do sócio |
| Link do documento parou de abrir | URL assinada expirada (1 hora) | Consulte a rota de novo para obter uma URL nova |
| Documento do sócio aparece no representante principal | Upload feito pela rota direta ou com token sem `legalRepresentativeId` | Reenvie com um token emitido para o sócio |

```http REST (JSON) theme={null}
GET /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

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

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const merchantId = '36OO3bcGjhPjjF3tzrqOGcmQuKo';

const response = await fetch(
  `https://api-global.fastpaybrasil.com/v1/submerchants/${merchantId}/legal-representatives?include=documents`,
  { headers: { Authorization: `Basic ${credentials}` } },
);

const { data } = await response.json();

for (const person of data) {
  const docs = person.documents ?? {};
  const missing = ['idFront', 'idBack', 'selfie'].filter((key) => !docs[key]);
  console.log(person.fullName, 'faltam:', missing);
}
```

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

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    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/legal-representatives?include=documents');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

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

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .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 request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents");

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"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	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/legal-representatives?include=documents")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

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

puts response.code
puts response.body
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "2vorkEaaaBbbCccDddEeeFffGgg",
      "fullName": "Ana Lima",
      "idNumber": "52998224725",
      "email": "ana.lima@email.com",
      "isPrimary": true,
      "documents": {
        "idFront": {
          "id": "2vorkEdddEeeFffGggHhhIiiJjj",
          "url": "https://<armazenamento>/documents/abc123?X-Amz-Signature=...",
          "status": "pending",
          "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": "Documento ilegível",
          "createdAt": "2026-08-05T14:30:00.000Z"
        }
      }
    },
    {
      "id": "2vorkEbbbCccDddEeeFffGggHhh",
      "fullName": "Joao Silva",
      "idNumber": "11144477735",
      "email": "joao.silva@email.com",
      "isPrimary": false,
      "documents": {}
    }
  ]
}
```

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

```json 404 theme={null}
{ "statusCode": 404, "message": "Merchant não encontrado" }
```

## Veja também

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

> [card] [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md)
>
> Token vinculado a um sócio.

> [card] [Enviar documentos com token](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token.md)
>
> Upload dos documentos do sócio.

> [card] [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
>
> Credenciamento da subconta.


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