Разработчикам
Справочник API
REST поверх HTTPS с JSON. Каждый запрос несёт токен приложения, и токен определяет магазин.
Справочник API
- Базовый адрес
https://api.saleya.app/v1- Версия
- 1
- Аутентификация
- Токен приложения из настроек магазина в заголовке Authorization: Bearer <token>.
- Спецификация
Эти адреса называет и сам API: GET на базовый адрес или на корень его хоста не требует токена и возвращает адреса этого справочника, файла OpenAPI и коллекции Postman; первые два приходят ещё и в заголовке Link (RFC 8631).
Scopes
Приложение получает только те scopes, что выбрал магазин. Scope записи включает scope чтения своего ресурса, а запрос без scope своего метода получает 403 insufficient_scope.
| Scope | В панели магазина | Что открывает | Методы |
|---|---|---|---|
catalog:read | Каталог — Чтение | Чтение каталога: категории, товары с вариантами и фото, правила рекомендаций, прайс-листы точек с ручными ценами и надбавками. | |
catalog:write | Каталог — Запись | Создание, правка и архив категорий, товаров, вариантов, опций и фото товаров и правил рекомендаций; правило, ручные цены и надбавки прайс-листов точек; ход загрузок фото. Включает catalog:read | |
inventory:read | Остатки — Чтение | Чтение остатков по точкам, журнала движений склада, партий, перемещений, ревизий и причин списания магазина. | |
inventory:write | Остатки — Запись | Установка физического остатка после пересчёта, приход и списание. Включает inventory:read | |
orders:read | Заказы — Чтение | Чтение заказов, черновиков, статусов заказов, способов доставки и ручных способов оплаты. Контакты покупателя в заказах требуют ещё customers:read. | |
orders:write | Заказы — Запись | Создание и оформление черновиков, смена статуса и отмена заказов, выпуск отправления у перевозчика и запись номера отслеживания у службы без интеграции. Оформление черновика оплаченным требует ещё payments:write, отмена заказа с полученными деньгами — refunds:write. Включает orders:read | |
orders:wholesale | Заказы — Оптовые прайсы | Условия опта — право панели «вести опт»: заведение, правка и удаление оптовых прайс-листов, их ручные цены и надбавки, назначение оптового прайса покупателю (с customers:write). Включает orders:read, catalog:read и costs:read: оптовый лист считает цену от себестоимости. Оптовых продаж через API нет. Включает orders:read, catalog:read, costs:read | |
customers:read | Покупатели — Чтение | Чтение покупателей с адресной книгой, реквизитами и группами, а также контактов, адреса и комментария покупателя в заказах и получателя фискальных документов. Добавляет поля в orders:read, fiscal:read | |
customers:write | Покупатели — Запись | Создание и правка покупателей, их адресной книги и реквизитов; ведение групп покупателей и их состава. Включает customers:read | |
locations:read | Точки — Чтение | Чтение точек магазина, доступных приложению. | |
payments:read | Платежи — Чтение | Чтение платежей по заказам. | |
payments:write | Платежи — Запись | Подтверждение ручного платежа полученным и оформление черновика оплаченным. Включает payments:read | |
refunds:read | Возвраты — Чтение | Чтение возвратов по заказам. | |
refunds:write | Возвраты — Запись | Расчёт и создание возвратов, подтверждение ручных выплат и отмена заказов с полученными деньгами. Включает refunds:read | |
costs:read | Себестоимость — Чтение | Себестоимость в вариантах каталога и позициях заказов, оптовые прайс-листы, считающие цену от неё. Своих методов не открывает и работает только вместе с catalog:read или orders:read. Добавляет поля в catalog:read, orders:read | |
fiscal:read | Учёт — Чтение | Чтение юрлиц магазина, фискальных документов с их PDF, налоговых периодов, удержаний и перцепций с сертификатами магазина. Получатель документа требует ещё customers:read. Вместе с orders:read даёт документ внешней кассы в заказах. Добавляет поля в orders:read | |
fiscal:write | Учёт — Запись | Выпуск фактуры по закрытой продаже, перевыпуск документа после сбоя или отказа налоговой и снятие отклонённого документа с контроля. Выпуск идёт в налоговую: ключ идемпотентности обязателен. Включает fiscal:read | |
fiscal:annul | Учёт — Аннулирование фактур | Аннулирование выпущенных фактур кредит-нотой — необратимо: нота остаётся в налоговой. Записи не даёт: выпускать документы и снимать их — разные полномочия. Включает fiscal:read | |
finance:read | Деньги — Чтение | Чтение денежных счетов с остатком, статей, журнала движений денег с источником и первичным документом, курса дня учёта, кассовых смен со сверкой и журналом денежного ящика, подарочных карт с долгом магазина и журналом карт, счетов покупателей в книге долгов с журналом и выпиской. | |
finance:write | Деньги — Запись | Запись ручных доходов и расходов, их правка и удаление, переводы между счетами, разноска журнала пачкой и погашение долгов покупателей деньгами, которые уже пришли. Счета и статьи ведёт панель магазина. Включает finance:read | |
procurement:read | Закупки — Чтение | Чтение поставщиков с реквизитами и условиями расчётов, счетов поставщиков с налогом, строками и остатком, оплат счетов, сальдо, акта сверки, взаимозачётов, заказов поставщику, приёмок, возвратов поставщику и актов реализации. | |
procurement:write | Закупки — Запись | Создание и правка поставщиков: реквизиты, условия расчётов, внешний id. Заказы поставщику: черновик, правка, размещение, отмена и закрытие. Счета поставщиков: черновик, правка, удаление черновика, проведение и аннулирование. Включает procurement:read | |
procurement:approve | Закупки — Утверждение счетов к оплате | Одобрение проведённых счетов поставщиков к оплате и отзыв одобрения: без него счёт не оплачивается. Записи не даёт: заводить счета и разрешать их оплату — разные полномочия. Включает procurement:read | |
procurement:pay | Закупки — Оплата счетов поставщиков | Оплата одобренных счетов поставщиков вне системы — когда деньги ушли мимо счетов магазина, например с банка ERP, — и отмена оплаты. Записи и одобрения не даёт: заводить счета, разрешать их оплату и платить — разные полномочия. Включает procurement:read | |
webhooks:read | Вебхуки и события — Чтение | Чтение ленты событий, адресов вебхуков и их доставок. | |
webhooks:write | Вебхуки и события — Запись | Создание, правка и удаление адресов вебхуков, получение и ротация их секретов, тестовые события и повтор доставок. Включает webhooks:read | |
bulk:read | Массовые операции — Чтение | Чтение массовых операций, скачивание их результатов и проверка загрузок. | |
bulk:write | Массовые операции — Запись | Загрузка файлов, запуск и отмена массовых операций. Каждый вид операции требует ещё scope своего ресурса. Включает bulk:read |
Лимиты
Потолки и сроки хранения API. Лимиты запросов тарифа приходят в заголовке RateLimit-Policy каждого ответа.
| Лимит | Значение |
|---|---|
| Записей на странице списка (limit). | 250 записей |
| Текущих токенов у приложения: один в работе и один на замену. | 2 |
| Сколько хранится ответ на запрос с Idempotency-Key. | 24 часа |
| Сколько действует курсор синхронизации; более старый получает 410 cursor_expired. | 30 дней |
| Сколько хранятся события в GET /v1/events. | 30 дней |
| Сколько запросы хранятся в журнале запросов приложения. | 30 дней |
| Адресов вебхуков у приложения. | 10 |
| Сколько доставка вебхука ждёт ответа адреса. | 10 секунд |
| Сколько прежний секрет ещё подписывает после ротации. | 24 часа |
| Автоматических повторов неудачной доставки вебхука. | 10 |
| Примерно сколько длятся автоматические повторы доставки. | 72 часа |
| Сколько адрес может отвечать неудачей без единого успеха, прежде чем его выключат. | 72 часа |
| Массовых операций приложения в очереди и в работе одновременно. | 5 |
| Размер входного файла массовой операции. | 256 МБ |
| Размер одной строки входа. | 1 МБ |
| Размер одной части загрузки. | 1 МБ |
| Сколько хранятся законченная массовая операция и её файлы. | 7 дней |
| Сколько запросов в минуту с одного адреса может быть отклонено на входе (401, 403), прежде чем адрес получит 429. | 60 |
Ресурсы
Основы
Приложение и токен
От чьего имени говорит токен: приложение, его scopes, точки и лимиты. Первый вызов интеграции: по нему видно, что токен рабочий и каких scopes не хватает.
Магазин
То, с чем читаются все остальные ответы: валюта денежных сумм, часовой пояс календарных дат и языки контента.
Точки
Точки магазина: магазины, склады, кухни и пункты самовывоза. На них ссылаются остатки, заказы и самовывоз.
Каталог
Категории
Категории каталога плоским списком: дерево строится по parent_id. Создаются, правятся, уходят в архив и сопоставляются по внешнему id.
Товары
Карточки товаров: названия, описания, категории, опции и фото. У вариантов свои методы; товар создаётся и пишется вместе с ними.
- getТовары: категории, опции и фото, без вариантов
- postСоздать товар вместе с вариантами
- getТовар
- patchИзменить карточку товара: поля, категории, внешний id
- deleteАрхивировать товар вместе с вариантами
- getТовар по внешнему id
- patchСоздать или изменить товар вместе с вариантами по внешнему id
- putЗаменить опции товара целиком и разложить по ним его варианты
Варианты
То, что реально продаётся и лежит на складе: артикул, штрихкоды, цены, единица и способ продажи. Варианты правятся под версией карточки своего товара.
- getВарианты товаров: артикул, штрихкоды, цены и единицы
- postДобавить вариант в товар
- getВариант товара
- patchИзменить вариант товара
- deleteАрхивировать вариант товара
- getВариант товара по внешнему id
- patchСоздать или изменить вариант по внешнему id
- getТех-карта варианта: состав и выход заготовки
- putЗаменить тех-карту варианта: состав и выход заготовки
Фото товара
Галерея товара: добавить фото по адресу, переставить, выбрать главное, снять.
Загрузки фото
Фото, добавленные по адресу, скачиваются в фоне; загрузка показывает статус и причину сбоя.
Группы модификаторов
Выбор к позиции: соусы, добавки, размер порции. Группа задаёт границы выбора, опции — надбавку и состав.
- getГруппы модификаторов с опциями, изменённые с указанного момента
- postСоздать группу модификаторов с опциями
- getГруппа модификаторов с опциями
- patchИзменить группу модификаторов и её набор опций
- deleteАрхивировать группу модификаторов
- getГруппа модификаторов по внешнему id
- patchСоздать или изменить группу модификаторов по внешнему id
Модификаторы товара
Какие группы модификаторов у товара, по порядку, с правилом выбора и надбавками опций по вариантам.
Правила рекомендаций
Что предлагать к товарам категории или подборки, по приоритету: свой список товара, затем правила сверху вниз, затем автоподбор.
Налоговые классы
Налоговые классы магазина, на которые товары ссылаются через tax_class_id: природа налога и ставка, которую запоминает продажа.
Прайс-листы
Прайс-листы точек и оптовые: процент к базовой цене или к себестоимости и округление. Ручные цены и надбавки — своими лентами.
- getПрайс-листы магазина: листы точек и оптовые, их правило и округление
- postЗавести оптовый прайс-лист
- getПрайс-лист
- patchИзменить прайс-лист: процент и округление, у оптового — и имя; правило листа точки меняет цены во всех его точках
- deleteУдалить оптовый прайс-лист; назначение покупателям снимается с согласия
Ручные цены прайс-листов
Ручные цены вариантов в прайс-листах — исключения из правила листа: цена в валюте прайса и её проекция в деньгах учёта.
Ручные надбавки прайс-листов
Ручные надбавки опций модификаторов в прайс-листах: для одного варианта позиции или для всех, в валюте прайса и в деньгах учёта.
Склад
Остатки
Остаток варианта на точке: прочитать уровни, установить физический остаток после пересчёта, принять или списать товар.
Движения склада
Журнал физического остатка точки: продажи, приёмки, списания, ревизии, перемещения и их сторно. Только дописывается.
Партии
Партии товара: номер с упаковки, срок годности и доступность. На партию ссылаются движения склада и строки документов.
Перемещения
Акты перемещения товара между точками магазина: проведённый документ со строками. Ошибку гасит встречный акт.
Ревизии
Ревизии остатков точки: охват, слепой счёт и статус от черновика до проведения. Строки — отдельной лентой.
Строки ревизий
Что нашла ревизия: учёт и факт по позиции и партии, расхождение, применённая коррекция и остаток точки после проведения.
Причины списания
Причины магазина, которые называет списание: причина решает учётный вид и нужен ли комментарий.
Заказы и оплаты
Заказы
Заказы всех каналов: позиции, итоги, статус и оплата. Лента отдаёт изменённое в порядке коммитов; статус меняется и заказ отменяется по правилам магазина.
- getЗаказы, изменённые с указанного момента: позиции, суммы, статус заказа и статус оплаты
- getЗаказ
- getНаклейка текущего отправления заказа у перевозчика, PDF; на ней данные получателя, поэтому нужен и customers:read
- postПеревести заказ в другой статус магазина
- postОтменить заказ
- postВыпустить отправление у перевозчика заказа: запрос исполняется в фоне, итог — в заказе и событием order.updated
- postЗаписать номер отслеживания у службы доставки без интеграции: номер, ссылку и название службы
- postСнять номер отслеживания, записанный вручную
Статусы заказов
Список статусов магазина с его собственными, постоянный смысл каждого и разрешённые переходы.
Черновики заказов
Заказ, который готовит приложение: черновик считается живьём по каталогу, скидкам и доставке, показывает помехи оформлению и становится заказом.
Платежи
Попытки оплаты заказов и их исход. Здесь подтверждаются ручные платежи, ждущие денег.
Возвраты
Возвраты по заказам: сначала расчёт, затем возврат позиций и доставки; деньги уходят обратно способами оплаты, товар — на склад.
- getВозвраты по заказам, изменённые с указанного момента: позиции и проводки по платежам
- getВозврат по заказу
- postРассчитать возврат по заказу и остаток к возврату — ничего не пишет
- postВернуть позиции и доставку заказа: деньги — по способам оплаты, товар — на склад
- postПодтвердить, что деньги возврата отданы вне системы
Способы доставки
Способы доставки магазина: справочник, на который заказы и черновики ссылаются полем delivery_method_id.
Ручные способы оплаты
Ручные способы оплаты магазина, например банковский перевод, на которые ссылаются заказы и платежи.
Покупатели
Покупатели
Покупатели магазина с контактами, согласием на рассылки и адресной книгой. Всё это — персональные данные под scope customers:read.
- getПокупатели, изменённые с указанного момента: контакты, согласие на рассылки, адреса и группы; поиск по телефону, email и группе
- postСоздать покупателя: имя и хотя бы один контакт
- getПокупатель
- patchИзменить имя, язык и внешний id покупателя
- getПокупатель по внешнему id
- patchСоздать или изменить покупателя по внешнему id
- postНазначить покупателю оптовый прайс-лист или снять его
Адреса покупателей
Адресная книга покупателя: добавить, изменить, сделать основным, удалить.
Реквизиты покупателей
Реквизиты, под которыми выписываются документы новых заказов покупателя.
Группы покупателей
Ручные группы покупателей — аудитория скидок и рассылок: VIP, опт, персонал. Состав группы — поле group_ids покупателя.
- getГруппы покупателей магазина: имя, описание и активность
- postСоздать группу покупателей
- getГруппа покупателей
- patchИзменить имя, описание или активность группы
- deleteУдалить группу: членство уходит с ней, правила скидок и рассылки от неё отвязываются
- postДобавить покупателей в группу
- postСнять покупателей с группы
Учёт
Юрлица
Юрлица магазина: налоговый номер и статус, эмитенты фискальных документов. На них ссылаются документы и налоговые периоды.
Фискальные документы
Фактуры, кредит- и дебет-ноты продаж так, как их выпустила налоговая: номер, дата, налог, аннулирование и PDF.
- getФискальные документы, изменённые с указанного момента: фактуры, кредит- и дебет-ноты во всех статусах
- getФискальный документ
- getPDF фискального документа — тот же файл, что получает покупатель
- postВыпустить фактуру по закрытой продаже: выпуск идёт в фоне, итог — событием
- postПеревыпустить документ после сбоя или отказа налоговой
- postСнять отклонённый документ с контроля: выпускать его не будут
- postАннулировать выпущенную фактуру кредит-нотой
Налоговые периоды
Месяцы налогового учёта юрлиц: закрытый период сдан, и данные за него больше не меняются. Только у магазинов Аргентины.
Удержания и перцепции
Налог, удержанный у магазина, — его зачёт, и удержанный магазином у поставщика — к перечислению; сертификаты магазина в PDF.
Денежные счета
Счета, на которые приходят и с которых уходят деньги магазина: касса, банк, эквайринг, кошелёк. Остаток — в валюте счёта.
Статьи движений
Дерево статей приходов и расходов. Системную статью опознаёт system_code, а не имя.
Движения денег
Журнал приходов и расходов по счетам: сумма проводки, запись-источник и первичный документ.
- getДвижения денег, изменённые с указанного момента: приходы и расходы по счетам с источником и первичным документом
- postРучной доход или расход по денежному счёту
- getДвижение денег
- patchПравка движения денег: у движения с документом-источником — только статья, контрагент и описание
- deleteУдаление ручного движения денег с возвратом остатка счёта
Переводы между счетами
Перевод денег со счёта на счёт с комиссией: создание, правка и удаление. Части перевода — движения денег с transfer_id.
Курсы дня учёта
Курс валюты к валюте магазина на дату — по нему журнал денег пересчитывает валютные счета; для переоценки и сверки.
Кассовые смены
Смены касс со сверкой денежного ящика по каждой валюте: фонд открытия, ожидание, пересчёт, расхождение и оставленный размен.
Движения денежного ящика
Журнал ящика смены: продажи и возвраты налом, внесения, выдачи, сдача в сейф, размен и сторно. Только дописывается.
Причины внесения и выдачи
Причины, которые называет внесение или выдача наличных из ящика, со статьёй, которой журнал денег проводит движение.
Подарочные карты
Подарочные карты магазина: номинал, остаток и долг магазина по карте. Код карты не хранится и не отдаётся.
Журнал подарочных карт
Строки журнала карт: выпуск, погашение, возврат на карту, корректировка, аннулирование и блокировка. Только дописывается.
Счета покупателей
Книга долгов магазина: остаток каждого покупателя, кредитный лимит, срок оплаты и выписка за период со сроками долгов.
- getСчета покупателей в книге долгов: остаток, кредитный лимит и срок оплаты
- getСчёт покупателя
- getВыписка по счёту покупателя за период: долг на начало и конец, движения с нарастающим остатком и открытые долги со сроками
- postПогашение долга покупателя деньгами, которые уже пришли: запись в книгу долгов со справками об удержаниях
Журнал счетов покупателей
Записи книги долгов: продажа в долг, погашение, возврат, списание, взаимозачёт, удержание и сторно. Только дописывается.
Закупки
Поставщики
Справочник поставщиков: реквизиты, валюта закупки, отсрочка оплаты и вид расчётов, а ещё сальдо и акт сверки. Контактное лицо и заметки не отдаются.
- getПоставщики магазина: реквизиты и условия расчётов
- postСоздать поставщика: реквизиты и условия расчётов
- getПоставщик
- patchИзменить реквизиты, условия расчётов и внешний id поставщика
- getПоставщик по внешнему id
- patchСоздать или изменить поставщика по внешнему id
- getСальдо поставщика: сколько магазин должен сейчас, по слагаемым и срокам оплаты
- getАкт сверки с поставщиком за период: сальдо на начало и конец, строки с нарастающим остатком
Счета поставщиков
Кредиторка: фактуры, ноты дебета и кредита, долги по поставкам без фактуры — с НДС по ставкам, перцепциями и строками.
- getСчета поставщиков: фактуры, ноты и долги по поставкам без фактуры с налогом и строками
- postСоздать черновик счёта поставщика
- getСчёт поставщика
- patchИзменить черновик счёта поставщика
- deleteУдалить черновик счёта поставщика
- postПровести счёт поставщика: он войдёт в кредиторку и книгу покупок
- postАннулировать счёт поставщика вместе с его оплатами и зачётами
- postОдобрить проведённый счёт поставщика к оплате
- postОтозвать одобрение счёта поставщика к оплате
Оплаты счетов поставщиков
Чем и на сколько закрыт долг по счёту поставщика: деньги, зачёт, нота кредита, аванс, расход журнала или вне системы.
Соглашения о взаимозачёте
Основание взаимозачёта: стороны, двусторонний или трёхсторонний зачёт, номер и дата договора, срок действия и расписание регулярного зачёта.
Взаимозачёты
Документ зачёта встречных долгов: что магазину должен покупатель против того, что магазин должен поставщику. Аннулированный зачёт остаётся со статусом voided.
Строки взаимозачётов
Что именно зачтено: заказ или долг покупателя по книге долгов и счёт поставщика, с погашениями, которые создал зачёт.
Заказы поставщику
Что магазин заказал у поставщика: строки с заказанным, подтверждённым и принятым количеством, ценой и обещанной датой поставки.
- getЗаказы поставщику: заказано, подтверждено поставщиком и принято по строкам
- postСоздать черновик заказа поставщику
- getЗаказ поставщику
- patchИзменить заказ поставщику: черновик целиком, размещённый — строки, дату и примечание с ревизией
- deleteУдалить черновик заказа поставщику
- postОтметить черновик размещённым у поставщика
- postОтменить размещённый заказ поставщику
- postЗакрыть принятый заказ поставщику
Приёмки
Приход товара от поставщика: строки с ценой накладной и себестоимостью, корректировки «было → стало». Сторно отмечает voided_at.
Возвраты поставщику
Товар, отгруженный обратно поставщику: строки, ожидаемая и полученная компенсация — нота кредита, замена товаром или деньги.
Акты реализации
Отчёт поставщику о проданном за период товаре на реализации — основание его фактуры: разделы, строки и итоги.
Массовые операции
Загрузки
Большой файл, переданный частями: сервер считает принятые байты, и оборванная загрузка продолжается с них. Вход массовой операции.
Массовые операции
Тысячи записей одним запросом: установить остатки, записать товары, выгрузить заказы. Результат — NDJSON, строка на строку входа, докачивается диапазонами.
- getМассовые операции приложения, изменённые с указанного момента: прогресс и исходы
- postНачать массовую операцию по загрузке или адресу входа, выгрузку ленты или сборку файла
- getМассовая операция
- getРезультат массовой операции — NDJSON, строка на строку входа или элемент выгрузки, либо ZIP операции-файла; докачка — по Range
- postОтменить массовую операцию на границе строки
События и вебхуки
События
Что изменилось в магазине за последние 30 дней, вместе с записью в её нынешнем виде. Те же события уходят на адреса вебхуков.
Адреса вебхуков
Адреса, на которые магазин отправляет события с подписью Standard Webhooks; секрет подписи, его смена и тестовое событие.
- getАдреса вебхуков приложения
- postДобавить адрес вебхука и подписать его на типы событий
- getАдрес вебхука
- patchИзменить адрес вебхука: URL, подпись, типы событий, включение
- deleteУдалить адрес вебхука
- postВыпустить новый секрет подписи: прежний ещё 24 часа подписывает доставки вместе с ним
- getСекрет подписи доставок адреса вебхука
Доставки вебхуков
Что ушло на адрес, что ждёт повтора и что не доставлено, с ответами получателя; доставку можно повторить.
Параметры каждого запроса
Accept-LanguagestringЯзык текстов ошибок: es, en или ru. По умолчанию английский.
- Пример:
es
Заголовки каждого успешного ответа
RateLimitstringобязательноСколько запросов пройдёт подряд и через сколько секунд корзина снова полна — по каждой политике.
- Пример:
"app";r=87;t=3, "store";r=390;t=1
RateLimit-PolicystringобязательноПолитики лимитов: квота на окно в секундах.
- Пример:
"app";q=300;w=60, "store";q=1200;w=60
X-Request-IdstringобязательноИдентификатор запроса. Назовите его, когда пишете в поддержку.
Ошибки
Ошибки приходят в формате application/problem+json (RFC 9457). type — стабильный код, по которому ветвится обработка; title и detail — текст для людей на языке из Accept-Language.
Типы ошибок
| Статус | Тип | Что случилось |
|---|---|---|
| 401 | api_token_expired | Срок токена API истёк |
| 401 | api_token_invalid | Токен API недействителен |
| 401 | api_token_missing | Нужен токен API |
| 401 | api_token_revoked | Токен API отозван |
| 403 | capability_disabled | Ресурс недоступен этому магазину |
| 403 | forbidden | Доступ запрещён |
| 403 | insufficient_scope | Не хватает доступа |
| 403 | integration_api_not_in_plan | API для интеграций нет в тарифе |
| 403 | ip_not_allowed | Адрес не разрешён |
| 404 | not_found | Не найдено |
| 405 | method_not_allowed | Метод не разрешён |
| 409 | address_book_full | Адресная книга покупателя полна |
| 409 | bulk_operation_finished | Операция уже закончилась |
| 409 | bulk_operation_queue_full | Очередь операций приложения полна |
| 409 | bulk_operation_result_unavailable | Файла результата нет |
| 409 | consent_required | Нужно согласие на последствия |
| 409 | customer_contact_in_use | Контакт уже у покупателя магазина |
| 409 | draft_order_closed | Черновик заказа закрыт |
| 409 | external_id_archived | Запись с этим внешним id в архиве |
| 409 | external_id_in_use | Внешний id занят |
| 409 | fiscal_document_annul_refused | Фактуру не аннулировать |
| 409 | fiscal_document_dismiss_refused | Документ не снять с контроля |
| 409 | fiscal_document_pdf_unavailable | У документа нет файла |
| 409 | fiscal_document_reissue_refused | Документ не перевыпустить |
| 409 | idempotency_key_in_use | Запрос с этим ключом ещё исполняется |
| 409 | in_use_conflict | Запись используется |
| 409 | invoice_issue_refused | Фактуру по заказу сейчас не выпустить |
| 409 | money_transaction_locked | Движение не меняется руками |
| 409 | order_cancel_refused | Заказ нельзя отменить |
| 409 | order_transition_refused | Заказ нельзя перевести в этот статус |
| 409 | payment_not_confirmable | Платёж нельзя подтвердить |
| 409 | plan_limit_reached | Достигнут лимит тарифа |
| 409 | purchase_order_refused | Заказ поставщику не принимает эту команду |
| 409 | record_limit_reached | Достигнут потолок записей |
| 409 | refund_not_confirmable | Возврат не ждёт подтверждения выплаты |
| 409 | refund_refused | Заказ нельзя вернуть |
| 409 | shipment_in_progress | Выпуск отправления уже идёт |
| 409 | shipment_label_unavailable | Наклейки отправления нет |
| 409 | shipment_outcome_unknown | Исход прошлого выпуска неизвестен |
| 409 | shipment_refused | Отправление сейчас не выпустить |
| 409 | shipment_tracking_refused | Номер отслеживания вручную не записать |
| 409 | stock_held_by_write_offs | Остаток удержан списаниями на подтверждении |
| 409 | stock_on_hand_changed | Остаток изменился |
| 409 | supplier_bill_payment_locked | Оплату счёта не отменить напрямую |
| 409 | supplier_bill_refused | Счёт поставщика не принимает эту команду |
| 409 | tax_withholding_certificate_unavailable | Сертификата по записи нет |
| 409 | unique_conflict | Повтор значения |
| 409 | upload_offset_mismatch | Часть не с того места |
| 409 | webhook_endpoint_limit_reached | У приложения предельное число адресов вебхуков |
| 410 | cursor_expired | Курсор синхронизации устарел |
| 412 | precondition_failed | Запись изменилась |
| 416 | range_not_satisfiable | Диапазон за концом результата |
| 422 | idempotency_key_required | Нужен ключ идемпотентности |
| 422 | idempotency_key_reused | Ключ идемпотентности уже использован |
| 422 | invalid_idempotency_key | Ключ идемпотентности неверен |
| 422 | last_variant_of_product | Последний вариант товара |
| 422 | money_out_of_range | Сумма вне диапазона |
| 422 | validation_error | Неверный запрос |
| 428 | precondition_required | Нужен If-Match |
| 429 | too_many_requests | Слишком много запросов |
| 500 | server_error | Ошибка сервера |
| 503 | carrier_unavailable | Перевозчик не отвечает |
| 503 | store_frozen | Магазин заморожен |
| 503 | transient_conflict | Временный конфликт |
| зависит от запроса | http_error | Ошибка HTTP |
Тела ошибок
Problem
typestringобязательноМашинный тип отказа: стабильный код для ветвления, например insufficient_scope. У каждого типа есть страница в каталоге ошибок.
titlestringобязательноКраткое описание отказа на языке запроса.
statusintegerобязательноHTTP-статус ответа.
detailstringОбъяснение этого случая на языке запроса.
ForbiddenProblem
typestringобязательноМашинный тип отказа: стабильный код для ветвления, например insufficient_scope. У каждого типа есть страница в каталоге ошибок.
titlestringобязательноКраткое описание отказа на языке запроса.
statusintegerобязательноHTTP-статус ответа.
detailstringОбъяснение этого случая на языке запроса.
required_scopestringУ insufficient_scope — scope, который нужен методу.
accepted_scopesмассив stringУ insufficient_scope — scopes, которые метод принимает: хватит любого. У метода с одним scope — он один.
ValidationProblem
typestringобязательноМашинный тип отказа: стабильный код для ветвления, например insufficient_scope. У каждого типа есть страница в каталоге ошибок.
titlestringобязательноКраткое описание отказа на языке запроса.
statusintegerобязательноHTTP-статус ответа.
detailstringОбъяснение этого случая на языке запроса.
errorsсловарь массив stringобязательноПоля с ошибками: имя поля (вложенные — через точку, например variants.0.price) → сообщения.
RateLimitProblem
typestringобязательноМашинный тип отказа: стабильный код для ветвления, например insufficient_scope. У каждого типа есть страница в каталоге ошибок.
titlestringобязательноКраткое описание отказа на языке запроса.
statusintegerобязательноHTTP-статус ответа.
detailstringОбъяснение этого случая на языке запроса.
policystringобязательноКакая корзина исчерпана: app — приложения; store — магазина, общая для всех его приложений; rejected — запросов с одного адреса, отклонённых на входе.
- Значения:
appstorerejected
ConflictProblem
typestringобязательноМашинный тип отказа: стабильный код для ветвления, например insufficient_scope. У каждого типа есть страница в каталоге ошибок.
titlestringобязательноКраткое описание отказа на языке запроса.
statusintegerобязательноHTTP-статус ответа.
detailstringОбъяснение этого случая на языке запроса.
currentobjectЗапись сейчас — поля, о которых конфликт: on_hand у stock_on_hand_changed, status у отказа в смене заказа, status и order_id у закрытого черновика.
external_idstringУ external_id_in_use и external_id_archived — занятый внешний id.
consent_kindstringУ consent_required — вид последствия, на который нужно согласие.
consequencesсловарь integerУ consent_required — что изменится: вид данных → число записей.
- Минимум:
- 0
consent_tokenstringУ consent_required — отпечаток показанных последствий. Повторите запрос с consent[<consent_kind>]=<consent_token>.
variant_idintegerУ consent_required для строки варианта в записи товара — вариант: согласие даётся правкой этого варианта (PATCH /v1/variants/{variant}).
limitintegerУ plan_limit_reached, address_book_full, bulk_operation_queue_full и webhook_endpoint_limit_reached — потолок.
- Минимум:
- 0
fieldstringУ customer_contact_in_use — контакт, который принадлежит другому покупателю: phone или email.
- Значения:
phoneemail
existing_customer_idintegerУ customer_contact_in_use — покупатель, которому принадлежит контакт.
receivedintegerУ upload_offset_mismatch — сколько байт загрузка уже приняла: смещение, с которого продолжить.
- Минимум:
- 0
operation_statusstringУ bulk_operation_finished — статус, с которым операция закончилась.