Розміщення замовлень

Розміщення замовлення — це єдиний виклик POST /api/v1/orders. Він списує кошти з балансу вашого акаунта й одразу повертає 201 зі status: "pending". Виконання відбувається асинхронно — кінцевий результат надходить на ваш webhook і завжди доступний для читання з GET /api/v1/orders/{id}.

Типи товарів

Кожен товар каталогу має тип продукту, який визначає, що ви маєте надіслати:

Поля запиту

• item_id (ціле число, обовʼязково) — числовий id товару з каталогу.
• quantity (число) — див. таблицю типів товарів вище. Має бути в межах діапазону min/max товару.
  • key: ціла кількість (за замовчуванням 1).
  • topup: десяткова сума (обовʼязково).
  • service: пропустіть — вона завжди 1.
• merchant_order_id (рядок, необовʼязково) — ваш власний ідентифікатор, унікальний у межах акаунта. Використовуйте його для ідемпотентності та для звʼязування подій webhook із вашими записами.
• fields (обʼєкт) — обовʼязкові лише для товарів topup і service, індексовані за іменами полів товару. Товари key не приймають fields.

Значення полів: текст проти вибору

Кожне поле товару є або текстовим полем, або полем вибору:

• Текстове поле → надсилайте значення як рядок (наприклад, "player_id": "123456789").
• Поле вибору → надсилайте числовий id вибору, а не мітку (наприклад, "server": 17, де 17 — це id вибору «Europe (EU-West)»).

Створення замовлення

$
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"
>
  }'

$
curl -X POST https://api.voodoo.center/api/v1/orders \
>
  -H "Authorization: Bearer <access_token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "item_id": 4211,
>
    "quantity": 10,
>
    "merchant_order_id": "po-10232",
>
    "fields": { "player_id": "123456789", "server": 17 }
>
  }'

$
curl -X POST https://api.voodoo.center/api/v1/orders \
>
  -H "Authorization: Bearer <access_token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "item_id": 5000,
>
    "merchant_order_id": "po-10233",
>
    "fields": { "account_email": "[email protected]" }
>
  }'

Успішне створення повертає 201 із замовленням у стані pending:

1
{
2
  "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
3
  "item": 4211,
4
  "item_name": "Sample Game Top-up",
5
  "item_product_type": "topup",
6
  "quantity": 10,
7
  "delivered_quantity": 0,
8
  "price": 12.50,
9
  "refund_amount": 0,
10
  "fields": { "player_id": "123456789", "server": "Europe (EU-West)" },
11
  "status": "pending",
12
  "error": "",
13
  "error_message": "",
14
  "codes": [],
15
  "merchant_order_id": "po-10232",
16
  "source": "api",
17
  "created_by": { "id": "0190f8a0-1111-7000-8000-000000000001", "email": "[email protected]" },
18
  "created_at": "2026-07-05T12:00:00Z",
19
  "completed_at": null
20
}

Життєвий цикл замовлення

Замовлення починається у стані pending, може ненадовго перейти в processing, а потім завершується одним із трьох термінальних статусів:

• codes — рядки доставлених ключів, для товарів типу key.
• refund_amount — сума, повернута за недоставлені одиниці для замовлення partial або failed.
• error / error_message — встановлюються, коли status дорівнює failed (наприклад, error: "OUT_OF_STOCK").

Читання замовлення

Отримайте поточний стан будь-якого зі своїх замовлень за допомогою GET /api/v1/orders/{id}:

$
curl https://api.voodoo.center/api/v1/orders/0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b \
>
  -H "Authorization: Bearer <access_token>"

1
{
2
  "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
3
  "item": 4090,
4
  "item_name": "Sample Gift Card 10 USD",
5
  "item_product_type": "key",
6
  "quantity": 2,
7
  "delivered_quantity": 2,
8
  "price": 18.00,
9
  "refund_amount": 0,
10
  "fields": {},
11
  "status": "completed",
12
  "error": "",
13
  "error_message": "",
14
  "codes": ["ABCD-1234-EFGH-5678", "IJKL-9012-MNOP-3456"],
15
  "merchant_order_id": "po-10231",
16
  "source": "api",
17
  "created_by": { "id": "0190f8a0-1111-7000-8000-000000000001", "email": "[email protected]" },
18
  "created_at": "2026-07-05T12:00:00Z",
19
  "completed_at": "2026-07-05T12:00:07Z"
20
}

Webhook проти опитування

Надавайте перевагу webhook: Voodoo Center надсилає термінальну подію на вашу URL, щойно замовлення завершується — опитування не потрібне. Опитування GET /api/v1/orders/{id} — це прийнятний запасний варіант (наприклад, якщо доставку webhook було пропущено), але webhook — це шлях із меншою затримкою та меншим навантаженням.