Интеграция для AI-агентов и разработчиков

Вариант 1: Быстрое подключение MCP (рекомендуется для AI-агентов)

Вставьте конфигурацию ниже в любой клиент с поддержкой MCP (Claude, Cursor и др.):

{
  "mcpServers": {
    "aibulk": {
      "url": "https://aibulk.uk/api/mcp",
      "headers": { "Authorization": "Bearer awk_your_key" }
    }
  }
}

Пользователи Claude Code могут выполнить напрямую:

claude mcp add --transport http aibulk https://aibulk.uk/api/mcp --header "Authorization: Bearer awk_your_key"

Инструменты: list_products / check_availability / get_balance / create_topup / purchase_codes / get_order / list_orders / list_transactions. Для заказов и пополнений требуются повторно используемые ID идемпотентности. Активация на стороне сервера пока доступна только через REST.

Вариант 2: REST API

Базовый URL REST: https://aibulk.uk/api — все пути API указываются относительно него, например GET https://aibulk.uk/api/wholesale/v1/products.

Полная документация API · llms.txt (руководство по интеграции для агентов) · openapi.json · История изменений (датированные изменения API)

Пример заказа с оплатой с баланса (синхронно возвращает список кодов):

curl -X POST https://aibulk.uk/api/wholesale/v1/orders \
  -H "Authorization: Bearer awk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"externalOrderId":"your-unique-id","productId":"<product-id>","qty":1,"payment":"balance"}'

Активация от имени клиента (серверное API активации)

Если вы сами собираете данные клиентов и активируете за них, не используйте публичные эндпоинты сайта активации (ограничены по IP). Используйте следующие эндпоинты с авторизацией по ключу:

• GET /wholesale/v1/products/:id → redeemFields подскажет, какие данные нужны до покупки (например, account_id = Claude Organization ID для prod_claude_pro); ключи в redeemInfo соответствуют redeemFields[].key.
• POST /wholesale/v1/redemptions {code, redeemInfo} → {redemptionId, status: pending}. Принимаются только коды из ваших собственных заказов (иначе 404 invalid_code). Лимит: 60 запросов в минуту на ключ.
• GET /wholesale/v1/redemptions/:redemptionId (или ?code=) → статус not_redeemed | pending | processing | fulfilled | failed, а также retryable / failureCode. При ошибке отправьте POST с тем же кодом и исправленными данными. Опрашивайте раз в 30–60 секунд.
• Подпишитесь на вебхуки redemption.fulfilled / redemption.failed, чтобы не опрашивать вручную; повторно отправленный код создает новое событие с новым eventId. Протестируйте процесс с помощью prod_api_order_test: его коды активируются мгновенно и отправляют redemption.fulfilled.

curl -X POST https://aibulk.uk/api/wholesale/v1/redemptions \
  -H "Authorization: Bearer awk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"code":"XXXX-XXXX-XXXX-XXXX","redeemInfo":{"account_id":"<Claude Organization ID>"}}'
# -> {"redemptionId":"...","status":"pending","code":"...","orderId":"..."}
# then poll: curl -H "Authorization: Bearer awk_your_key" https://aibulk.uk/api/wholesale/v1/redemptions/<redemptionId>

Коды ошибок, примеры запросов и правила повторов описаны в Полная документация API.

Дополнительно: Webhook о выдаче

Получайте события order.delivered / topup.credited на свой сервер без необходимости постоянного опроса. Настройте URL (секретный ключ подписи показывается один раз — при повторной настройке он обновляется), затем проверьте через POST /wholesale/v1/webhook/test:

curl -X PUT https://aibulk.uk/api/wholesale/v1/webhook \
  -H "Authorization: Bearer awk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.example.com/aibulk-webhook"}'

Проверяйте HMAC-подпись сырого тела запроса перед обработкой данных:

// Node.js — verify an AIBulk webhook delivery
import { createHmac, timingSafeEqual } from "node:crypto";

