API для клиентов

Аутентификация

Каждый запрос — с заголовком Authorization: Bearer <токен>. Токен начинается с avst_live_ и показывается один раз при создании — сохраните его в безопасном месте. Утёкший токен немедленно отзовите в ЛК и создайте новый.

curl https://avstorg.ru/api/ext/v1/me \
  -H "Authorization: Bearer avst_live_ВАШТОКЕН"

Токен привязан к организации: цены, остатки и заказы — её контекста. Несколько организаций — отдельный токен на каждую.

Конвенции

• Все цены и суммы — в рублях (число с двумя знаками, например 114.00).
• Даты — ISO 8601 UTC (2026-07-21T12:00:00Z).
• Идентификаторы товара — sku (артикул) и code (внутренний код на сайте, 6 цифр).
• Номера заказов содержат кириллицу (АТ.26-07-21.0001.Ю) — в URL передавайте с URL-encoding.
• Пагинация каталога — курсорная: передавайте next_cursor из ответа, пока он не станет null.
• Неизвестные поля в ответах игнорируйте — мы добавляем новые без смены версии.
• Ошибки: { "error": "код", "message": "описание", "details": {...} } — матчьте по стабильному error.

Лимиты

Превышение → 429 с заголовком Retry-After и details.retryAfterSec.

GET /me — проверка токена

Кто вы, какие права у токена, контекст (организация, тип цен, склад). Начните интеграцию с этого вызова.

{
  "token": { "name": "1С — основная база", "scopes": ["catalog:read", "orders:read"] },
  "context": {
    "type": "legal",
    "display_name": "ООО «Ромашка»",
    "price_type": { "code": "wholesale", "name": "Оптовая" },
    "warehouse": { "code": "voronezh", "name": "Воронеж" },
    "member_role": "owner"
  }
}

GET /products — каталог, цены, остатки

Право: catalog:read. Два представления:

• view=offers — компактно: артикул, внутренний код, цена, остаток. Для частого опроса.
• view=full (по умолчанию) — полная карточка: штрихкоды, габариты, бренд, характеристики, галерея фото, нормы заказа, разбивка остатка.

Параметры: view, cursor, limit (до 200), sku, code (списки через запятую, до 100), barcode, gtin, updated_since (только full).

Запрос — компакт, до 200 позиций:

curl "https://avstorg.ru/api/ext/v1/products?view=offers&limit=200" \
  -H "Authorization: Bearer avst_live_..."

Ответ:

{
  "items": [
    { "sku": "A40854S", "code": "480021", "price": 114.00, "base_price": 120.00,
      "qty": 96, "qty_primary": 96 }
  ],
  "next_cursor": "QTQwODU0Uw",
  "as_of": "2026-07-21T12:34:56Z"
}

Точечно по артикулам (sku):

curl "https://avstorg.ru/api/ext/v1/products?view=offers&sku=A40854S,A80782S" \
  -H "Authorization: Bearer avst_live_..."

Точечно по внутренним кодам (code):

curl "https://avstorg.ru/api/ext/v1/products?view=offers&code=480021,570024" \
  -H "Authorization: Bearer avst_live_..."

Полная карточка (view=full) — ответ:

{
  "sku": "A40854S",
  "code": "480021",
  "name": "Размораживатель замков 75 мл AVS AVK-760",
  "barcode": "4607147352519", "brand": "AVS", "unit": "шт",
  "weight_g": 95, "width_mm": 35, "height_mm": 110, "length_mm": 35,
  "image_url": "https://cdn.avstorg.ru/..._medium.webp",
  "images": [
    "https://cdn.avstorg.ru/..._medium.webp",
    "https://cdn.avstorg.ru/..._medium.webp"
  ],
  "attributes": [{ "name": "Объём", "value": "75", "unit": "мл" }],
  "price": { "price": 114.00, "base_price": 120.00, "discount_percent": 5 },
  "order_rules": { "min_qty": 1, "max_qty": null, "qty_step": 12 },
  "stock": { "qty": 96, "qty_primary": 96, "qty_secondary": 0, "next_delivery_days": null },
  "updated_at": "2026-07-15T10:00:00Z"
}

sku — артикул; code — наш внутренний код товара на сайте (6 цифр, тот же, что в карточке товара и адресе страницы). Оба уникальны и стабильны — по любому из них удобно сопоставлять номенклатуру и запрашивать точечно.

images — галерея фото товара в среднем размере (600px, WebP), главное фото первым. image_url — то же главное фото (для совместимости). Если фото нет — images пустой, image_url = null.

Все цены и суммы — в рублях (число с двумя знаками). order_rules — обязательные нормы заказа: количество не меньше min_qty, кратно qty_step. Цена — ваша персональная (тип цен + постоянные скидки); акции «от суммы корзины» в неё не входят.

Рецепт синхронизации

1. Раз в сутки: полный проход view=full по курсору — карточки, штрихкоды, нормы заказа.
2. Каждые 15–60 минут: полный проход view=offers — цены и остатки. Всегда полным проходом: фильтр updated_since отслеживает только изменения карточек, но не цен и остатков.
3. Между суточными проходами можно забирать изменённые карточки: view=full&updated_since=<момент старта прошлого прохода> (берите время старта, а не конца — перекрытие дешевле пропуска).
4. Товар исчез из выдачи — снят с продажи или недоступен в вашем регионе. Товар с "price": null — виден, но цены для вашего типа цен нет: не удаляйте карточку, просто не продавайте.

Заказы: чтение

Право: orders:read. Каждый заказ — свой номер, склад, статусы оплаты и доставки, состав, трек. Видны заказы организации токена.

