API и подключение 1С
Токен организации, адреса API, как 1С или другая система загружает товары, цены и остатки и забирает заказы.
API — способ для программ работать с вашей организацией без кабинета: 1С любой конфигурации (Управление нашей фирмой, Управление торговлей, Бухгалтерия) или ваша собственная система сама обращается к нам, загружает товары, цены и остатки и забирает заказы с площадок. Работать можно и без 1С — всё то же доступно в кабинете.
Токен. В разделе «API и 1С» владелец или администратор создаёт токен — пароль для программы. Показываем его один раз, сразу после создания: скопируйте и вставьте в настройки 1С. Заведите отдельный токен на каждую систему — тогда одну можно отключить, не трогая другие. Потеряли токен — отзовите его и создайте новый.
Как обращаться. Адрес — https://hranitel.cleverprof.ru/api/v1, каждый запрос — с заголовком Authorization: Bearer <токен>, данные — JSON. Проверка подключения — GET /api/v1/ping: ответит названием организации. До 120 запросов в минуту на токен; превысили — ответ 429 и заголовок Retry-After.
Товары, цены и остатки из 1С. PUT /api/v1/products — пакет до 500 товаров: код в учётной системе (erp_id), название, артикул, цена продажи. Товар находим по коду; нет такого — по артикулу: товар, заведённый в кабинете, переходит под учётную систему. Нет и его — создаём в пределах тарифа. PUT /api/v1/prices — только цены. В ответе — итог по каждой позиции: ошибка в одной не отменяет остальные.
Остатки по складам. PUT /api/v1/stocks — остаток товара на складе 1С: код товара или артикул, код склада и количество. Склад с новым кодом появится у нас сам, название можно уточнить через PUT /api/v1/warehouses. В карточке магазина, в блоке «Склады и остатки обычных товаров», загрузите склады площадки и выберите для каждого склад 1С, остаток которого туда отправлять. Когда остатки магазина сверены с площадкой, они уходят туда каждые 10 минут и сразу после обмена — на складе минус неотгруженные заказы, не меньше нуля. Товара нет на складе 1С — его остаток на площадке не трогаем. В ответах о товаре stock — сумма «на складе» по складам, она может быть отрицательной (продано больше, чем было); stock_updated_at — когда число в последний раз изменилось (обмен, правка, отгрузка, возврат), а не когда 1С присылала его последний раз: тот же остаток повторно время не меняет.
Кто ведёт остатки. В «Склады и остатки» выбирается хозяин остатков: «В 1С» или «В сервисе». Пока выбрано «В сервисе», PUT /api/v1/stocks и PUT /api/v1/warehouses отвечают 409 с кодом stocks_managed_in_service и ничего не записывают; чтение работает всегда. Для 1С присылайте свободный остаток — сколько на складе минус то, что 1С уже зарезервировала и отгрузила сама. Сервис вычитает из него только резерв по заказам, которых 1С ещё не подтвердила: POST /api/v1/orders/ack значит «заказ создан в 1С и учтён в её остатке». Порядок в сеансе обмена: заказы, подтверждения, остатки. Если выбран режим «Один склад на все магазины», принимается только один склад: первый присланный код достаётся единственному складу, другой код даёт ошибку позиции single_warehouse.
Журнал движений. GET /api/v1/stock-movements — что и почему менялось на складах: товар, склад, изменение, остаток после, причина, заказ. По возрастанию номера, по 500 записей: after_id — номер последней полученной записи, product_id — только один товар. Журнал на чтение, правит остатки он не может. Если склад потом удалили, запись остаётся: warehouse.id и code пустые, name — название склада на момент движения.
Кто хозяин поля. Название, артикул, цену продажи и остатки на складах ведёт учётная система — в карточке товара они только для чтения, менять их нужно в 1С. «Нашу цену» для защиты цены, способ выдачи, материалы и ключи ведёт сервис. Тип товара (цифровой или обычный) 1С задаёт только при создании. Остаток цифрового товара — его свободные ключи, из 1С он не приходит.
Ошибки приходят одним видом: {"error": {"code": "…", "message": "…"}}. code — для программы, не меняется; message — для человека. У ошибок проверки есть fields — что не так с каждым полем.
Что ведёт сервис — тоже через API. GET /api/v1/shops — магазины (ключи площадок API не отдаёт), GET /api/v1/listings — предложения с ценой на площадке, PUT /api/v1/our-prices — «наша цена» для защиты цены, PATCH /api/v1/products/{id} — выдача ключей, страница получения, инструкция, архив. Ключи загружаются POST /api/v1/products/{id}/keys, а GET по тому же адресу показывает только их число — сами ключи API не отдаёт никогда. Материалы страницы получения — /api/v1/products/{id}/materials: ссылка или файл в пределах тарифа.
Заказы в 1С. GET /api/v1/orders?since_version=N — заказы всех площадок, изменившиеся после версии N: позиции с кодами товаров учётной системы, суммы, статусы. 1С хранит у себя последнюю версию из ответа и в следующий раз продолжает с неё. Загрузив заказ, 1С подтверждает это POST /api/v1/orders/ack со своим номером документа. Изменился заказ позже — например, его отменили — он снова появится в ленте с пометкой «нужно выгрузить». Ключи и коды покупки в API не попадают.
Схема, срок и склад заказа. У заказа в API есть scheme — fbs, rfbs (отгружает продавец) или fbo (со склада площадки), ship_by — срок сборки или отгрузки от площадки (у Wildberries в API его нет), warehouse — код и название нашего склада, с которого заказ отгружается (по складу FBS магазина; у FBO и несопоставленного склада — пусто), и shipped_at — когда площадка перевела заказ в доставку. Пока заказ FBS или rFBS не отгружен и не отменён, его позиции в резерве склада. При отгрузке, если остатки ведёт сервис, позиции списываются со склада один раз — в журнале движений это «Отгрузка заказа». В режиме «В 1С» сервис не списывает — отгрузку учитывает 1С. Заказ, который пришёл к нам уже отгруженным (например, история при подключении магазина или заказ, созданный и отгруженный между двумя загрузками), не списывается: shipped_at у него есть, движения нет — такое расхождение исправляет сверка.
Если связь пропадёт, данные останутся у нас, а 1С при следующем обращении заберёт всё, что изменилось: курсор сдвигает сама 1С, пропустить ничего нельзя.
Описание всех адресов — в формате OpenAPI: его понимают Postman, Insomnia и генераторы клиентов. Подключить вашу 1С поможем — напишите в поддержку.
Возвраты. У позиции заказа в API есть return_decision и return_decided_at: pending — возврат обычного товара ждёт решения продавца, restock — «Годен», write_off — «Брак», пусто — возврата нет. Если остатки ведёт 1С, сервис по «Годен» склад не меняет — вернуть остаток должна 1С, ориентируясь на это поле.