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

# Visão geral da API

> Base URL, autenticação, formato das respostas e o mapa dos endpoints.

## Base URL

| Ambiente | URL                            |
| -------- | ------------------------------ |
| Produção | `https://v4pay-api.vercel.app` |
| Local    | `http://localhost:3000`        |

## Autenticação

Header `Authorization: Bearer v4pay_...` nas rotas protegidas. Como gerar a chave está em
[Autenticação](/authentication). As rotas públicas (checkout, webhook do motor de
pagamentos, saúde) não exigem credencial.

## Formato das respostas

```json theme={null}
{ "data": { } }                            // sucesso
{ "error": { "message": "…", "codigo": "…" } }     // erro das rotas
{ "error": "Token JWT ou chave de API ausente" }   // erro do middleware de autenticação
```

<Note>
  O terceiro formato é uma exceção real, não erro de digitação desta página: quando a
  credencial falha, `error` vem como string. Trate os dois. Os `codigo` de negócio estão
  todos em [Erros e códigos](/erros-e-codigos).
</Note>

## Mapa

| Grupo                                           | O que cobre                                                                                                  |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Pix**                                         | emitir (manual ou por produto), listar, consultar status, cancelar, devolver, simular pagamento (teste)      |
| **Cobranças** e **Clientes**                    | registro direto de cobranças e o cadastro de pagadores                                                       |
| **Links de pagamento** e **Checkout (público)** | as URLs reutilizáveis e as rotas sem credencial que a página de pagamento usa                                |
| **Produtos** e **Cupons**                       | catálogo e descontos                                                                                         |
| **Assinaturas**                                 | recorrência — o cron diário emite as cobranças                                                               |
| **Webhooks (endpoints)** e **Chaves de API**    | as URLs de notificação da loja e as credenciais de integração                                                |
| **Conta de recebimento**                        | cadastro da empresa e a subconta — vale no modo subconta (ver [Modo de recebimento](/modo-de-recebimento))   |
| **Aprovação de produção**                       | o fluxo que libera a operação em produção                                                                    |
| **Saques**                                      | pedidos de saque — suspensos no modo conta única (`REPASSE_MANUAL`)                                          |
| **Membros da loja**                             | quem pode operar a loja junto com o dono                                                                     |
| **Conta (auth)**, **Auditoria** e **Sistema**   | sessão, trilha de ações e saúde                                                                              |
| **Interno**                                     | rotas do painel (Roadmap, aprovações da equipe, cron…) — documentadas por transparência, não para integração |

As páginas são geradas do `openapi.yaml` e têm **playground interativo**: informe
a sua chave e chame a API dali mesmo.

<Warning>
  `POST /pix/cancel` e `POST /pix/refund` existem, mas **ainda não executam** o
  cancelamento nem a devolução na origem — respondem `502` explicando. Está dito na página
  de cada um.
</Warning>