> 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-токен і вчасно оновлюйте його.

Типи товарів, поля, правила кількості та життєвий цикл замовлення.

Отримуйте та перевіряйте події термінального статусу ваших замовлень.

Конверт помилки, коди статусів і семантика збоїв.