Початок роботи

Вступ

Розміщуйте та відстежуйте замовлення цифрових товарів програмно через API Voodoo Center

View as Markdown

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}. Повний процес описано в розділах Розміщення замовлень і Webhooks.

Швидкий старт

1

Створення API-ключа

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

2

Обмін ключа на токен доступу

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

Обмін вашого 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"}'
Відповідь
1{
2  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
3  "token_type": "Bearer"
4}
3

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

Надсилайте токен як Bearer-облікові дані в кожному запиті до API:

Розміщення замовлення
$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 — описано в розділі Швидкий старт.

Спробуйте у браузері

Вкладка API Reference містить інтерактивний API Explorer («try it») для кожного ендпоінта. Вам не потрібно вручну реалізовувати процес автентифікації: введіть лише свій API-ключ ak_ один раз, і Explorer автоматично обміняє його на Bearer-токен доступу та додасть до ваших запитів. Жодного JWT копіювати чи вставляти не потрібно.

Швидкий старт

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

Автентифікація

Перетворіть ключ ak_ на Bearer-токен і вчасно оновлюйте його.

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

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

Webhooks

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

Помилки

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