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

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

Створіть ключ, отримайте токен, розмістіть замовлення та прийміть webhook — від початку до кінця

View as Markdown

Це найшвидший шлях від нуля до виконаного замовлення. Ви створите API-ключ, обміняєте його на токен доступу, розмістите замовлення й отримаєте кінцевий результат на ваш webhook. Кожен запит надсилається на єдину базову URL-адресу:

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

Передумови

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

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

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

2

Налаштування webhook (рекомендовано)

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

3

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

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

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

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

4

Перевірка балансу (необовʼязкова перевірка)

2 — Переконайтеся, що автентифікація працює
$curl https://api.voodoo.center/api/v1/account/balance \
>  -H "Authorization: Bearer <access_token>"
Відповідь
1{ "balance": 1240.75 }
5

Розміщення першого замовлення

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

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"
>  }'
201 Created
1{
2  "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
3  "status": "pending",
4  "merchant_order_id": "po-10231",
5  "source": "api"
6}

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

6

Отримання результату на webhook

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

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

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

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

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

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

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

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

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

Webhooks

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

Помилки

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