Закрытая интеграция для партнёров

Автоматическая закупка и выдача товаров

Получайте каталог, проверяйте баланс и создавайте заказы из своего магазина или серверной интеграции. Оплата списывается с баланса в Ahlis Shop только после успешного резервирования товара.

Base URL https://api.ahlis.shop

Авторизация: X-API-Key
Денежные суммы: в копейках
Формат: JSON / UTF-8
Версия: стабильная v1

01

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

От ключа до первого заказа за три шага.

1
Получите доступ
Администратор выдаёт доступ. Ключ создаётся в боте: Профиль → API для реселлеров.
2
Загрузите каталог
Используйте GET /v1/products и сохраните стабильный sku.
3
Создайте заказ
Передайте уникальные external_order_id и Idempotency-Key.

curl "https://api.ahlis.shop/v1/account" \
  -H "X-API-Key: YOUR_API_KEY"

import httpx

response = httpx.get(
    "https://api.ahlis.shop/v1/account",
    headers={"X-API-Key": "YOUR_API_KEY"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://api.ahlis.shop/v1/account",
  { headers: { "X-API-Key": "YOUR_API_KEY" } },
);

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Важно: API-ключ хранится только на вашем сервере. Не вставляйте его в браузерный JavaScript, публичный репозиторий или логи.

02

Методы API

Все защищённые запросы требуют заголовок X-API-Key.

GET/v1/account

Баланс, статус доступа и лимиты аккаунта.

GET/v1/products

Доступные товары, цены, остатки и ограничения.

GET/v1/products/{sku}

Актуальная карточка одного товара.

POST/v1/orders

Атомарная покупка и автоматическая выдача.

GET/v1/orders/{order_id}

Восстановление результата заказа по ID.

GET/v1/orders?external_order_id=...

Поиск по номеру заказа вашей площадки.

GET/v1/orders/recent

Последние заказы с постраничной загрузкой.

GET/v1/webhook

Состояние, адрес и очередь webhook.

PUT/v1/webhook

Подключение подписанных уведомлений.

POST/v1/webhook/test

Тестовая доставка в текущий приёмник.

DELETE/v1/webhook

Отключение webhook и очистка секрета.

03

Поля и лимиты

Полный контракт данных, который нужен для серверной интеграции.

Создание заказа

Поле	Тип и ограничения	Назначение
`external_order_id`	строка, 1–128 символов	Постоянный номер заказа в вашей системе. По нему можно восстановить результат.
`sku`	строка, до 64 символов	Значение из каталога. Разрешены латинские буквы, цифры, `-_.`
`quantity`	целое, 1–500	Дополнительно ограничивается лимитом аккаунта и карточкой товара.
`max_unit_price_minor`	целое, необязательно	Максимальная допустимая цена одной штуки в копейках.
`Idempotency-Key`	уникальный заголовок	Создаётся до запроса и не меняется при повторной отправке того же заказа.

Ответы, деньги и доступ

Деньги в minor units

unit_price_minor, charged_minor и balance_minor передаются в копейках. 8000 = 80 ₽.

Выдача в items

Каждый элемент содержит position и content. Сохраните ответ до выдачи клиенту.

Постраничные заказы

GET /v1/orders/recent?limit=50&before_id=.... Для следующей страницы используйте next_before_id.

IP allowlist

Если ограничение включено, администратору нужен публичный IP вашего сервера. Без списка доступ не ограничивается по IP.

Лимит запросов

Текущее значение возвращается как rate_limit_per_minute в GET /v1/account. При 429 учитывайте Retry-After.

Сверка каталога

Перед покупкой проверяйте цену, available_quantity, min_quantity и max_quantity.

04

Создание заказа

Одна операция резервирует товар, списывает баланс и возвращает данные.

ЗапросPOST /v1/orders

curl "https://api.ahlis.shop/v1/orders" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: client-order-84521" \
  -d '{
    "external_order_id": "84521",
    "sku": "gemini-pro-18m",
    "quantity": 2,
    "max_unit_price_minor": 8000
  }'

Успешный ответ201 Created

{
  "order_id": 4585,
  "external_order_id": "84521",
  "status": "completed",
  "sku": "gemini-pro-18m",
  "quantity": 2,
  "charged_minor": 16000,
  "balance_minor": 74200,
  "items": [
    {"position": 1, "content": "..."},
    {"position": 2, "content": "..."}
  ],
  "idempotency_replayed": false
}

minor8000 означает 80 ₽. Так исключаются ошибки округления.

05

Контракт надёжности

Правила, которые защищают деньги и товар при повторах и сбоях сети.

Один ключ — один результат

Повторяйте запрос с тем же Idempotency-Key. API вернёт исходный заказ и не спишет деньги повторно.

Нет товара — нет списания

При OUT_OF_STOCK баланс и склад остаются без изменений.

Цена под контролем

max_unit_price_minor отменяет покупку, если цена стала выше ожидаемой.

Результат восстанавливается

После timeout проверьте заказ по внутреннему или внешнему ID перед новым запросом.

06

Webhooks

Получайте подтверждения заказов и изменения склада без постоянного опроса.

События

order.completedтовар выдан и баланс списан
product.stock_changedизменился доступный остаток
webhook.testпроверка приёмника

Подключение

curl "https://api.ahlis.shop/v1/webhook" \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"url":"https://your-shop.example/webhooks/ahlis"}'

Сохраните signing_secret из первого ответа: повторно он не показывается.

Проверка подписи

X-Ahlis-Event: order.completed
X-Ahlis-Delivery: evt_...
X-Ahlis-Timestamp: 1789500000
X-Ahlis-Signature: sha256=...

Секрет подписи показывается только при подключении webhook. Проверяйте timestamp, HMAC и идентификатор доставки.

07

Ошибки

Ориентируйтесь на машинный error.code, а не на текст сообщения.

HTTP	Код	Что делать
401	`INVALID_API_KEY`	Проверьте ключ или создайте новый в профиле.
402	`INSUFFICIENT_BALANCE`	Пополните баланс; деньги за заказ не списаны.
403	`API_ACCESS_INACTIVE`	Обратитесь к администратору магазина.
404	`PRODUCT_UNAVAILABLE`	Обновите каталог и не повторяйте покупку вслепую.
409	`OUT_OF_STOCK`	Баланс не списан; покажите отсутствие товара.
409	`IDEMPOTENCY_CONFLICT`	Используйте новый ключ для другого состава заказа.
409	`PRICE_CHANGED`	Получите новую цену и подтвердите её.
429	`RATE_LIMITED`	Подождите время из `Retry-After`.
500	`INTERNAL_ERROR`	Повторите тот же запрос с тем же idempotency key.

{
  "error": {
    "code": "OUT_OF_STOCK",
    "message": "Not enough stock.",
    "request_id": "...",
    "retryable": false,
    "details": {}
  }
}

08

Как проходит запрос

Публичным остаётся только HTTPS-вход; база и внутренний API недоступны из интернета.

Схема подключения магазина реселлера к Ahlis Shop API через HTTPS — Клиент → HTTPS reverse proxy → API → база магазина и гарантированная очередь webhook.