# Evolution Boost Reseller API (v1)

API REST para revendedores oficiais do Evolution Boost: coloque saldo em reais via PIX, compre keys de licença com esse saldo e consulte as suas keys.

URL base: https://evolutionboost.xyz/api/v1
Documentação: https://evolutionboost.xyz/docs/api
OpenAPI 3.1: https://evolutionboost.xyz/openapi.json

Gerado da mesma fonte de https://evolutionboost.xyz/docs/api e /openapi.json.

## Introdução

A API de revendedores do Evolution Boost permite que revendedores oficiais coloquem saldo via PIX, comprem keys de licença com esse saldo e consultem as próprias keys (livres, resgatadas ou todas) a partir dos seus sistemas, bots ou lojas.

É uma API REST em JSON sobre HTTPS. A URL base é `https://evolutionboost.xyz/api/v1`. Ela é feita para uso servidor a servidor: nunca chame pelo navegador nem coloque a sua chave dentro de um app (não há CORS).

- Dinheiro é sempre um inteiro em centavos de real (`12990` = R$ 129,90), com `currency: "BRL"`.
- Datas são ISO 8601 em UTC.
- Toda resposta traz o cabeçalho `X-Request-Id`. Informe-o ao falar com o suporte.
- As respostas nunca vão para cache (`Cache-Control: no-store`).
- Não há webhooks na v1: consulte os endpoints periodicamente.

## Autenticação

Autentique toda requisição com a sua chave de API no cabeçalho `Authorization`, como Bearer token. As chaves começam com `evb_live_` e são criadas pela equipe do Evolution Boost no painel admin. Você recebe a chave completa uma única vez, então guarde-a em um cofre de segredos ou variável de ambiente.

```http
Authorization: Bearer evb_live_xxxxxxxxxxxxxxxx
```

- Chave ausente, inválida, revogada ou expirada devolve `401 invalid_api_key` (mesma resposta em todos os casos).
- Chave válida de revendedor revogado devolve `403 reseller_inactive`.
- Falhas de autenticação demais do mesmo IP (20 por minuto) devolvem `429` antes de a chave ser conferida.
- Se uma chave vazar, peça à equipe para revogá-la e emitir outra. Você pode ter várias chaves (por exemplo uma por sistema).

### Cabeçalhos

- Authorization (Sempre): `Bearer evb_live_...`, a sua chave de API.
- Content-Type (POST): `application/json`. O corpo tem limite de 24000 bytes.
- Idempotency-Key (POST): Uma chave única por operação (UUID). Veja Idempotência.
- X-Request-Id (Opcional): O seu próprio id de requisição (8 a 64 caracteres entre `A-Z a-z 0-9 . _ -`), devolvido na resposta; senão, geramos um. Sempre presente nas respostas.

## Erros

Os erros usam os status HTTP convencionais e um corpo JSON. Trate por `error.type` e `error.code`, nunca pela `message`. `param` aponta o campo ou cabeçalho que causou o erro.

```json
{
  "error": {
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "message": "Insufficient balance: this purchase costs 5990 cents and the balance is 1200 cents.",
    "param": null
  },
  "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c"
}
```

### Tipos de erro

- authentication_error (HTTP 401): A chave de API está ausente, inválida, revogada ou expirada.
- permission_error (HTTP 403): A chave é válida, mas a conta do revendedor não está ativa.
- invalid_request_error (HTTP 400, 404, 405, 409, 413): A requisição está malformada ou aponta para algo que não existe.
- insufficient_balance (HTTP 402): O saldo não cobre a compra. Nada foi cobrado.
- rate_limit_error (HTTP 429): Requisições demais. Aguarde `Retry-After` segundos.
- api_error (HTTP 500, 502, 503): Algo falhou do nosso lado ou no provedor de pagamento. Tente de novo com espera crescente.

### Códigos de erro

