> 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-ключ,
обміняєте його на токен доступу, розмістите замовлення й отримаєте кінцевий
результат на ваш webhook. Кожен запит надсилається на єдину базову URL-адресу:

**Базова URL-адреса** — `https://api.voodoo.center` (лише HTTPS). Ендпоінти
автентифікації розміщені на тому самому хості за шляхом `/api/v1/auth`.

## Передумови

* Акаунт Voodoo Center із поповненим балансом.
* Доступ до сторінки **API** в дашборді (щоб створити ключ і налаштувати webhook).
* Товар для купівлі — його `item_id`, тип продукту, межі кількості та поля
  вводу ви отримуєте з **експорту каталогу** (див. [Розміщення замовлень](/orders)).

У дашборді відкрийте сторінку **API** та створіть ключ. Сирий ключ
(формат `ak_...`) показується **один раз**, під час створення — скопіюйте його
одразу й збережіть як секрет. Ви можете відкликати та створювати ключі тут
у будь-який час.

На тій самій сторінці **API** вкажіть свій **Webhook URL** (публічно
доступний через HTTPS) і скопіюйте **секрет для підпису** (`whsec_...`, теж
показується один раз). Саме сюди надсилаються кінцеві результати замовлень.
Ви можете пропустити цей крок і використовувати опитування, але webhook — це
шлях із меншою затримкою.

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

```bash title="1 — Отримання токена доступу"
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"
}
```

Надсилайте `access_token` як `Authorization: Bearer <access_token>` у кожному
іншому запиті. Обмінюйте ключ повторно, коли термін дії токена спливає.

```bash title="2 — Переконайтеся, що автентифікація працює"
curl https://api.voodoo.center/api/v1/account/balance \
  -H "Authorization: Bearer <access_token>"
```

```json title="Відповідь"
{ "balance": 1240.75 }
```

Купіть товар типу key. `POST /api/v1/orders` списує кошти з вашого балансу й
одразу повертає `201` зі `status: "pending"` — виконання відбувається у фоні.

```bash title="3 — Розміщення замовлення"
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"
  }'
```

```json title="201 Created"
{
  "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
  "status": "pending",
  "merchant_order_id": "po-10231",
  "source": "api"
}
```

Завжди надсилайте унікальний `merchant_order_id` — це робить повторні спроби ідемпотентними.

Коли замовлення завершується, Voodoo Center надсилає `POST` із підписаною
подією на вашу webhook-адресу. Перевірте `X-Webhook-Signature` щодо **сирого**
тіла запиту, а потім прочитайте кінцевий `status`, доставлені `codes` та будь-який
`refund_amount`:

```json title="Webhook — виконане замовлення з ключами"
{
  "order_id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
  "merchant_order_id": "po-10231",
  "status": "completed",
  "delivered_quantity": 2,
  "refund_amount": 0,
  "codes": ["ABCD-1234-EFGH-5678", "IJKL-9012-MNOP-3456"]
}
```

Поки не хочете запускати webhook? Замість цього опитуйте
`GET /api/v1/orders/{id}`, доки `status` не стане термінальним.

## Спробуйте, не залишаючи документацію

Вкладка [API Reference](/api-reference) має живий **API Explorer** для кожного
ендпоінта. Він налаштований отримувати токен доступу за вас — введіть **лише свій
API-ключ `ak_`** один раз, запустіть будь-який ендпоінт, і Explorer отримає свіжий
Bearer-токен у фоні та додасть його автоматично. Вам ніколи не доведеться вставляти JWT.

Процес API-ключ → токен детально, а також термін дії та оновлення токена.

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

Перевіряйте підписи та обробляйте повторні доставки ідемпотентно.

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