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

# Visão geral

> URL base, prefixo /v1, cabeçalhos comuns e como usar o playground sem cobrar ninguém de verdade.

A API da Vext tem cinco operações e três eventos. Tudo em JSON, tudo sob `/v1`, tudo autenticado por
chave secreta no header.

## URL base

Toda chamada vai para:

```
https://api.usevext.com
```

Todo endpoint desta versão vive sob `/v1`. A URL completa de uma criação de cobrança é
`https://api.usevext.com/v1/charges`.

## Cabeçalhos

**Você envia**

| Header                       | Quando         | Para quê                                       |
| ---------------------------- | -------------- | ---------------------------------------------- |
| `Authorization: Bearer sk_…` | Sempre         | Autentica a chamada                            |
| `Idempotency-Key`            | Em todo `POST` | Torna seguro repetir depois de um erro de rede |

**Você recebe**

| Header                      | Quando                 | Significa                                             |
| --------------------------- | ---------------------- | ----------------------------------------------------- |
| `Idempotent-Replayed: true` | Replay de idempotência | O corpo é uma resposta gravada; nada foi criado agora |
| `X-RateLimit-Limit`         | Toda resposta          | Requisições permitidas por minuto neste balde         |
| `X-RateLimit-Remaining`     | Toda resposta          | Quantas ainda cabem no minuto corrente                |
| `Retry-After`               | Em `429`               | Segundos até a cota ser reposta                       |

**Nós enviamos, nos webhooks**

| Header             | Significa                                                            |
| ------------------ | -------------------------------------------------------------------- |
| `X-Vext-Signature` | `t=<timestamp>,v1=<hmac>` — confira antes de agir                    |
| `X-Vext-Event`     | Tipo do evento, fora do corpo, para filtrar no log sem desserializar |
| `X-Vext-Delivery`  | Identificador da entrega — cite-o ao abrir um chamado                |

## Erros

Todo erro tem a mesma forma, inclusive os que não previmos:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_below_minimum",
    "message": "O valor está abaixo do mínimo permitido.",
    "details": {}
  }
}
```

Trate pelo `code`, nunca pela `message`: o código é contrato, o texto pode ser reescrito a qualquer
momento. O catálogo completo está em [Erros](/essenciais/erros).

## Usando o playground

O playground desta documentação envia requisições de verdade. Cole uma chave `sk_test_` — nunca uma
`sk_live_`. O prefixo é visível a olho nu de propósito: uma chave de produção colada aqui cria uma
cobrança real, com dinheiro real de um comprador real.

***

Ficou algo de fora? Escreva para [suporte@usevext.com](mailto:suporte@usevext.com). Se o assunto for
uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o
`X-Vext-Delivery` — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.