- invalid_api_key (HTTP 401, authentication_error): Chave de API ausente, inválida, revogada ou expirada. A resposta é a mesma em todos os casos.
- reseller_inactive (HTTP 403, permission_error): A conta do revendedor foi revogada ou removida.
- invalid_json (HTTP 400, invalid_request_error): O corpo está vazio, não é JSON ou não é um objeto JSON.
- idempotency_key_required (HTTP 400, invalid_request_error): POST sem o cabeçalho `Idempotency-Key`.
- invalid_idempotency_key (HTTP 400, invalid_request_error): `Idempotency-Key` deve ter de 1 a 255 caracteres ASCII visíveis, sem espaços.
- invalid_amount (HTTP 400, invalid_request_error): `amount_cents` deve ser um inteiro entre 1000 e 500000.
- too_many_pending_deposits (HTTP 400, invalid_request_error): Você já tem 3 depósitos pendentes. Pague um ou espere expirar.
- missing_items (HTTP 400, invalid_request_error): Envie `items` (não vazio) ou `package_code`.
- invalid_items (HTTP 400, invalid_request_error): `items` deve ser uma lista de objetos.
- too_many_items (HTTP 400, invalid_request_error): `items` aceita no máximo 50 itens.
- invalid_package_code (HTTP 400, invalid_request_error): `package_code` deve ter o formato `H150` (1 a 20 letras ou dígitos).
- invalid_quantity (HTTP 400, invalid_request_error): `quantity` deve ser um inteiro entre 1 e 100.
- duplicate_package (HTTP 400, invalid_request_error): O mesmo pacote aparece duas vezes em `items`. Some as quantidades.
- too_many_keys (HTTP 400, invalid_request_error): Uma requisição cria no máximo 100 keys no total.
- package_unavailable (HTTP 400, invalid_request_error): O pacote não existe ou não tem preço de atacado. Veja `GET /packages`.
- invalid_limit (HTTP 400, invalid_request_error): `limit` deve ser um inteiro entre 1 e 100.
- invalid_cursor (HTTP 400, invalid_request_error): `starting_after` não é um UUID ou não é um objeto desta lista.
- invalid_status (HTTP 400, invalid_request_error): Valor desconhecido no filtro `status`.
- invalid_kind (HTTP 400, invalid_request_error): Valor desconhecido no filtro `kind`.
- invalid_batch_id (HTTP 400, invalid_request_error): `batch_id` deve ser um UUID.
- insufficient_balance (HTTP 402, insufficient_balance): O saldo não cobre o total da compra. Nada foi cobrado nem criado.
- resource_missing (HTTP 404, invalid_request_error): O objeto não existe ou é de outro revendedor (mesma resposta), ou o endpoint não existe.
- method_not_allowed (HTTP 405, invalid_request_error): Método HTTP não suportado. Veja o cabeçalho `Allow`.
- idempotency_key_reused (HTTP 409, invalid_request_error): A `Idempotency-Key` já foi usada com outro corpo. Use uma chave nova para uma operação nova.
- payload_too_large (HTTP 413, invalid_request_error): O corpo passa de 24000 bytes.
- rate_limit_exceeded (HTTP 429, rate_limit_error): Limite de taxa atingido. Aguarde os segundos do cabeçalho `Retry-After`.
- internal_error (HTTP 500, api_error): Erro inesperado. Tente mais tarde; em POST, reutilize a mesma `Idempotency-Key`.
- payment_provider_error (HTTP 502, api_error): O provedor PIX falhou ao criar a cobrança. Tente mais tarde.
- service_unavailable (HTTP 503, api_error): O serviço está temporariamente indisponível. Tente de novo com espera crescente.

## Paginação

Os endpoints de lista devolvem `{"object": "list", "data": [...], "has_more": bool}`, do mais novo para o mais antigo. Use `limit` (1 a 100, padrão 20) e, para a próxima página, passe o `id` do último objeto recebido em `starting_after`. Pare quando `has_more` for `false`.

```bash
curl "https://evolutionboost.xyz/api/v1/keys?status=free&limit=100&starting_after=6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b" \
  -H "Authorization: Bearer $EVB_API_KEY"
```

## Idempotência

Todo `POST` que movimenta dinheiro ou cria keys exige o cabeçalho `Idempotency-Key`. Gere um UUID novo para cada operação e reutilize-o só para repetir aquela mesma operação (timeout, erro de rede, 5xx). A repetição nunca cobra duas vezes: devolve o resultado original.

- `POST /keys` repetido com a mesma chave e o mesmo corpo: `200` com o mesmo lote e o cabeçalho `Idempotent-Replayed: true` (a primeira chamada devolve `201`).
- `POST /deposits` repetido com a mesma chave e o mesmo valor: `200` com o mesmo depósito e o mesmo código PIX (sem nova cobrança).
- Mesma chave com outro corpo: `409 idempotency_key_reused`.
- As chaves valem por revendedor e não expiram. Nunca reutilize uma chave em uma operação nova.

