> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pag.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão Geral

> Visão geral da API do PagFinance: base URL, ambientes, autenticação, envelopes de resposta e erros comuns.

A API do PagFinance permite integrar pagamentos com criptomoedas convertidos para moeda local (PIX, boleto e giftcard), cotações de preço e verificação de KYC.

<Info>
  A forma recomendada de consumir a API é através do SDK oficial [@pagfinance/sdk](https://www.npmjs.com/package/@pagfinance/sdk). Consulte a [documentação da SDK](/pt-BR/sdks/introduction). Esta referência descreve os endpoints REST subjacentes.
</Info>

## Base URL

A API é exposta através de um host que atua como proxy (por exemplo, um app Next.js ou um BFF dedicado). O SDK aponta para esse host via a opção `baseUrl`.

<CodeGroup>
  ```bash Produção theme={null}
  https://app.pag.finance
  ```

  ```bash Sandbox (BRLP) theme={null}
  https://sandbox.brlp.io
  ```
</CodeGroup>

<Note>
  O domínio `sandbox.brlp.io` passará, no futuro, a hospedar exclusivamente os endpoints focados no **BRLP**. Organize sua integração já considerando essa separação. Veja o grupo [BRLP](/pt-BR/api-reference/brlp).
</Note>

## Ambientes

<CardGroup cols={2}>
  <Card title="Sandbox" icon="flask">
    Ambiente de testes para desenvolvimento e homologação. Base URL de sandbox.
  </Card>

  <Card title="Produção" icon="rocket">
    Ambiente de produção com transações reais. Base URL de produção.
  </Card>
</CardGroup>

## Autenticação

A API usa autenticação por token JWT no cabeçalho `Authorization`. O token é obtido por um fluxo de login Web3 do tipo challenge-response (estilo SIWS).

<Steps>
  <Step title="Solicitar desafio">
    `POST /api/auth/challenge` retorna um desafio (nonce) para o endereço informado.
  </Step>

  <Step title="Assinar">
    A aplicação assina o desafio com a carteira do usuário.
  </Step>

  <Step title="Verificar">
    `POST /api/auth/verify` recebe a assinatura e retorna o token JWT.
  </Step>
</Steps>

```http theme={null}
Authorization: Bearer <tokenJWT>
```

<Warning>
  Nenhuma chave privada ou lógica de assinatura vive na API cliente. A única prova é a assinatura da carteira, e toda a validação (nonce, verificação, emissão do token) ocorre no servidor. Consulte [Autenticação](/pt-BR/api-reference/authentication).
</Warning>

## Envelopes de resposta

A API pode retornar dois formatos de envelope. O SDK normaliza ambos automaticamente.

<CodeGroup>
  ```json Sucesso theme={null}
  {
    "success": true,
    "data": { }
  }
  ```

  ```json Erro theme={null}
  {
    "ok": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "messages": ["Mensagem de erro"],
      "fieldErrors": { "campo": "detalhe" }
    }
  }
  ```
</CodeGroup>

## Erros comuns

<ResponseField name="400 Bad Request" type="erro de validação">
  Requisição malformada ou parâmetros inválidos. O campo `fieldErrors` detalha os problemas por campo.
</ResponseField>

<ResponseField name="401 Unauthorized" type="não autenticado">
  Token JWT ausente, expirado ou inválido. Refaça o login. O SDK pode refazer o login automaticamente (auto-relogin).
</ResponseField>

<ResponseField name="403 Forbidden" type="sem permissão">
  O usuário autenticado não tem permissão para o recurso, ou o KYC exigido não foi concluído.
</ResponseField>

<ResponseField name="404 Not Found" type="não encontrado">
  Recurso inexistente (por exemplo, pagamento ou recibo não encontrado).
</ResponseField>

<ResponseField name="422 Unprocessable Entity" type="regra de negócio">
  A requisição é válida, mas viola uma regra de negócio (por exemplo, valor acima do limite permitido).
</ResponseField>

<ResponseField name="429 Too Many Requests" type="limite de taxa">
  Limite de requisições excedido. Aguarde antes de repetir.
</ResponseField>

<ResponseField name="500 Internal Server Error" type="erro interno">
  Erro inesperado no servidor. Tente novamente ou contate o suporte.
</ResponseField>

## Organização da referência

Os endpoints estão agrupados por recurso:

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="/pt-BR/api-reference/authentication">
    Login Web3, tokens e OTP.
  </Card>

  <Card title="Onramp e Offramp" icon="arrow-right-arrow-left" href="/pt-BR/api-reference/onramp-offramp">
    Ativos, preços e conversão entre cripto e moeda local.
  </Card>

  <Card title="Pagamentos" icon="money-bill-transfer" href="/pt-BR/api-reference/payments">
    Validação, cotação, criação e consulta de pagamentos.
  </Card>

  <Card title="BRLP" icon="brazilian-real-sign" href="/pt-BR/api-reference/brlp">
    Endpoints focados no BRLP, futuro domínio sandbox.brlp.io.
  </Card>

  <Card title="KYC" icon="id-card" href="/pt-BR/api-reference/kyc">
    Verificação de identidade de pessoa física e jurídica.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pt-BR/api-reference/webhooks">
    Notificações de eventos de pagamento e KYC.
  </Card>
</CardGroup>