API для поставщиков
Ваша учётная система сама загружает в Optor товары, цены и остатки. Обычный JSON по HTTPS, без SDK.
Доступ
- Ключ выдаёт владелец компании-поставщика: «Компания → Интеграции → Создать ключ». Ключ показывается один раз.
- Права ключа: catalog:read — читать свои товары и статусы загрузок, catalog:write — загружать товары, цены и остатки. Ключ можно ограничить IP-адресами.
- Каждый запрос передаёт ключ в заголовке Authorization.
curl https://optor.ai/api/supplier/v1/me \
-H "Authorization: Bearer opt_live_…"Загрузка товаров
POST /offers/batch — до 1000 товаров и 2,5 МБ за запрос. Ключ товара — ваш артикул supplier_sku: повторная отправка обновляет товар, а не создаёт новый. Каждая позиция проверяется сразу, ошибки приходят в ответе, остальные применяются в фоне за несколько секунд. Товары, которых нет в запросе, не меняются.
curl -X POST https://optor.ai/api/supplier/v1/offers/batch \
-H "Authorization: Bearer opt_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 2026-10-22-full-1" \
-d '{"items": [{
"supplier_sku": "SRV-DL380-G10",
"name": "Сервер HPE ProLiant DL380 Gen10",
"brand": "HPE",
"mpn": "P20172-B21",
"category": "servers",
"price": "1249000.00",
"currency": "RUB",
"vat_mode": "included",
"stock": 4,
"lead_time_days": 3
}]}'Ответ 202 — номер загрузки и ошибки по позициям. Итог — GET /imports/{uuid}: статус applying → done, сколько товаров создано и обновлено.
| Поле | Что это |
|---|---|
supplier_sku, name, brand, category, price | Обязательные. category: laptops, desktops, servers, storage, network, monitors, components, peripherals, printing, software, other. |
mpn | Артикул производителя: по бренду и mpn товар привязывается к карточке справочника. |
stock, lead_time_days, min_order_qty, warehouse_city | Наличие и условия поставки. |
vat_mode, price_visibility, active | НДС (included, excluded, exempt), кому видна цена (signed_in, verified, on_request), в продаже ли товар. Не передали — значение у товара не меняется. |
Цены и остатки
POST /offers/stocks-prices — до 1000 позиций, применяется сразу. Меняются только переданные поля. Подходит для обновления каждые 5–15 минут.
curl -X POST https://optor.ai/api/supplier/v1/offers/stocks-prices \
-H "Authorization: Bearer opt_live_…" \
-H "Content-Type: application/json" \
-d '{"items": [{"supplier_sku": "SRV-DL380-G10", "price": "1199000.00", "stock": 2},
{"supplier_sku": "SW-C9200", "stock": 0, "active": false}]}'Результат по каждой позиции: updated, not_found (сначала загрузите товар), feed_managed (товар обновляется прайс-листом по ссылке) или invalid с текстом ошибки.
Сверка
GET /offers?updated_since=2026-10-22T00:00:00Z — ваши товары по времени изменения, до 500 за страницу; следующая страница — параметр cursor из next_cursor.
Обмен с 1С без программиста
1С:Управление торговлей, Комплексная автоматизация и ERP подключаются стандартным «Обменом с сайтами» (CommerceML 2 и 3): адрес https://optor.ai/api/1c/exchange, пользователь — любой, пароль — ключ API с правом catalog:write. Тип цен, категорию и НДС по умолчанию владелец выбирает в «Компания → Интеграции».
Ошибки и лимиты
- Ошибка всегда в одном виде: {"error": {"code": "…", "message": "…", "fields": {…}}}. code — для программы, message — для человека.
- 401 — нет ключа или он отозван, 403 — у ключа нет права или запрос не с разрешённого IP, 422 — поля запроса не прошли проверку.
- Не больше 120 запросов в минуту на ключ и 20 загрузок товаров в минуту. При превышении — 429 и заголовок Retry-After с числом секунд.
- Один товар — один источник: товары из прайс-листа по ссылке через API не меняются. Товары в архиве — тоже, пока их не вернут из архива в кабинете.
- Запрос больше 2,5 МБ получает ответ 413: разбейте его на части.
- API только расширяется: поля и методы не удаляются и не переименовываются.
Схема и проверка
Полная схема OpenAPI: https://optor.ai/api/supplier/v1/openapi.json. Для проверки интеграции попросите тестовый доступ на staging.optor.ai: support@optor.ai.