## Limites de taxa

Os limites contam por chave de API (falhas de autenticação, por IP). Ao passar do limite você recebe `429 rate_limit_exceeded` com o cabeçalho `Retry-After` em segundos. Espere esse tempo antes de repetir.

- Leitura (todos os GET): 120 por minuto, por chave de API
- POST /keys: 30 por minuto, por chave de API
- POST /deposits: 5 por 5 minutos, por chave de API
- Falhas de autenticação: 20 por minuto, por IP

## Guia rápido

O fluxo recomendado, do saldo zerado até as keys na mão:

1. Veja o que você pode vender e o seu saldo: `GET /packages` e `GET /balance`.
2. Coloque saldo: `POST /deposits` com `amount_cents` (R$ 10,00 a R$ 5.000,00). Pague o `br_code` devolvido (PIX copia e cola) ou o QR em `br_code_base64` e consulte `GET /deposits/{id}` a cada 5 a 10 segundos até `status` ser `paid`.
3. Compre keys: `POST /keys` com `items` e uma `Idempotency-Key` nova. A resposta traz o texto completo de cada key.
4. Acompanhe: `GET /keys?status=free` (ainda não resgatadas) ou `GET /keys?status=redeemed`.

```bash
export EVB_API_KEY="evb_live_..."

# 1. Packages and balance
curl https://evolutionboost.xyz/api/v1/packages -H "Authorization: Bearer $EVB_API_KEY"
curl https://evolutionboost.xyz/api/v1/balance -H "Authorization: Bearer $EVB_API_KEY"

# 2. Deposit R$ 500,00, pay the PIX, poll until "paid"
curl -X POST https://evolutionboost.xyz/api/v1/deposits \
  -H "Authorization: Bearer $EVB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount_cents": 50000}'
curl https://evolutionboost.xyz/api/v1/deposits/9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b -H "Authorization: Bearer $EVB_API_KEY"

# 3. Buy 10 keys of H150
curl -X POST https://evolutionboost.xyz/api/v1/keys \
  -H "Authorization: Bearer $EVB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"package_code": "H150", "quantity": 10}]}'

# 4. Keys not redeemed yet
curl "https://evolutionboost.xyz/api/v1/keys?status=free" -H "Authorization: Bearer $EVB_API_KEY"
```

## Referência da API

### Me

Quem você é: revendedor, chave em uso e saldo. Uma boa primeira chamada para testar a integração.

#### O objeto Reseller

O revendedor dono da chave de API.

- object (string (reseller)): Sempre `reseller`.
- id (string): Id do revendedor.
- name (string): Nome de exibição.
- code (string): Código do revendedor. É a primeira parte das keys que você compra.
- status (string (active | revoked)): Só revendedores `active` podem usar a API.
- token (TokenInfo): A chave de API usada nesta requisição.
- balance (Balance): Saldo atual.

#### GET /me — Consultar o revendedor

Devolve o revendedor dono da chave, a chave usada e o saldo atual.

Limite de taxa: 120 por minuto, por chave de API.

Exemplos de requisição:

curl:
```bash
curl https://evolutionboost.xyz/api/v1/me \
  -H "Authorization: Bearer $EVB_API_KEY"
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/me', {
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import requests

response = requests.get(
    "https://evolutionboost.xyz/api/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — O revendedor.
```json
{
  "object": "reseller",
  "id": "5f0c2a3e-8d41-4b6a-9e2f-1c7d3b9a6e10",
  "name": "ACME Games",
  "code": "ACME",
  "status": "active",
  "token": {
    "name": "Store backend",
    "prefix": "xxxxxxxx"
  },
  "balance": {
    "object": "balance",
    "balance_cents": 125000,
    "currency": "BRL",
    "updated_at": "2026-10-17T14:10:03.000Z"
  }
}
```

Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

### Pacotes

Planos disponíveis para revendedores, com o seu preço de atacado.

#### O objeto Package

Um plano do qual você pode comprar keys, com o seu preço de atacado.

- object (string (package)): Sempre `package`.
- code (string): Código do pacote usado em `POST /keys` (por exemplo `H150`).
- hours (integer): Horas de farm que uma key concede.
- account_limit (integer): Contas Steam que o cliente pode farmar ao mesmo tempo.
- price_cents (integer): O seu preço de atacado por key, em centavos de real.
- currency (string (BRL)): Sempre `BRL`.

#### GET /packages — Listar pacotes

Lista os pacotes dos quais você pode comprar keys, com o seu preço de atacado por key. Pacotes sem preço de atacado não aparecem e não podem ser comprados. Sem paginação (`has_more` é sempre `false`).

Limite de taxa: 120 por minuto, por chave de API.

Exemplos de requisição:

curl:
```bash
curl https://evolutionboost.xyz/api/v1/packages \
  -H "Authorization: Bearer $EVB_API_KEY"
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/packages', {
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import requests

