> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voodoo.center/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voodoo.center/_mcp/server.

# Введение

API Voodoo Center позволяет покупать цифровые товары — ключи подарочных карт,
пополнения и игровые сервисы — прямо из ваших систем. Вы создаёте заказ, мы
списываем средства с баланса вашего аккаунта, выполнение происходит асинхронно,
а результат доставляется на ваш webhook (и его всегда можно прочитать обратно
через API).

## Базовый URL

Все запросы к API отправляются на единый хост:

```
https://api.voodoo.center
```

Эндпоинты аутентификации используют тот же хост по пути `/api/v1/auth`.

## Что умеет API

Программный API намеренно небольшой — три эндпоинта:

| Возможность               | Эндпоинт                      |
| ------------------------- | ----------------------------- |
| Проверить баланс аккаунта | `GET /api/v1/account/balance` |
| Разместить заказ          | `POST /api/v1/orders`         |
| Получить заказ            | `GET /api/v1/orders/{id}`     |

Всё остальное — просмотр каталога, избранное, депозиты, тикеты, управление
командой и подпиской, а также **получение списка** заказов — доступно в
дашборде и **не** является частью программного API. `item_id`, тип продукта,
границы количества и поля ввода, необходимые для заказа, узнавайте из
**экспорта каталога** (отдельный канал данных, а не эндпоинт API).

## Как работает заказ

`POST /api/v1/orders` списывает средства с вашего баланса и сразу возвращает
`201` со `status: "pending"`. Далее выполнение происходит в фоне, и заказ
завершается одним из терминальных статусов:

* **`completed`** — доставлено полностью. Для товаров типа key поле `codes`
  содержит строки доставленных ключей.
* **`partial`** — доставлена часть единиц; `refund_amount` — это возврат средств
  за недоставленную часть.
* **`failed`** — ничего не доставлено; списание возвращается, а `error` /
  `error_message` объясняют причину.

Узнать окончательный результат можно двумя способами: через ваш **webhook**
(рекомендуется — push, без опроса) или прочитав `GET /api/v1/orders/{id}`.
Полный процесс описан в разделах [Размещение заказов](/orders) и
[Webhooks](/webhooks).

## Быстрый старт

В дашборде откройте страницу **API** и создайте ключ. Сырой ключ
(формат `ak_...`) показывается **один раз** — скопируйте его сразу.

Обменяйте свой ключ `ak_` на короткоживущий Bearer-токен (действителен **2 часа**):

```bash title="Обмен вашего API-ключа"
curl -X POST https://api.voodoo.center/api/v1/auth/token/client \
  -H "Content-Type: application/json" \
  -d '{"api_key":"ak_your_api_key_here"}'
```

```json title="Ответ"
{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer"
}
```

Отправляйте токен как Bearer-учётные данные в каждом запросе к API:

```bash title="Размещение заказа"
curl -X POST https://api.voodoo.center/api/v1/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"item_id": 4090, "quantity": 2, "merchant_order_id": "po-10231"}'
```

В ответ вы получите `201` со `status: "pending"`. Ожидайте терминальный
статус на вашем webhook или опрашивайте `GET /api/v1/orders/{id}`.

Полный сквозной процесс — включая настройку и проверку webhook — описан в
разделе [Быстрый старт](/quickstart).

## Попробуйте в браузере

Вкладка **[API Reference](/api-reference)** содержит интерактивный **API Explorer**
(«try it») для каждого эндпоинта. Вам не нужно вручную реализовывать процесс
аутентификации: введите **только свой API-ключ `ak_`** один раз, и Explorer
автоматически обменяет его на Bearer-токен доступа и добавит к вашим запросам.
Никакой JWT копировать или вставлять не нужно.

Ключ → токен → заказ → webhook, от начала до конца, с готовыми cURL для копирования.

Превратите ключ `ak_` в Bearer-токен и вовремя обновляйте его.

Типы товаров, поля, правила количества и жизненный цикл заказа.

Получайте и проверяйте события терминального статуса ваших заказов.

Конверт ошибки, коды статусов и семантика сбоев.