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

# Criar token de upload

> Emite um token de curta duração para enviar documentos da subconta sem expor a chave secreta, com vínculo opcional a um sócio.

Esta rota gera um **token de upload**: uma credencial temporária, válida por 5 minutos, que só serve para enviar documentos de uma subconta em [`POST /v1/document-uploads`](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token). Com ele, o upload pode sair direto do navegador do vendedor, sem que a chave secreta saia do seu servidor. É também o único caminho para enviar os documentos pessoais de um **sócio adicional**.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Documentos pessoais de um sócio adicional | Envie o `legalRepresentativeId` do sócio |
| Tela de upload no navegador do vendedor | Gere o token no seu servidor e entregue só o token ao front-end |
| Reenviar o documento de um sócio específico | Gere um token novo com o `legalRepresentativeId` dele e reenvie o arquivo |
| Documentos do representante legal ou da empresa | Sem corpo (vincula ao representante legal), ou use [Enviar documentos](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos.md) |

## Antes de chamar

* Tenha o `id` da subconta, devolvido em [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md).
* Para um sócio, tenha o `id` dele: vem em `legalRepresentatives` na resposta da criação (itens com `isPrimary: false`) ou em [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md).
* Autentique com a chave secreta (`sk_`) da **conta master**, sempre no servidor ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).

## Parâmetros de caminho

**merchantId** `string` *required*

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

## Corpo da requisição

Formato `application/json`. O corpo é opcional.

**legalRepresentativeId** `string`

Sócio ao qual os documentos de pessoa (`responsible_document_front`, `responsible_document_back`, `selfie_with_document`) serão vinculados. Precisa pertencer à subconta; caso contrário, a resposta é `404`. Quando omitido, os documentos ficam no representante legal. Ex.: `2vorkEbbbCccDddEeeFffGggHhh`.

> [!NOTE]
>
> O `legalRepresentativeId` só afeta documentos de pessoa. Documentos de empresa (`cnpj_card`, `social_contract`, `irs_letter`) valem para a subconta como um todo, com ou sem sócio no token.

## Respostas

**token** `string`

Token de upload. Use no cabeçalho `Authorization: Bearer` da chamada [`POST /v1/document-uploads`](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token). Ex.: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`.

**expiresIn** `integer`

Validade do token em segundos. Ex.: `300` (5 minutos).

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Token emitido | `token`, `expiresIn` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `404` | Representante legal não encontrado (não pertence à subconta) | `{"statusCode": 404, "message": "Representante legal não encontrado"}` |

> [!WARNING]
>
> O token expira em **300 segundos** (5 minutos) e é de **uso único**. Gere o token no momento do envio. Token vencido é recusado com `401` "Token de upload inválido ou expirado"; token já usado, com `403` "Token de upload expirado ou já utilizado". Nos dois casos, gere outro token.

> [!TIP]
>
> **Para o desenvolvedor:** a subconta e o sócio ficam gravados **dentro do token**. O front-end recebe só o token e não consegue trocar de subconta ou de sócio. Gere um token por sócio: um token emitido para Bruno vincula os documentos de pessoa a Bruno, mesmo que o arquivo seja de outra pessoa.

> [!NOTE]
>
> **Para o negócio:** com o token, cada sócio pode enviar os próprios documentos por um link ou tela do seu sistema, e a chave secreta da sua conta continua guardada no servidor.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` "Representante legal não encontrado" | `legalRepresentativeId` de outra subconta ou inexistente | Confira os ids com [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md) para esse `merchantId` |
| `401` | Chave ausente, inválida ou mal codificada no Basic | Codifique `chave:` em Base64 (com os dois-pontos no fim) |
| Upload recusado com `401` minutos depois | Token vencido (300 segundos) | Gere um token novo logo antes do envio |
| Segundo upload recusado com `403` | O token é de uso único | Gere um token para cada envio |
| Documentos do sócio aparecem no representante legal | Token emitido sem `legalRepresentativeId` | Envie o id do sócio no corpo |

```http REST (JSON) theme={null}
POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/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/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }'
```

```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}/document/upload-token`,
  {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ legalRepresentativeId: '2vorkEbbbCccDddEeeFffGggHhh' }),
  },
);

const { token, expiresIn } = await response.json();
// Entregue apenas o token ao front-end; ele vale por expiresIn segundos
```

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

import requests

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

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/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/36OO3bcGjhPjjF3tzrqOGcmQuKo/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/36OO3bcGjhPjjF3tzrqOGcmQuKo/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/36OO3bcGjhPjjF3tzrqOGcmQuKo/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/36OO3bcGjhPjjF3tzrqOGcmQuKo/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/36OO3bcGjhPjjF3tzrqOGcmQuKo/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
```

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

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

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

## Veja também

> [card] [Enviar documentos com token](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token.md)
>
> Upload usando o token gerado aqui.

> [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)
>
> Ids dos sócios e status dos documentos.

> [card] [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md)
>
> Cadastro com sócios adicionais.


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