• GET /shipments?page=1&per_page=50 — список заказов (фильтры: payment_status, delivery_status, number).
• GET /shipments/{номер} — детально один заказ.
• GET /shipments/{номер}/status-history — таймлайн статусов.
• GET /dictionaries/statuses — справочник статусов (code, name, sort, is_terminal). Постройте маппинг один раз, матчьте по code.

Ответ GET /shipments/{номер} (один заказ):

{
  "number": "АТ.26-07-21.0001.ВРН.Ю.1-ОЗ",
  "order_number": "АТ.26-07-21.0001.Ю",
  "source": { "code": "api", "name": "API" },
  "created_at": "2026-07-21T09:12:00Z",
  "updated_at": "2026-07-21T14:30:00Z",
  "warehouse": { "code": "voronezh", "name": "Воронеж" },
  "is_on_order": false,
  "payment_status":  { "code": "paid",    "name": "Оплачен" },
  "delivery_status": { "code": "shipped",  "name": "Отгружен" },
  "delivery_method": "Самовывоз",
  "tracking_number": null,
  "shipped_at": "2026-07-21T14:30:00Z",
  "delivered_at": null,
  "subtotal": 2736.00,
  "delivery": 0,
  "order_total": 2591.00,
  "order_discount": 145.00,
  "order_delivery": 0,
  "customer_order_ref": "456",
  "legal_entity": { "inn": "3600000000", "kpp": "360001001", "name": "ООО «Ромашка»" },
  "items": [
    { "sku": "A40854S", "code": "480021", "name": "Размораживатель замков 75 мл AVS",
      "qty_ordered": 24, "qty_shipped": 24, "qty_delivered": 0, "qty_returned": 0,
      "price": 114.00, "discount": 6.00,
      "line_subtotal": 2736.00, "line_discount": 144.00, "line_total": 2592.00 }
  ]
}

source — источник заказа (сайт, 1С, API и т.д.). customer_order_ref — номер вашей заявки, если вы указали его при создании.

Суммы позиции: price и discount — за штуку; line_subtotal (до скидки), line_discount, line_total — итоги по позиции по заказанному количеству (qty_ordered). При отмене или частичной отгрузке фактически оплаченное смотрите по статусам и qty_shipped/qty_delivered.

Итоги заказа: order_total (к оплате без доставки), order_discount (суммарная скидка), order_delivery. Сумма к оплате по заказу = order_total + order_delivery. Это точные итоги всего заказа-источника — берите их для сумм; не суммируйте order_* по отгрузкам одного заказа (в каждой отгрузке это итог всего заказа). Расхождение с суммой позиций возможно из-за округления скидки на штуку и списанных бонусов. subtotal — сумма этой отгрузки до скидок.

Создание заказа (POST /shipments)

Право: orders:write. Заголовок Idempotency-Key обязателен (до 64 символов, например UUID): повтор с тем же ключом в течение 24 часов вернёт тот же результат (200), а не дубль.

curl -X POST "https://avstorg.ru/api/ext/v1/shipments" \
  -H "Authorization: Bearer avst_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3a9c12-4b8e-4d01-9a55-e2c6b0f81d34" \
  -d '{
    "items": [
      { "sku": "A40854S", "qty": 24 },
      { "sku": "A80782S", "qty": 12 }
    ],
    "comment": "Заявка из 1С № 456",
    "customer_order_ref": "456",
    "on_lack": "reject"
  }'

Ответ (201):

{
  "order_number": "АТ.26-07-21.0001.Ю",
  "customer_order_ref": "456",
  "source": { "code": "api", "name": "API" },
  "total": 4104.00,
  "delivery": 0,
  "discount": 216.00,
  "shipments": [
    {
      "number": "АТ.26-07-21.0001.ВРН.Ю.1-ОЗ",
      "warehouse": { "code": "voronezh", "name": "Воронеж" },
      "subtotal": 4104.00,
      "items": [ { "sku": "A40854S", "code": "480021", "qty_ordered": 24, "price": 114.00, "discount": 6.00 } ]
    }
  ]
}

subtotal в отгрузке — сумма позиций до скидок (по базовой цене). Итог с учётом скидок смотрите на уровне заказа: total (к оплате) и discount (суммарная скидка). Поэтому сумма subtotal по отгрузкам может превышать total заказа.

Ошибка валидации (422):

{
  "error": "validation_failed",
  "message": "Позиции не прошли валидацию",
  "details": { "problems": [
    { "sku": "A99999", "code": "unknown_sku" },
    { "sku": "A40854S", "code": "insufficient_stock", "available": 8 },
    { "sku": "A80782S", "code": "invalid_step", "qty_step": 12 }
  ] }
}

• Адрес, оплата и доставка не передаются — используются ваши настройки, детали согласует менеджер или клиентская служба.
• customer_order_ref — номер вашей заявки, вернётся во всех ответах по заказу.
• on_lack: reject (по умолчанию) — отклонить позиции сверх остатка. Режим backorder («под заказ» сверх регионального остатка) сейчас ограничен настройками — количество сверх остатка отклоняется; уточняйте у менеджера или в клиентской службе.
• Бонусы через API не списываются.
• Успех — 201 с полным заказом: цены и скидки посчитаны, виден состав.
• Ошибка валидации — 422 с построчными details.problems (см. коды ниже); заказ при этом не создаётся, ключ можно использовать повторно.

Коды ошибок

Коды в details.problems ответа 422:

• unknown_sku — артикул не найден;
• no_price — нет цены для вашего типа цен;
• insufficient_stock — не хватает остатка (поле available — сколько доступно);
• below_min_qty / above_max_qty / invalid_step — нарушены нормы заказа (см. order_rules карточки);
• checkout_rejected — заказ отклонён правилами оформления (текст в message, например минимальная сумма).

Вопросы по интеграции — вашему менеджеру или в клиентскую службу.