function isValidAibulkWebhook(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return !!signatureHeader && signatureHeader.length === expected.length &&
    timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}
// app.post("/aibulk-webhook", ...): verify X-AIBulk-Signature against the raw body,
// dedupe on X-AIBulk-Event-Id, then respond 2xx within 5 seconds.

События: order.delivered {orderId, externalOrderId, productId, qty, codes[], redeemUrl} / topup.credited {orderId, externalTopupId, amount, currency} / redemption.fulfilled & redemption.failed {orderId, externalOrderId, productId, redemptionId, code, status, failureCode, retryable, fulfilledAt} / order.delivery_attention / webhook.test. Поля eventId / event / timestamp находятся на верхнем уровне JSON. При ответе не-2xx или таймауте >5с выполняются повторные попытки до 10 раз с экспоненциальной задержкой (до 6 часов); повторные отправки содержат тот же заголовок X-AIBulk-Event-Id — используйте его для дедупликации. Полные схемы: openapi.json → webhooks.

Соглашения и ограничения

• Суммы всегда передаются десятичными строками (например, "12.5"); валюты — USDT / USDC.
• Для заказов обязателен externalOrderId; для пополнений — externalTopupId (или Idempotency-Key). Используйте одно и то же значение при повторах. Передавайте expectedUnitPrice, если хотите, чтобы при изменении цены запрос завершался с ошибкой price_changed.
• Проверяйте наличие товара перед крупными заказами. При payment=balance списание происходит мгновенно; для direct_code подарочных карт заказ может вернуть paid с codes=[] до завершения подготовки; payment=intent возвращает checkoutUrl — передавайте его только плательщику и не публикуйте в логах; опрашивайте заказ каждые 10–30с после ручной оплаты (синхронизация статуса ограничена до 10с). Неоплаченные intent-заказы аннулируются примерно через 15 минут, но опоздавшая оплата будет обработана и доставлена после сверки.
• Цены фиксируются по уровням пользователя (Lv1–Lv5) и одинаковы на сайте и в API; очки уровня = сумма трат + баланс, повышаются пополнением.
• Ответы с ошибками всегда возвращают { error, message, requestId } — обрабатывайте по коду ошибки (unauthorized / insufficient_balance / rate_limited …).
• Ограничение частоты: 300 запросов в минуту. Ориентируйтесь на заголовки X-RateLimit-* и Retry-After; сохраняйте X-Request-Id для обращения в поддержку.
• Для deliveryType=redemption передаются code и redeemUrl. Для direct_code передаются коды подарочных карт, redeemUrl равен null. Группируйте номиналы с помощью productGroupId, denomination, faceCurrency и region; заказывайте id выбранного товара. stockMode=limited требует проверки количества. fulfillmentStatus=needs_attention означает ручную проверку выдачи или возврата; сохраняйте исходный заказ.
• Неоплаченные intent-заказы и пополнения аннулируются примерно через 15 минут; после этого создайте новый заказ с новым externalOrderId. Пополнения в USDC зачисляются 1:1 на баланс USDT.
• Коды, выпущенные через API, не имеют срока действия. Код расходуется при первой отправке на активацию; в случае неудачи активацию можно повторить с исправленными данными.
• Совместимость: изменения только аддитивные, поля не переименовываются и не удаляются; неизвестные поля следует игнорировать. Значения перечислений (status, stockMode, deliveryType, fulfillmentStatus, коды ошибок, события вебхуков …) могут расширяться — неизвестное значение следует считать неподдерживаемым, а не вызывать сбой всего ответа. Nullable-поля, такие как redeemUrl, могут быть null. Все изменения фиксируются с датой в списке изменений.
• Именование полей: POST /wholesale/v1/orders возвращает camelCase (orderId, externalOrderId); в строках списка заказов и деталях заказа присутствуют те же поля в camelCase наряду со старыми в snake_case с идентичными значениями. Рекомендуется использовать camelCase.