Начало работы

Введение

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

Просмотр в формате 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

Получайте и проверяйте события терминального статуса ваших заказов.

Ошибки

Конверт ошибки, коды статусов и семантика сбоев.