API для интеграции

версия v1

Веб-сервисы нужны не «вообще», а для одного: учётная система заказчика или дилера забирает заявки и передаёт остатки, цены и расчёты. Всё остальное в API не добавляется без повода. Версия стоит в пути, потому что интеграция живёт годами и меняется по договору, а не по нашему желанию.

С чего начать

Запросить ключКлюч выдаёт завод: напишите менеджеру, какие обмены нужны. Области доступа перечислены ниже — ключ получает только те, что нужны обмену.
Проверить ключЗапрос GET https://develop.stormofgalaxy.com/api/v1/ping возвращает области ключа. Половина разбирательств заканчивается на этом ответе.
Настроить обменКлюч передаётся заголовком Authorization: Bearer <ваш-ключ>. Частота считается по ключу, а не по адресу: у партнёров он может совпасть за общим NAT.

Области доступа

Ключ несёт области, а не «полный доступ»: обмен остатками не должен уметь читать контакты заказчиков.

Область	Что открывает
`catalog:read` Чтение каталога	Артикулы, наименования, атрибуты, цены и остатки — то же, что видно на сайте.
`orders:read` Чтение заявок и заказов	Заявки с составом и суммами, включая контакты заказчика. Персональные данные.
`orders:write` Создание заявок и смена статуса	Создание заявки от имени заказчика и перевод её по статусам. Принимает контакты — персональные данные.
`catalog:write` Правка текста и статуса позиций	Наименование, статус и SEO-поля существующих позиций. Новые не заводит и ничего не удаляет.
`stock:write` Проставление остатков	Изменение остатка по артикулу. Ничего не создаёт и не удаляет.
`prices:write` Проставление цен	Изменение цены по артикулу. Ничего не создаёт и не удаляет.
`balance:write` Проставление расчётов с заказчиком	Долг, лимит отгрузки и отсрочка по компании — их видит заказчик в кабинете. Компаний не создаёт: неизвестный ИНН отвергается.

Методы

Метод	Область	Что делает
GET /v1/ping	`catalog:read`	Проверка ключа Возвращает области ключа. Половина разбирательств заканчивается на этом ответе.
GET /v1/catalog	`catalog:read`	Обход каталога Постраничный обход курсором. `changedSince` отдаёт только изменившееся.
GET /v1/catalog/{sku}	`catalog:read`	Одна позиция по артикулу По артикулу, а не по внутреннему идентификатору: артикул — то, чем позиция называется и в 1С.
GET /v1/orders	`orders:read`	Заявки и заказы Персональные данные: контакты заказчика приходят вместе с заявкой.
POST /v1/stock	`stock:write`	Проставление остатков Меняет остатки, по которым покупатель принимает решение. Ноль — «нет на складе», null — «учётная система ничего не сказала»: это разные вещи. Песочница его не выполняет.
POST /v1/prices	`prices:write`	Проставление цен Цена — без НДС, В РУБЛЯХ. Песочница его не выполняет: это цена, по которой купят.
POST /v1/orders	`orders:write`	Создать заявку Создаёт настоящую заявку, которую менеджер будет считать. Песочница его не выполняет.

Соглашения

Деньги — в рублях. Наружу и внутрь. Копейки за пределами платформы — ловушка, в которую однажды попадёт интегратор и пришлёт цену в сто раз больше.
Запись идемпотентна. Остатки, цены и поля позиций проставляются, а не добавляются. Единственный метод, создающий сущность, — POST /orders; у него есть Idempotency-Key, и повтор возвращает тот же заказ, а не второй на тот же объём.
Постраничность курсором, а не смещением: каталог правится во время выгрузки, и offset пропустил бы часть позиций.
Ноль остатка и отсутствие остатка — разное. Ноль — «нет на складе», null — «учётная система про артикул ничего не сказала». Свести их значило бы обнулить остаток всему, чего нет в выгрузке.
Строка с ошибкой не отменяет пакет. Обмен из тысячи позиций, отвергнутый из-за одной опечатки, — это способ никогда не обменяться. Что принято и что отвергнуто, видно из ответа. Исключение — заявка: неизвестный артикул отвергает её целиком.
Цену заявки присылать не нужно — она считается на стороне завода теми же функциями, что и спецификация покупателя. Второе место, где считаются деньги, однажды разойдётся с первым.
Артикул регистрозависим. В нём есть значащая латинская «x» размера: НЗТИ-Т-108x4-ПЭ-1-ОДК.

Чего в текущей версии нет

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

Полное описание форматов запросов и ответов передаётся вместе с ключом. Прайс-лист без ключа доступен на странице цен, а спецификацию можно прислать файлом.