> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voodoo.center/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voodoo.center/_mcp/server.

# Быстрый старт

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

**Базовый URL** — `https://api.voodoo.center` (только HTTPS). Эндпоинты
аутентификации размещены на том же хосте по пути `/api/v1/auth`.

## Предварительные требования

* Аккаунт Voodoo Center с пополненным балансом.
* Доступ к странице **API** в дашборде (чтобы создать ключ и настроить webhook).
* Товар для покупки — его `item_id`, тип продукта, границы количества и поля
  ввода вы получаете из **экспорта каталога** (см. [Размещение заказов](/orders)).

В дашборде откройте страницу **API** и создайте ключ. Сырой ключ
(формат `ak_...`) показывается **один раз**, при создании — скопируйте его
сразу и сохраните как секрет. Вы можете отзывать и создавать ключи здесь
в любое время.

На той же странице **API** укажите свой **Webhook URL** (публично доступный
по HTTPS) и скопируйте **секрет для подписи** (`whsec_...`, тоже показывается
один раз). Именно сюда отправляются окончательные результаты заказов. Вы
можете пропустить этот шаг и использовать опрос, но webhook — это путь с
меньшей задержкой.

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

```bash title="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"}'
```

```json title="Ответ"
{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer"
}
```

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

```bash title="2 — Убедитесь, что аутентификация работает"
curl https://api.voodoo.center/api/v1/account/balance \
  -H "Authorization: Bearer <access_token>"
```

```json title="Ответ"
{ "balance": 1240.75 }
```

Купите товар типа key. `POST /api/v1/orders` списывает средства с вашего
баланса и сразу возвращает `201` со `status: "pending"` — выполнение
происходит в фоне.

```bash title="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"
  }'
```

```json title="201 Created"
{
  "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
  "status": "pending",
  "merchant_order_id": "po-10231",
  "source": "api"
}
```

Всегда отправляйте уникальный `merchant_order_id` — это делает повторные попытки идемпотентными.

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

```json title="Webhook — выполненный заказ с ключами"
{
  "order_id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
  "merchant_order_id": "po-10231",
  "status": "completed",
  "delivered_quantity": 2,
  "refund_amount": 0,
  "codes": ["ABCD-1234-EFGH-5678", "IJKL-9012-MNOP-3456"]
}
```

Пока не хотите запускать webhook? Вместо этого опрашивайте
`GET /api/v1/orders/{id}`, пока `status` не станет терминальным.

## Попробуйте, не покидая документацию

Вкладка [API Reference](/api-reference) имеет живой **API Explorer** для каждого
эндпоинта. Он настроен получать токен доступа за вас — введите **только свой
API-ключ `ak_`** один раз, запустите любой эндпоинт, и Explorer получит свежий
Bearer-токен в фоне и добавит его автоматически. Вам никогда не придётся
вставлять JWT.

Процесс API-ключ → токен подробно, а также срок действия и обновление токена.

Типы товаров, поля, правила количества и жизненный цикл заказа.

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

Конверт ошибки и сбои при создании против асинхронных сбоев.