Размещение заказов

Размещение заказа — это единственный вызов 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 — это путь с меньшей задержкой и меньшей нагрузкой.