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

# Introdução à Referência

> URL base, autenticação, formato dos dados e como ler as páginas de endpoint da API da Finvia.

Esta seção descreve cada rota da API da Finvia com todos os parâmetros, todos os campos de resposta e todos os códigos HTTP do contrato. Use os guias para entender **o fluxo** de um recurso (Pix, 3D Secure, estorno) e use a Referência para conferir **o detalhe** de uma chamada: nome exato do campo, tipo, se é obrigatório e o que volta.

> [!NOTE]
>
> **Para o negócio:** cada página de endpoint começa com um parágrafo sobre para que a rota serve e uma tabela "Quando usar". Esses trechos ajudam a decidir o que pedir ao time técnico sem precisar ler os parâmetros. Os detalhes técnicos vêm logo depois.

## URL base

Todas as rotas usam o mesmo endereço, em produção e no sandbox (ambiente de testes):

```text theme={null}
https://api-global.fastpaybrasil.com
```

O ambiente é definido pela chave enviada. Com uma chave de teste (`sk_test_`, `pk_test_`), toda cobrança em `POST /v1/charges` é simulada, inclusive com cartão salvo. Com uma chave de produção (`sk_`, `pk_`), as transações são reais. O cadastro de cartão e as assinaturas não têm sandbox, e não existe saque no sandbox (veja o aviso em [Testar no playground](#testar-no-playground)). As rotas começam com `/v1`, por exemplo `GET /v1/charges`.

Outros endereços: o painel fica em `https://app.finvia.com.br`, e o SDK de 3D Secure via CDN em `https://js.fastpaybrasil.com/security-sdk.min.js`. No 3DS gerenciado, use o endereço recebido em `authenticationUrl`, sem montar a URL. As URLs de documentos são assinadas e têm o domínio do provedor de armazenamento (nos exemplos, `https://<armazenamento>/documents/...`): não fixe esse domínio.

## Autenticação

A maior parte da API usa **HTTP Basic Auth** com a chave secreta: a chave vai no lugar do usuário, a senha fica vazia e o par `chave:` é convertido para Base64.

```text theme={null}
Authorization: Basic c2tfYWJjMTIzOg==
```

O valor acima é o Base64 de `sk_abc123:`. Para conferir se o seu valor está certo, decodifique o Base64 e veja se ele termina com `:`. O passo a passo completo, com exemplos em várias linguagens, está em [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md).

Nem todas as rotas usam a mesma credencial:

| Credencial | Como enviar | Rotas |
| - | - | - |
| Chave secreta (`sk_`, `sk_test_`) | `Authorization: Basic` com `chave:` em Base64 | Todas as rotas não listadas abaixo: cobranças, estorno, clientes, cartões, planos, assinaturas, meios de pagamento, saldo (`GET /v1/wallets`), saques (`/v1/payout-requests` e o saque de subconta), domínios Apple Pay, subcontas, `fees-info` e endpoints de webhook |
| Chave pública (`pk_`, `pk_test_`) | `Authorization: Basic` com `chave:` em Base64, usando a chave pública | Apple Pay: `POST /v1/apple-pay/validate-merchant`. 3D Secure: `POST /v1/three-ds/authenticate`, `POST /v1/three-ds/submit`, `POST /v1/three-ds/cancel`, `POST /v1/three-ds/challenge-result` e `POST /v1/charges/{id}/resume-3ds` |
| Token de upload | `Authorization: Bearer` seguido do token gerado em `POST /v1/submerchants/{merchantId}/document/upload-token` | Só `POST /v1/document-uploads`. Esse token é diferente da chave de API |

Fora o envio de documentos com token, toda chamada de integração usa uma das chaves da tabela.

> [!WARNING]
>
> A chave **secreta** (`sk_`) nunca pode aparecer em código que roda no navegador ou no aplicativo do cliente. A chave **pública** (`pk_`) foi feita para o front-end e é a que você usa nas rotas de 3D Secure e na validação de sessão do Apple Pay. A conta precisa estar ativa para a `pk_` funcionar.

A chave age com as permissões do usuário que a gerou. A chave de produção criada automaticamente pertence ao proprietário da conta e funciona em todas as rotas. Se for usar uma chave gerada por outro usuário, gere com um perfil **Owner** ou **Manager**: chaves de Desenvolvedor recebem `403` com `Acesso negado` ao criar cobranças, em saldo e em saques, e as de Desenvolvedor e Financeiro também nas rotas de planos e assinaturas (veja [Permissões da chave](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#permissões-da-chave)).

## Formato dos dados

| Item | Regra | Exemplo |
| - | - | - |
| Corpo das requisições e respostas | JSON, com `Content-Type: application/json` nas requisições com corpo | `{"chargeId": "2vorkDcXyvzifL63YX09S9VqcnI"}` |
| Nomes de campos | camelCase na API | `paymentMethod`, `createdAt`, `pspRefId` |
| Valores monetários | Em **reais** (decimal), na unidade da moeda | `10` = R\$ 10,00; `199.99` = R\$ 199,99 |
| Datas | ISO 8601 (formato `date-time`) | `2023-01-15T14:30:00Z` |
| Moedas | Código ISO 4217 | `BRL` |
| Países | ISO 3166-1 alpha-3, em maiúsculas | `BRA` |

Exceções que você vai encontrar:

* Os itens da cobrança usam `unit_price` (com sublinhado), como está no contrato.
* Os endpoints de webhook (`/v1/webhook-endpoints`) recebem o corpo em snake\_case (`enabled_events`, `include_submerchants`) e respondem em camelCase.
* `orderBy` em `GET /v1/submerchants` usa os nomes das colunas em snake\_case (`legal_name,-created_at`).
* Nas respostas de `GET` de cobrança, as chaves de `metadata` voltam em camelCase. Envie-as nesse formato para lê-las iguais em todos os canais (veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata)).
* Valores de saque (`amount`, `payoutFee`, `netAmount`) e o `splitPercentage` do split chegam como texto decimal com 8 casas (ex.: `"100.00000000"`). Converta para número antes de calcular.
* Os webhooks de cobrança e de assinatura usam snake\_case no primeiro nível de `data`, como `psp_ref_id` e `paid_at`; os objetos aninhados da cobrança ficam em camelCase. O postback `charge.updated`, os avisos de conta e os eventos de saque usam camelCase. Detalhes em [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md).

## Paginação, ordenação e idempotência

* Todas as listagens paginadas recebem `page` (começa em `1`) e `size` (itens por página, padrão `10`). `limit` e outros parâmetros desconhecidos são ignorados sem erro. Algumas listagens devolvem um array simples, sem paginação, como `GET /v1/wallets`.
* A maior parte das listagens tem ordem fixa, da mais recente para a mais antiga. `orderBy` só funciona em `GET /v1/submerchants`, com nomes em snake\_case.
* O cabeçalho `Idempotency-Key` não existe hoje: depois de um timeout, siga o procedimento descrito em [Idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#idempotência).

Regras completas e exemplos em [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md).

## Erros

Os erros voltam com o código HTTP e um corpo JSON. Há três formatos:

| Formato | Onde aparece | Exemplo |
| - | - | - |
| `{ statusCode, message, error }` | A maior parte das rotas. Em erros de validação de campos (`400`), `message` é uma lista | `{ "statusCode": 404, "message": "Cobrança não encontrada", "error": "Not Found" }` |
| `{ code, message }` | Erros de negócio do Apple Pay e validação de cartão em `POST /v1/subscriptions` | `{ "code": "APPLE_PAY_DOMAIN_NOT_VERIFIED", "message": "..." }` |
| `{ error, message, details }` | Erros de arquivo em `POST /v1/document-uploads` | `{ "error": "NO_FILE_SENT", "message": "Nenhum arquivo foi enviado." }` |

```json theme={null}
{
  "statusCode": 400,
  "message": ["amount must be a positive number", "amount must not be less than 1"],
  "error": "Bad Request"
}
```

| HTTP | Significado geral |
| - | - |
| `400` | Corpo inválido (validação) ou operação não permitida no estado atual |
| `401` | Credencial ausente ou inválida |
| `403` | A credencial não tem permissão para o recurso (`Acesso negado`), recurso não habilitado ou operação indisponível no Modo Teste |
| `404` | Recurso não encontrado ou fora do escopo da sua chave |
| `409` | Conflito, como CNPJ já cadastrado ou requisição simultânea |
| `422` | Regra de negócio violada |
| `429` | Limite de tentativas atingido |
| `500` e `503` | Erro interno ou serviço indisponível |
| `501` | Operação não disponível para o método ou provedor |

Trate o erro pelo código HTTP e, quando existir, pelo campo `code` ou `error` dos dois últimos formatos. As mensagens misturam português e inglês e não devem ser comparadas como texto. Cada página de endpoint lista os códigos da rota. O tratamento recomendado está em [Erros e como tratar](https://docs.fastpaybrasil.com/primeiros-passos/erros.md) e as mensagens de cada rota em [Códigos de erro](https://docs.fastpaybrasil.com/anexos/codigos-de-erro.md).

## Como ler uma página de endpoint

Toda página de endpoint segue a mesma ordem:

**1. Cabeçalho**

Método e rota (ex.: `POST /v1/refunds`) e o tipo de autenticação.

**2. Para que serve, quando usar e antes de chamar**

Contexto de negócio, situações de uso e pré-requisitos.

**3. Parâmetros**

Cada parâmetro aparece com o nome, onde ele vai (`path`, `query` ou `body`), o tipo e o selo **required** quando é obrigatório. Valores padrão aparecem como `default`. Limites (mínimo, máximo, tamanho) e valores aceitos (enums) ficam na descrição.

**4. Respostas**

Todos os campos da resposta de sucesso, seguidos de uma tabela com os códigos HTTP documentados.

**5. Exemplos**

Exemplo de requisição em cURL e Node.js e exemplos de resposta de sucesso e de erro, no painel lateral.

Objetos aninhados ficam recolhidos. Clique em **propriedades** (ou no nome da variante, quando o campo pode ter formatos diferentes) para ver os campos internos. Quando um campo recebe um formato diferente por forma de pagamento, cada formato aparece em um bloco separado.

> [!TIP]
>
> **Para o desenvolvedor:** um campo sem o selo **required** pode ser omitido na requisição. Na resposta, um tipo como `string | null` significa que o campo pode vir `null`. Escreva o seu código para tolerar campos ausentes e nulos sempre que o tipo indicar isso.

## Testar no playground

As páginas de endpoint têm um botão para enviar a requisição direto do navegador. Use sempre uma **chave de teste** nesse recurso:

* Em rotas com chave secreta, informe a chave `sk_test_` como usuário e deixe a senha vazia.
* Nas rotas de 3D Secure, informe a chave pública de teste (`pk_test_`).
* Em `POST /v1/document-uploads`, informe o token de upload.

> [!WARNING]
>
> Não use a chave de produção no playground. Mesmo com a chave de teste, o cadastro de cartão (`POST /v1/cards`) registra o cartão de verdade (sem cobrar) e as assinaturas cobram de verdade. O cofre de cartões é o mesmo para teste e produção.

## Veja também

> [card] [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)
>
> Como gerar as chaves e montar o cabeçalho.

> [card] [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> A rota central da API.

> [card] [Mapa da API](https://docs.fastpaybrasil.com/mapa-da-api.md)
>
> Todas as rotas agrupadas por recurso.

> [card] [Roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> O que testar antes de ir para produção.


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