response = requests.get(
    "https://evolutionboost.xyz/api/v1/packages",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — A lista de pacotes.
```json
{
  "object": "list",
  "data": [
    {
      "object": "package",
      "code": "H150",
      "hours": 150,
      "account_limit": 3,
      "price_cents": 499,
      "currency": "BRL"
    },
    {
      "object": "package",
      "code": "H600",
      "hours": 600,
      "account_limit": 6,
      "price_cents": 1099,
      "currency": "BRL"
    },
    {
      "object": "package",
      "code": "H1200",
      "hours": 1200,
      "account_limit": 12,
      "price_cents": 1899,
      "currency": "BRL"
    }
  ],
  "has_more": false
}
```

Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

### Saldo

O seu saldo pré-pago em reais. Depósitos creditam; compras de keys debitam.

#### O objeto Balance

O saldo atual da carteira do revendedor.

- object (string (balance)): Sempre `balance`.
- balance_cents (integer): Saldo disponível em centavos de real.
- currency (string (BRL)): Sempre `BRL`.
- updated_at (string | null): Última alteração do saldo; `null` se a carteira nunca foi usada.

#### GET /balance — Consultar o saldo

Devolve o saldo atual da sua carteira, em centavos de real.

Limite de taxa: 120 por minuto, por chave de API.

Exemplos de requisição:

curl:
```bash
curl https://evolutionboost.xyz/api/v1/balance \
  -H "Authorization: Bearer $EVB_API_KEY"
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/balance', {
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import requests

response = requests.get(
    "https://evolutionboost.xyz/api/v1/balance",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — O saldo.
```json
{
  "object": "balance",
  "balance_cents": 125000,
  "currency": "BRL",
  "updated_at": "2026-10-17T14:10:03.000Z"
}
```

Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

### Extrato

Todos os movimentos de saldo, imutáveis, com o saldo depois de cada um.

#### O objeto LedgerEntry

Um movimento de saldo imutável.

- object (string (ledger_entry)): Sempre `ledger_entry`.
- id (string): Id do movimento (também é o cursor de paginação).
- kind (string (deposit | key_purchase | adjustment | refund)): `deposit` (PIX pago), `key_purchase` (compra de keys), `adjustment` (manual, pela equipe do Evolution Boost) ou `refund` (estorno).
- amount_cents (integer): Valor com sinal: positivo credita, negativo debita.
- balance_after_cents (integer): Saldo logo depois deste movimento.
- currency (string (BRL)): Sempre `BRL`.
- ref_type (string | null): O que originou, por exemplo `deposit` ou `key_batch`; em geral `null` em ajustes.
- ref_id (string | null): Id do depósito ou do lote de keys.
- description (string | null): Descrição curta.
- created_at (string): Quando o movimento aconteceu.

#### GET /ledger — Listar o extrato

Lista os movimentos de saldo, do mais novo para o mais antigo. Paginado.

Limite de taxa: 120 por minuto, por chave de API.

Parâmetros:
- limit [query, integer, opcional]: Quantidade de objetos por página, de 1 a 100. Padrão 20.
- starting_after [query, string, opcional]: Cursor: o `id` do último objeto da página anterior. Devolve os objetos que vêm depois dele.
- kind [query, string (deposit | key_purchase | adjustment | refund), opcional]: Só movimentos deste tipo.

Exemplos de requisição:

curl:
```bash
curl "https://evolutionboost.xyz/api/v1/ledger?kind=key_purchase&limit=20" \
  -H "Authorization: Bearer $EVB_API_KEY"
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/ledger?kind=key_purchase&limit=20', {
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import requests

response = requests.get(
    "https://evolutionboost.xyz/api/v1/ledger?kind=key_purchase&limit=20",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — Uma página do extrato.
```json
{
  "object": "list",
  "data": [
    {
      "object": "ledger_entry",
      "id": "7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a",
      "kind": "key_purchase",
      "amount_cents": -5990,
      "balance_after_cents": 125000,
      "currency": "BRL",
      "ref_type": "key_batch",
      "ref_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "description": "10x H150, 1x H600",
      "created_at": "2026-10-17T14:10:03.000Z"
    },
    {
      "object": "ledger_entry",
      "id": "2e3f4a5b-6c7d-4e8f-a9b0-c1d2e3f4a5b6",
      "kind": "deposit",
      "amount_cents": 50000,
      "balance_after_cents": 130990,
      "currency": "BRL",
      "ref_type": "deposit",
      "ref_id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
      "description": "Deposito PIX",
      "created_at": "2026-10-17T14:02:41.000Z"
    }
  ],
  "has_more": true
}
```

Erros:
- 400 invalid_limit: `limit` deve ser um inteiro entre 1 e 100.
- 400 invalid_cursor: `starting_after` não é um UUID ou não é um objeto desta lista.
- 400 invalid_kind: Valor desconhecido no filtro `kind`.
Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

### Depósitos

Cobranças PIX que creditam o seu saldo. De R$ 10,00 a R$ 5.000,00 cada, no máximo 3 pendentes ao mesmo tempo.

#### O objeto Deposit

Uma cobrança PIX que credita o seu saldo depois de paga.

- object (string (deposit)): Sempre `deposit`.
- id (string): Id do depósito.
- amount_cents (integer): Valor em centavos de real.
- currency (string (BRL)): Sempre `BRL`.
- status (string (pending | paid | failed | expired)): `pending` até o PIX ser pago; `paid` significa que o saldo foi creditado; `failed` ou `expired` nunca serão creditados.
- br_code (string | null): Código PIX copia e cola. Só enquanto `pending`.
- br_code_base64 (string | null): QR code em data URL PNG (`data:image/png;base64,...`). Só enquanto `pending`.
- expires_at (string | null): Quando a cobrança PIX expira (definido pelo provedor de pagamento).
- created_at (string): Data de criação.
- paid_at (string | null): Quando o pagamento foi confirmado.

#### POST /deposits — Criar um depósito

Cria uma cobrança PIX de `amount_cents`. Pague o `br_code` (copia e cola) ou o QR em `br_code_base64`; o saldo é creditado sozinho quando o pagamento é confirmado. Depois consulte `GET /deposits/{id}`. No máximo 3 depósitos pendentes ao mesmo tempo.

Limite de taxa: 5 por 5 minutos, por chave de API.

Parâmetros:
- Idempotency-Key [header, string, obrigatório]: Chave única por operação (um UUID é o ideal), de 1 a 255 caracteres ASCII visíveis. Repetir com a mesma chave nunca cobra duas vezes.

Corpo (JSON):
- amount_cents [integer, obrigatório]: Valor em centavos de real, de 1000 (R$ 10,00) a 500000 (R$ 5.000,00).

Exemplos de requisição:

curl:
```bash
curl -X POST https://evolutionboost.xyz/api/v1/deposits \
  -H "Authorization: Bearer $EVB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount_cents":50000}'
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/deposits', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it only to retry this same call
  },
  body: JSON.stringify({
    "amount_cents": 50000
  }),
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import uuid
import requests

response = requests.post(
    "https://evolutionboost.xyz/api/v1/deposits",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it only to retry this same call
    },
    json={
      "amount_cents": 50000
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — O depósito pendente com o código PIX. Repetir com a mesma `Idempotency-Key` devolve o mesmo depósito.
```json
{
  "object": "deposit",
  "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
  "amount_cents": 50000,
  "currency": "BRL",
  "status": "pending",
  "br_code": "00020101021226850014br.gov.bcb.pix...6304A1B2",
  "br_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "expires_at": "2026-10-18T14:00:00.000Z",
  "created_at": "2026-10-17T14:00:00.000Z",
  "paid_at": null
}
```

Erros:
- 400 idempotency_key_required: POST sem o cabeçalho `Idempotency-Key`.
- 400 invalid_idempotency_key: `Idempotency-Key` deve ter de 1 a 255 caracteres ASCII visíveis, sem espaços.
- 400 invalid_json: O corpo está vazio, não é JSON ou não é um objeto JSON.
- 400 invalid_amount: `amount_cents` deve ser um inteiro entre 1000 e 500000.
- 400 too_many_pending_deposits: Você já tem 3 depósitos pendentes. Pague um ou espere expirar.
- 409 idempotency_key_reused: A `Idempotency-Key` já foi usada com outro corpo. Use uma chave nova para uma operação nova.
- 413 payload_too_large: O corpo passa de 24000 bytes.
- 502 payment_provider_error: O provedor PIX falhou ao criar a cobrança. Tente mais tarde.
Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

#### GET /deposits/{id} — Consultar um depósito

Devolve um depósito. Enquanto ele está `pending`, esta chamada também confere o pagamento com o provedor PIX; consultar a cada 5 a 10 segundos é o jeito de saber que o saldo foi creditado. Depósito de outro revendedor devolve 404.

Limite de taxa: 120 por minuto, por chave de API.

Parâmetros:
- id [path, string, obrigatório]: Id do depósito.

Exemplos de requisição:

curl:
```bash
curl https://evolutionboost.xyz/api/v1/deposits/9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b \
  -H "Authorization: Bearer $EVB_API_KEY"
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/deposits/9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b', {
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import requests

response = requests.get(
    "https://evolutionboost.xyz/api/v1/deposits/9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — O depósito.
```json
{
  "object": "deposit",
  "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
  "amount_cents": 50000,
  "currency": "BRL",
  "status": "paid",
  "br_code": null,
  "br_code_base64": null,
  "expires_at": "2026-10-18T14:00:00.000Z",
  "created_at": "2026-10-17T14:00:00.000Z",
  "paid_at": "2026-10-17T14:02:41.000Z"
}
```

Erros:
- 404 resource_missing: O objeto não existe ou é de outro revendedor (mesma resposta), ou o endpoint não existe.
Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

#### GET /deposits — Listar depósitos

Lista os seus depósitos, do mais novo para o mais antigo. Paginado. Diferente de `GET /deposits/{id}`, a lista não confere pagamentos pendentes no provedor.

Limite de taxa: 120 por minuto, por chave de API.

Parâmetros:
- limit [query, integer, opcional]: Quantidade de objetos por página, de 1 a 100. Padrão 20.
- starting_after [query, string, opcional]: Cursor: o `id` do último objeto da página anterior. Devolve os objetos que vêm depois dele.
- status [query, string (pending | paid | failed | expired), opcional]: Só depósitos com este status.

Exemplos de requisição:

curl:
```bash
curl "https://evolutionboost.xyz/api/v1/deposits?status=paid&limit=20" \
  -H "Authorization: Bearer $EVB_API_KEY"
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/deposits?status=paid&limit=20', {
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import requests

response = requests.get(
    "https://evolutionboost.xyz/api/v1/deposits?status=paid&limit=20",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — Uma página de depósitos.
```json
{
  "object": "list",
  "data": [
    {
      "object": "deposit",
      "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
      "amount_cents": 50000,
      "currency": "BRL",
      "status": "paid",
      "br_code": null,
      "br_code_base64": null,
      "expires_at": "2026-10-18T14:00:00.000Z",
      "created_at": "2026-10-17T14:00:00.000Z",
      "paid_at": "2026-10-17T14:02:41.000Z"
    },
    {
      "object": "deposit",
      "id": "3c8f1a20-6b7d-4e9f-8a1b-2c3d4e5f6a7b",
      "amount_cents": 100000,
      "currency": "BRL",
      "status": "paid",
      "br_code": null,
      "br_code_base64": null,
      "expires_at": "2026-10-11T09:00:00.000Z",
      "created_at": "2026-10-10T09:00:00.000Z",
      "paid_at": "2026-10-10T09:01:15.000Z"
    }
  ],
  "has_more": false
}
```

Erros:
- 400 invalid_limit: `limit` deve ser um inteiro entre 1 e 100.
- 400 invalid_cursor: `starting_after` não é um UUID ou não é um objeto desta lista.
- 400 invalid_status: Valor desconhecido no filtro `status`.
Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

### Keys

Compre keys de licença com o seu saldo e consulte as keys que são suas.

#### O objeto Key

Uma key de licença que pertence a você.

- object (string (key)): Sempre `key`.
- id (string): Id da key (também é o cursor de paginação).
- key (string | null): Texto completo da key. `null` em keys antigas que não podem ser recuperadas (use `key_prefix`).
- key_prefix (string): As três primeiras partes da key, seguras para exibir.
- package_code (string): Pacote da key.
- hours (integer | null): Horas concedidas pela key.
- status (string (free | redeemed | revoked | suspended)): `free` (ainda não resgatada), `redeemed` (resgatada), `revoked` (revogada) ou `suspended` (suspensa).
- batch_id (string | null): Lote de compra que criou a key.
- created_at (string): Data de criação.
- redeemed_at (string | null): Quando um cliente resgatou.

#### POST /keys — Comprar keys

Debita o preço de atacado do seu saldo e cria as keys em uma única operação atômica. Se o saldo não bastar, nada é cobrado nem criado (`402 insufficient_balance`). Até 100 keys e 50 itens por requisição. A resposta traz o texto completo de cada key.

Limite de taxa: 30 por minuto, por chave de API.

Parâmetros:
- Idempotency-Key [header, string, obrigatório]: Chave única por operação (um UUID é o ideal), de 1 a 255 caracteres ASCII visíveis. Repetir com a mesma chave nunca cobra duas vezes.

Corpo (JSON):
- items [PurchaseItem[], obrigatório]: O que comprar: de 1 a 50 objetos `{package_code, quantity}`, cada pacote uma vez só.
- items[].package_code [string, obrigatório]: Código do pacote de `GET /packages`.
- items[].quantity [integer, opcional]: Quantidade de keys, de 1 a 100. Padrão 1.
Para um único pacote você também pode enviar `{"package_code": "H150", "quantity": 10}` em vez de `items`.

Exemplos de requisição:

curl:
```bash
curl -X POST https://evolutionboost.xyz/api/v1/keys \
  -H "Authorization: Bearer $EVB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items":[{"package_code":"H150","quantity":2},{"package_code":"H600","quantity":1}]}'
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/keys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it only to retry this same call
  },
  body: JSON.stringify({
    "items": [
      {
        "package_code": "H150",
        "quantity": 2
      },
      {
        "package_code": "H600",
        "quantity": 1
      }
    ]
  }),
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import uuid
import requests

response = requests.post(
    "https://evolutionboost.xyz/api/v1/keys",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it only to retry this same call
    },
    json={
      "items": [
        {
          "package_code": "H150",
          "quantity": 2
        },
        {
          "package_code": "H600",
          "quantity": 1
        }
      ]
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 201 — O lote foi comprado.
```json
{
  "object": "key_batch",
  "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
  "total_cents": 2097,
  "balance_cents": 122903,
  "currency": "BRL",
  "keys": [
    {
      "object": "key",
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA",
      "key_prefix": "ACME-H150-AAAA",
      "package_code": "H150",
      "hours": 150,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    },
    {
      "object": "key",
      "id": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b",
      "key": "ACME-H150-BBBB-BBBB-BBBB-BBBB",
      "key_prefix": "ACME-H150-BBBB",
      "package_code": "H150",
      "hours": 150,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    },
    {
      "object": "key",
      "id": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e",
      "key": "ACME-H600-CCCC-CCCC-CCCC-CCCC",
      "key_prefix": "ACME-H600-CCCC",
      "package_code": "H600",
      "hours": 600,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    }
  ]
}
```

HTTP 200 — Repetição com a mesma `Idempotency-Key` e o mesmo corpo: o lote original, sem nova cobrança.
Idempotent-Replayed: `true` quando a resposta é uma repetição.
(mesmo corpo da resposta acima)

Erros:
- 400 idempotency_key_required: POST sem o cabeçalho `Idempotency-Key`.
- 400 invalid_idempotency_key: `Idempotency-Key` deve ter de 1 a 255 caracteres ASCII visíveis, sem espaços.
- 400 invalid_json: O corpo está vazio, não é JSON ou não é um objeto JSON.
- 400 missing_items: Envie `items` (não vazio) ou `package_code`.
- 400 invalid_items: `items` deve ser uma lista de objetos.
- 400 too_many_items: `items` aceita no máximo 50 itens.
- 400 invalid_package_code: `package_code` deve ter o formato `H150` (1 a 20 letras ou dígitos).
- 400 invalid_quantity: `quantity` deve ser um inteiro entre 1 e 100.
- 400 duplicate_package: O mesmo pacote aparece duas vezes em `items`. Some as quantidades.
- 400 too_many_keys: Uma requisição cria no máximo 100 keys no total.
- 400 package_unavailable: O pacote não existe ou não tem preço de atacado. Veja `GET /packages`.
- 402 insufficient_balance: O saldo não cobre o total da compra. Nada foi cobrado nem criado.
- 409 idempotency_key_reused: A `Idempotency-Key` já foi usada com outro corpo. Use uma chave nova para uma operação nova.
- 413 payload_too_large: O corpo passa de 24000 bytes.
Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

#### GET /keys — Listar keys

Lista as suas keys, da mais nova para a mais antiga. Paginado. Filtre por status (`free` = ainda não resgatada), pacote ou lote de compra. Respostas que trazem o texto da key são auditadas.

Limite de taxa: 120 por minuto, por chave de API.

Parâmetros:
- limit [query, integer, opcional]: Quantidade de objetos por página, de 1 a 100. Padrão 20.
- starting_after [query, string, opcional]: Cursor: o `id` do último objeto da página anterior. Devolve os objetos que vêm depois dele.
- status [query, string (free | redeemed | all), opcional]: `free` (não resgatadas), `redeemed` (resgatadas) ou `all` (padrão; inclui também revogadas e suspensas).
- package_code [query, string, opcional]: Só keys deste pacote.
- batch_id [query, string, opcional]: Só keys deste lote de compra.

Exemplos de requisição:

curl:
```bash
curl "https://evolutionboost.xyz/api/v1/keys?status=free&package_code=H150&limit=50" \
  -H "Authorization: Bearer $EVB_API_KEY"
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/keys?status=free&package_code=H150&limit=50', {
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import requests

response = requests.get(
    "https://evolutionboost.xyz/api/v1/keys?status=free&package_code=H150&limit=50",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — Uma página de keys.
```json
{
  "object": "list",
  "data": [
    {
      "object": "key",
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA",
      "key_prefix": "ACME-H150-AAAA",
      "package_code": "H150",
      "hours": 150,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    },
    {
      "object": "key",
      "id": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b",
      "key": "ACME-H150-BBBB-BBBB-BBBB-BBBB",
      "key_prefix": "ACME-H150-BBBB",
      "package_code": "H150",
      "hours": 150,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    }
  ],
  "has_more": true
}
```

Erros:
- 400 invalid_limit: `limit` deve ser um inteiro entre 1 e 100.
- 400 invalid_cursor: `starting_after` não é um UUID ou não é um objeto desta lista.
- 400 invalid_status: Valor desconhecido no filtro `status`.
- 400 invalid_package_code: `package_code` deve ter o formato `H150` (1 a 20 letras ou dígitos).
- 400 invalid_batch_id: `batch_id` deve ser um UUID.
Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

#### GET /keys/{id} — Consultar uma key

Devolve uma key pelo `id` (UUID). Para saber se uma key vendida já foi resgatada, pegue o `id` dela em `GET /keys`: o texto da key nunca vai na URL, onde proxies e logs poderiam registrá-lo. Key de outro revendedor, id inexistente ou valor malformado devolvem o mesmo 404. Respostas que trazem o texto da key são auditadas.

Limite de taxa: 120 por minuto, por chave de API.

Parâmetros:
- id [path, string, obrigatório]: Id da key (UUID), como devolvido por GET /keys ou POST /keys.

Exemplos de requisição:

curl:
```bash
curl https://evolutionboost.xyz/api/v1/keys/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $EVB_API_KEY"
```

Node.js:
```js
const response = await fetch('https://evolutionboost.xyz/api/v1/keys/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d', {
  headers: {
    Authorization: `Bearer ${process.env.EVB_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

Python:
```python
import os
import requests

response = requests.get(
    "https://evolutionboost.xyz/api/v1/keys/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    headers={
        "Authorization": f"Bearer {os.environ['EVB_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

Respostas:

HTTP 200 — A key.
```json
{
  "object": "key",
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA",
  "key_prefix": "ACME-H150-AAAA",
  "package_code": "H150",
  "hours": 150,
  "status": "redeemed",
  "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
  "created_at": "2026-10-17T14:10:03.000Z",
  "redeemed_at": "2026-10-17T18:22:09.000Z"
}
```

Erros:
- 404 resource_missing: O objeto não existe ou é de outro revendedor (mesma resposta), ou o endpoint não existe.
Além dos erros comuns: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.