Разработчикам

Справочник 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

Ресурсы

Основы

Каталог

Склад

Заказы и оплаты

Покупатели

Учёт

Закупки

Массовые операции

События и вебхуки

Параметры каждого запроса

  • 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.

Типы ошибок

СтатусТипЧто случилось
401api_token_expiredСрок токена API истёк
401api_token_invalidТокен API недействителен
401api_token_missingНужен токен API
401api_token_revokedТокен API отозван
403capability_disabledРесурс недоступен этому магазину
403forbiddenДоступ запрещён
403insufficient_scopeНе хватает доступа
403integration_api_not_in_planAPI для интеграций нет в тарифе
403ip_not_allowedАдрес не разрешён
404not_foundНе найдено
405method_not_allowedМетод не разрешён
409address_book_fullАдресная книга покупателя полна
409bulk_operation_finishedОперация уже закончилась
409bulk_operation_queue_fullОчередь операций приложения полна
409bulk_operation_result_unavailableФайла результата нет
409consent_requiredНужно согласие на последствия
409customer_contact_in_useКонтакт уже у покупателя магазина
409draft_order_closedЧерновик заказа закрыт
409external_id_archivedЗапись с этим внешним id в архиве
409external_id_in_useВнешний id занят
409fiscal_document_annul_refusedФактуру не аннулировать
409fiscal_document_dismiss_refusedДокумент не снять с контроля
409fiscal_document_pdf_unavailableУ документа нет файла
409fiscal_document_reissue_refusedДокумент не перевыпустить
409idempotency_key_in_useЗапрос с этим ключом ещё исполняется
409in_use_conflictЗапись используется
409invoice_issue_refusedФактуру по заказу сейчас не выпустить
409money_transaction_lockedДвижение не меняется руками
409order_cancel_refusedЗаказ нельзя отменить
409order_transition_refusedЗаказ нельзя перевести в этот статус
409payment_not_confirmableПлатёж нельзя подтвердить
409plan_limit_reachedДостигнут лимит тарифа
409purchase_order_refusedЗаказ поставщику не принимает эту команду
409record_limit_reachedДостигнут потолок записей
409refund_not_confirmableВозврат не ждёт подтверждения выплаты
409refund_refusedЗаказ нельзя вернуть
409shipment_in_progressВыпуск отправления уже идёт
409shipment_label_unavailableНаклейки отправления нет
409shipment_outcome_unknownИсход прошлого выпуска неизвестен
409shipment_refusedОтправление сейчас не выпустить
409shipment_tracking_refusedНомер отслеживания вручную не записать
409stock_held_by_write_offsОстаток удержан списаниями на подтверждении
409stock_on_hand_changedОстаток изменился
409supplier_bill_payment_lockedОплату счёта не отменить напрямую
409supplier_bill_refusedСчёт поставщика не принимает эту команду
409tax_withholding_certificate_unavailableСертификата по записи нет
409unique_conflictПовтор значения
409upload_offset_mismatchЧасть не с того места
409webhook_endpoint_limit_reachedУ приложения предельное число адресов вебхуков
410cursor_expiredКурсор синхронизации устарел
412precondition_failedЗапись изменилась
416range_not_satisfiableДиапазон за концом результата
422idempotency_key_requiredНужен ключ идемпотентности
422idempotency_key_reusedКлюч идемпотентности уже использован
422invalid_idempotency_keyКлюч идемпотентности неверен
422last_variant_of_productПоследний вариант товара
422money_out_of_rangeСумма вне диапазона
422validation_errorНеверный запрос
428precondition_requiredНужен If-Match
429too_many_requestsСлишком много запросов
500server_errorОшибка сервера
503carrier_unavailableПеревозчик не отвечает
503store_frozenМагазин заморожен
503transient_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 — статус, с которым операция закончилась.