Перейти к основному содержанию

Разработчикам

Merchant API

REST API в режиме только чтения для вашего магазина VeeBoost: один опубликованный контракт, аутентификация по ключу и предсказуемая пагинация — для интеграций, которые остаются синхронными.

Один контракт, опубликованный как единственный источник истины

Ваш магазин публикует полный машиночитаемый контракт (OpenAPI 3.1): каждый эндпоинт, параметр, ответ и код ошибки merchant API. Эта страница ссылается на него и никогда не воспроизводит таблицы эндпоинтов — контракт не может разойтись с реальностью, и ваша интеграция тоже.

Опубликованный контрактGET /openapi/v1.json

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

Три шага до первого чтения каталога:

  1. Создайте ключ API в админке (раздел «Разработчики») с нужными скоупами чтения. Он начинается с vbk_ и показывается только один раз.
  2. Передавайте его в заголовке X-Api-Key с каждым запросом — ваш тенант определяется по ключу, а не по хосту.
  3. Вызовите первый эндпоинт, например 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 — ничего не планируется тихо.