Разработчикам
Merchant API
REST API в режиме только чтения для вашего магазина VeeBoost: один опубликованный контракт, аутентификация по ключу и предсказуемая пагинация — для интеграций, которые остаются синхронными.
Один контракт, опубликованный как единственный источник истины
Ваш магазин публикует полный машиночитаемый контракт (OpenAPI 3.1): каждый эндпоинт, параметр, ответ и код ошибки merchant API. Эта страница ссылается на него и никогда не воспроизводит таблицы эндпоинтов — контракт не может разойтись с реальностью, и ваша интеграция тоже.
GET /openapi/v1.jsonБыстрый старт
Три шага до первого чтения каталога:
- Создайте ключ API в админке (раздел «Разработчики») с нужными скоупами чтения. Он начинается с vbk_ и показывается только один раз.
- Передавайте его в заголовке X-Api-Key с каждым запросом — ваш тенант определяется по ключу, а не по хосту.
- Вызовите первый эндпоинт, например GET /products, а дальше следуйте контракту.
Аутентификация
Каждый запрос несёт ваш ключ в заголовке X-Api-Key. v1 предоставляет ровно четыре скоупа чтения — товары, заказы, клиенты и доставки вебхуков. Отсутствующий скоуп даёт 403; отозванный ключ отклоняется немедленно. Храните ключи на сервере: им не место в браузере или публичном репозитории.
products:readorders:readcustomers:readwebhooks:readПагинация
Списковые эндпоинты пагинируются: обходите их с параметром page и читайте конверт, возвращаемый с каждой коллекцией, — он показывает, где вы находитесь, чтобы интеграция могла пересинхронизироваться без догадок. Точные параметры каждого эндпоинта описаны в контракте.
Ошибки и лимиты запросов
Ошибки возвращают структурированное JSON-тело, которое можно парсить, а не абзац, который надо скрести. Ответ 429 — стабильный контракт: всегда одна и та же форма тела, с заголовками X-RateLimit-* и Retry-After, точно указывающим, когда вернуться. Напор не разблокирует данные — отступите.
Ключи sandbox
На этапе перед запуском ключи sandbox выдаются после валидации нашей командой и работают с выделенным бюджетом лимитов, отдельным от продакшн-ключей — исследуйте API на своём магазине, не затрагивая живой трафик и квоты.
Примеры по языкам
По одному фрагменту на платформу, только скоупы чтения: каждый получает ваш каталог товаров. Замените <api-base> на API-хост вашего магазина из админки → раздел «Разработчики».
curl
curl -H "X-Api-Key: vbk_your_key" \
"https://<api-base>/products?page=1"JavaScript
async function listProducts(page = 1) {
const res = await fetch("https://<api-base>/products?page=" + page, {
headers: { "X-Api-Key": "vbk_your_key" },
});
if (res.status === 429) {
// Structured contract: honor Retry-After, never screen-scrape.
const wait = Number(res.headers.get("Retry-After")) * 1000;
await new Promise((done) => setTimeout(done, wait));
return listProducts(page);
}
if (!res.ok) throw new Error("products:read failed with " + res.status);
return res.json();
}Python
import requests
def list_products(page=1):
res = requests.get(
"https://<api-base>/products",
params={"page": page},
headers={"X-Api-Key": "vbk_your_key"},
timeout=10,
)
res.raise_for_status()
return res.json()v1 по дизайну только для чтения: products:read, orders:read, customers:read и webhooks:read — единственные существующие скоупы. Скоупы записи были бы явно документированным решением v1.x — ничего не планируется тихо.