Перейти к содержанию

Заказы и клиенты

Для работы с заказами и клиентами используйте авторизацию приложения в API бэк-офиса. Вход покупателя на витрину через session.json не даёт доступа к этим методам. Чтобы получить заказы конкретного клиента, передайте client_id в GET /admin/orders.json.

Сверка списков по updated_since и from_id — в изменившихся данных. Скидка на отдельные строки — в частичных скидках. Скидка внешней системы — в внешних скидках.

Заказы

В пути к заказу используется id — его идентификатор в API. Поле number содержит номер, который магазин показывает покупателю. Эти значения независимы: например, у заказа с id: 1 может быть number: 1000, а следующий заказ получит номер 1001.

GET /admin/orders/1000.json, где 1000 — номер, а не id, отвечает 404. Тело при Accept: application/json остаётся HTML-страницей.

Карточка заказа содержит поля заказа, строки order_lines, клиента client, адрес shipping_address и скидки discounts. Поле discount дублирует первую скидку из массива.

У строки заказа есть sale_price, full_sale_price, total_price, full_total_price, quantity, variant_id, product_id и bundle_id. Вложенный объект client содержит меньше данных, чем карточка клиента: в нём нет default_address, client_tags и full_name.

custom_status — объект с permalink и title. fulfillment_status — системный статус исполнения: new, accepted, approved, dispatched, delivered, returning, declined, returned. financial_status — оплата: pending, paid, partially_paid.

Список и количество заказов

GET /admin/orders.json возвращает массив заказов. По умолчанию на странице 25 записей, отсортированных по убыванию id. Если per_page больше 100, API использует 100. Значение per_page=1 возвращает одну запись, per_page=0 — пустой массив.

Нумерация page начинается с 1. При page=0 API возвращает 422 и {"message":"page должен иметь значение, большее 0"}.

GET /admin/orders/count.json возвращает количество заказов, соответствующих переданным фильтрам: {"count": N}.

GET/admin/orders.json?per_page=1
Параметр Описание
per_page необязательный
число		 Количество заказов на странице. При значении больше 100 API использует 100. При 0 возвращает пустой массив.
page необязательный
число		 Номер страницы, начиная с 1. 
GET /admin/orders.json?per_page=1
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {
    "id": 4,
    "number": 1003,
    "fulfillment_status": "new",
    "financial_status": "pending",
    "total_price": 15.0,
    "custom_status": {"permalink": "new", "title": "Новый"}
  }
]

У списка нет заголовка с числом страниц. Число записей читается отдельным запросом, с теми же фильтрами.

GET/admin/orders/count.json?client_id=1
Параметр Описание
client_id необязательный
число		 Считать заказы этого клиента. 
GET /admin/orders/count.json?client_id=1
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

{"count": 2}

Фильтрация

Чтобы найти заказ по номеру, задайте одинаковые number_from и number_to. Для диапазона укажите разные границы. Параметр number не фильтрует список.

from_number оставляет заказы с номером больше либо равным переданному. Номер больше последнего даёт пустой массив.

client_id ограничивает список заказами одного клиента. Для нескольких идентификаторов повторите параметр ids[]. Параметры fulfillment_status, delivery_variant_id и payment_gateway_id требуют точного совпадения. Параметр q использует поиск магазина; строка, для которой нет совпадений, возвращает [].

С status=open возвращаются заказы в работе, в том числе доставленные, но ещё не оплаченные. С status=closed возвращаются отменённые, возвращённые, а также доставленные и оплаченные заказы.

custom_status сравнивает permalink пользовательского статуса. Несколько значений передаются повторением параметра.

Одиночный параметр financial_status=paid возвращает оплаченные заказы. Любое другое одиночное значение, включая pending и partially_paid, возвращает все заказы со статусом оплаты, отличным от paid. Чтобы выбрать точные статусы, используйте массив financial_status[].

API принимает created_at_from и created_at_to со статусом 200, но запрос за календарный день может вернуть пустой список, даже если в этот день есть заказы. Для чтения изменений используйте updated_since.

При заданном updated_since заказы сортируются по возрастанию updated_at, затем по id. Поэтому при per_page=1 возвращается самый старый из подходящих заказов. В следующем запросе передайте его updated_at как updated_since, а id — как from_id: этот заказ повторно не вернётся. Последовательность обхода описана в статье «Получение только изменившихся данных».

GET/admin/orders.json?number_from=1001&number_to=1001
Параметр Описание
number_from необязательный
число		 Нижняя граница номера, включительно.
number_to необязательный
число		 Верхняя граница номера, включительно. 
GET /admin/orders.json?number_from=1001&number_to=1001
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {"id": 2, "number": 1001}
]
GET/admin/orders.json?financial_status=partially_paid
Параметр Описание
financial_status необязательный
строка		 paid — только оплаченные. Другая одиночная строка — все, кроме оплаченных. 
GET /admin/orders.json?financial_status=partially_paid
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {"id": 2, "number": 1001, "financial_status": "pending"},
  {"id": 1, "number": 1000, "financial_status": "pending"}
]
GET/admin/orders.json?financial_status[]=paid&financial_status[]=pending
Параметр Описание
financial_status[] необязательный
массив строк		 Точный список статусов оплаты. 
GET /admin/orders.json?financial_status[]=paid&financial_status[]=pending
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {"id": 2, "financial_status": "pending"},
  {"id": 1, "financial_status": "pending"}
]
GET/admin/orders.json?created_at_from=2026-10-21&created_at_to=2026-10-21
Параметр Описание
created_at_from необязательный
строка		 Нижняя календарная граница, `YYYY-MM-DD`.
created_at_to необязательный
строка		 Верхняя календарная граница, `YYYY-MM-DD`. 
GET /admin/orders.json?created_at_from=2026-10-21&created_at_to=2026-10-21
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[]

Чтобы получить заказы клиента за период, ограничьте список параметром client_id. Дату создания проверяйте по created_at полученных заказов; если нужен период изменения, используйте updated_since.

Архив

По умолчанию архивные заказы не возвращаются ни в списке, ни при чтении карточки. Запрос к карточке архивного заказа возвращает 404 с HTML-страницей.

Параметр deleted=true возвращает только архивные заказы, with_deleted=true — текущие и архивные. У архивного заказа archived равен true. Эти флаги применяются к списку, карточке и подсчёту заказов.

GET/admin/orders/2.json?with_deleted=true
Параметр Описание
id обязательный
число		 Идентификатор заказа.
with_deleted необязательный
строка		 true — отдать заказ и из архива.
deleted необязательный
строка		 true — только архивный заказ. 
GET /admin/orders/2.json?with_deleted=true
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

{"id": 2, "number": 1001, "archived": true}

Создание с товаром

Для создания заказа передайте объект order в POST /admin/orders.json. Строки заказа задаются через order_lines_attributes. Поле order_lines при создании игнорируется: если строки не заданы, API вернёт 422 и сообщение «Заказ должен содержать хотя бы одну позицию».

Для строки достаточно указать variant_id и quantity. Если передать только product_id, InSales выберет первый вариант товара. Если передать sale_price, это значение станет ценой строки и будет использоваться при расчёте суммы заказа.

Передайте адрес объектом shipping_address, указав населённый пункт в full_locality_name. В сообщениях об ошибках это поле называется «Населенный пункт». Отдельные город и регион не заменяют full_locality_name. Если телефон и согласие на обработку персональных данных обязательны в настройках магазина, их тоже нужно передать.

Параметры delivery_variant_id и payment_gateway_id выбирают способы доставки и оплаты. При создании заказа цена доставки берётся из настроек способа.

Для внешней доставки передайте тариф и точку самовывоза в delivery_info_attributes: поля tariff_id, price, title и outlet. Для DeliveryVariant::PickUp укажите в outlet координаты latitude и longitude. Без них API вернёт 422 и сообщение «Не выбрана точка самовывоза».

Поля способов описаны в разделах «Доставка» и «Способы оплаты». Чтобы отключить письма клиенту и магазину, используйте соответственно not_send_email_to_client и not_send_email_to_account.

Клиента можно передать вложенным объектом client или указать идентификатор существующего клиента в client_id. Во вложенном объекте сохраняются имя, почта, телефон и согласие. Чтобы записать фамилию и отчество, сначала создайте клиента отдельным запросом, затем передайте его client_id в заказ.

Без населённого пункта и согласия ответ 422:

{
  "full_locality_name": [["Не заполнено обязательное поле \"Населенный пункт\""]],
  "consent_to_personal_data": [["Не заполнено обязательное поле \"Согласие на обработку персональных данных\""]]
}
POST/admin/orders.json
Параметр Описание
order[order_lines_attributes][][variant_id] обязательный
число		 Вариант товара. Вместо него можно передать product_id, тогда берётся первый вариант.
order[order_lines_attributes][][quantity] обязательный
число		 Количество.
order[order_lines_attributes][][sale_price] необязательный
число		 Своя цена строки. Пустое значение оставляет цену варианта.
order[order_lines_attributes][][comment] необязательный
строка		 Комментарий строки.
order[client][name] необязательный
строка		 Имя нового клиента.
order[client][email] необязательный
строка		 Почта нового клиента.
order[client][phone] необязательный
строка		 Телефон. Обязателен, если поле включено в настройках магазина.
order[client][consent_to_personal_data] обязательный
логический		 Согласие. Обязательно, если поле включено в настройках магазина.
order[client_id] необязательный
число		 Уже существующий клиент вместо объекта client.
order[shipping_address][full_locality_name] обязательный
строка		 Населённый пункт, например «г Москва».
order[shipping_address][address] необязательный
строка		 Улица и дом.
order[shipping_address][zip] необязательный
строка		 Индекс.
order[delivery_variant_id] обязательный
число		 Способ доставки.
order[payment_gateway_id] обязательный
число		 Способ оплаты.
order[comment] необязательный
строка		 Комментарий покупателя.
order[manager_comment] необязательный
строка		 Служебный комментарий.
order[coupon] необязательный
строка		 Код промокода. 
POST /admin/orders.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "order": {
    "order_lines_attributes": [
      {
        "variant_id": 2176487172,
        "quantity": 2,
        "comment": "строка docs-api"
      }
    ],
    "client": {
      "name": "Докс",
      "email": "docs-api-order2@example.com",
      "phone": "+79990001102",
      "consent_to_personal_data": true
    },
    "shipping_address": {
      "name": "Докс Апи",
      "phone": "+79990001102",
      "address": "ул. Документации, 1",
      "full_locality_name": "г Москва",
      "zip": "101000"
    },
    "delivery_variant_id": 17,
    "payment_gateway_id": 6101770,
    "comment": "docs-api заказ с товаром",
    "manager_comment": "служебный",
    "not_send_email_to_account": true,
    "not_send_email_to_client": true
  }
}

Ответ · 201

{
  "id": 3,
  "number": 1002,
  "comment": "docs-api заказ с товаром",
  "manager_comment": "служебный",
  "fulfillment_status": "new",
  "financial_status": "pending",
  "custom_status": {"permalink": "new", "title": "Новый"},
  "items_price": 200.0,
  "delivery_price": 300.0,
  "total_price": 500.0,
  "delivery_variant_id": 17,
  "delivery_title": "Курьером",
  "payment_gateway_id": 6101770,
  "payment_title": "Наличными или картой при получении",
  "currency_code": "RUR",
  "order_lines": [
    {
      "id": 3,
      "variant_id": 2176487172,
      "product_id": 625,
      "quantity": 2,
      "sale_price": 100.0,
      "full_total_price": 200.0,
      "comment": "строка docs-api",
      "bundle_id": null,
      "title": "Футболка (Красный)"
    }
  ],
  "client": {
    "id": 9,
    "name": "Докс",
    "email": "docs-api-order2@example.com",
    "phone": "+79990001102",
    "registered": false,
    "type": "Client::Individual",
    "consent_to_personal_data": true
  },
  "shipping_address": {
    "full_locality_name": "г Москва",
    "address": "ул. Документации, 1",
    "zip": "101000",
    "full_delivery_address": "101000, г Москва, ул. Документации, 1"
  }
}

Без number магазин назначает следующий номер. number в PUT уже выданный номер не меняет.

Создание с комплектом

Для заказа комплекта передайте в строке variant_id комплекта. При сохранении InSales заменяет эту строку составляющими. У каждой из них bundle_id содержит идентификатор товара-комплекта. Количество составляющей равно её количеству в комплекте, умноженному на количество комплектов в заказе. Сумма цен составляющих равна цене комплекта.

Тот же вариант может быть добавлен в заказ отдельной строкой. У неё будет такой же variant_id, как у составляющей комплекта, но пустой bundle_id. Поэтому для скидки выбирайте строку по order_lines[].id, как описано в статье «Частичные скидки в заказе».

Комплект ниже собран из варианта за 100 и двух штук варианта за 1, цена комплекта 90. В заказе одна штука комплекта и одна отдельная штука первого варианта.

POST/admin/orders.json
Параметр Описание
order[order_lines_attributes][][variant_id] обязательный
число		 Вариант комплекта или обычного товара.
order[order_lines_attributes][][quantity] обязательный
число		 Сколько комплектов или отдельных единиц.
order[client_id] обязательный
число		 Клиент заказа.
order[shipping_address][full_locality_name] обязательный
строка		 Населённый пункт.
order[delivery_variant_id] обязательный
число		 Способ доставки.
order[payment_gateway_id] обязательный
число		 Способ оплаты. 
POST /admin/orders.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "order": {
    "client_id": 41,
    "order_lines_attributes": [
      {"variant_id": 2176487183, "quantity": 1},
      {"variant_id": 2176487172, "quantity": 1}
    ],
    "shipping_address": {
      "name": "Садресом",
      "phone": "+79990001122",
      "full_locality_name": "г Москва",
      "address": "ул. Клиента, 5"
    },
    "delivery_variant_id": 9,
    "payment_gateway_id": 6101770,
    "not_send_email_to_account": true,
    "not_send_email_to_client": true
  }
}

Ответ · 201

{
  "id": 9,
  "number": 1008,
  "items_price": 190.0,
  "total_price": 190.0,
  "order_lines": [
    {
      "id": 10,
      "title": "Футболка (Красный)",
      "product_id": 625,
      "variant_id": 2176487172,
      "bundle_id": 689,
      "quantity": 1,
      "sale_price": 88.24,
      "full_total_price": 88.24
    },
    {
      "id": 11,
      "title": "Подарочная упаковка",
      "product_id": 617,
      "variant_id": 2176487171,
      "bundle_id": 689,
      "quantity": 2,
      "sale_price": 0.88,
      "full_total_price": 1.76
    },
    {
      "id": 12,
      "title": "Футболка (Красный)",
      "product_id": 625,
      "variant_id": 2176487172,
      "bundle_id": null,
      "quantity": 1,
      "sale_price": 100.0,
      "full_total_price": 100.0
    }
  ]
}

88,24 и 1,76 в сумме дают 90 — цену комплекта. Отдельная строка осталась по 100. Итог заказа 190, самовывоз добавил 0 к доставке.

Строки и адрес

Для изменения заказа используйте PUT /admin/orders/:id.json. В order_lines_attributes передавайте id для изменения существующей строки, элемент без id — для добавления новой. Чтобы удалить строку, передайте её id и _destroy: true.

Для изменения адреса передайте shipping_address_attributes с идентификатором адреса id. Поле delivery_price заменяет стоимость доставки переданным числом, после чего итог заказа пересчитывается. Поле manager_comment сохраняет комментарий менеджера.

PUT/admin/orders/3.json
Параметр Описание
order[order_lines_attributes][][id] необязательный
число		 Строка, которую меняют. Без id добавляется новая строка.
order[order_lines_attributes][][quantity] необязательный
число		 Новое количество.
order[order_lines_attributes][][sale_price] необязательный
число		 Новая цена строки.
order[order_lines_attributes][][variant_id] необязательный
число		 Вариант новой строки.
order[order_lines_attributes][][_destroy] необязательный
логический		 true удаляет строку с этим id.
order[shipping_address_attributes][id] необязательный
число		 id адреса заказа.
order[shipping_address_attributes][address] необязательный
строка		 Новая улица и дом.
order[shipping_address_attributes][full_locality_name] необязательный
строка		 Населённый пункт.
order[delivery_price] необязательный
число		 Сумма доставки, как её нужно записать.
order[manager_comment] необязательный
строка		 Служебный комментарий. 
PUT /admin/orders/3.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "order": {
    "order_lines_attributes": [
      {"id": 3, "quantity": 1, "sale_price": 80},
      {"variant_id": 2176487171, "quantity": 3}
    ],
    "shipping_address_attributes": {
      "id": 3,
      "address": "ул. Документации, 2",
      "full_locality_name": "г Москва",
      "surname": "Апи",
      "name": "Докс",
      "phone": "+79990001102"
    },
    "delivery_price": 50,
    "manager_comment": "собрать отдельно"
  }
}

Ответ · 200

{
  "id": 3,
  "number": 1002,
  "items_price": 83.0,
  "delivery_price": 50.0,
  "total_price": 133.0,
  "manager_comment": "собрать отдельно",
  "order_lines": [
    {"id": 4, "variant_id": 2176487171, "quantity": 3, "sale_price": 1.0, "full_total_price": 3.0},
    {"id": 3, "variant_id": 2176487172, "quantity": 1, "sale_price": 80.0, "full_total_price": 80.0, "comment": "строка docs-api"}
  ],
  "shipping_address": {
    "address": "ул. Документации, 2",
    "full_locality_name": "г Москва",
    "surname": "Апи"
  }
}

Удаление второй строки тем же PUT с _destroy: true оставило одну строку и итог 130 при доставке 50.

Статусы

Статус financial_status: "paid" заполняет paid_at и устанавливает paid_amount по текущей сумме заказа. При partially_paid заказ не считается полностью оплаченным, а paid_at сбрасывается. Если затем уменьшить сумму заказа, уже записанный paid_amount автоматически не уменьшится.

fulfillment_status переводит заказ в системный статус и подставляет permalink статуса по умолчанию для этого системного статуса. delivered заполняет delivered_at и ставит custom_status в dostavlen («Доставлен»).

Чтобы назначить пользовательский статус, передайте его permalink в custom_status_permalink. InSales также установит связанный с ним системный статус. Если передать в этом поле системный код (new, accepted, approved и другие из списка выше), он будет записан как fulfillment_status.

Если одновременно передать несовместимые fulfillment_status и custom_status_permalink, API вернёт 422:

{"message": "incompatible fulfillment and custom statuses"}

Неизвестное значение fulfillment_status отклоняется со статусом 422 и сообщением «имеет непредусмотренное значение».

Параметр version содержит время updated_at в целых секундах. Если заказ изменился позже переданного version, API вернёт 409 с телом {}.

История изменений возвращается в order_changes. У каждой записи есть action, value_was, value_is, created_at, full_description и user_name. Для запроса приложения user_name содержит название ключа доступа. При смене системного статуса action равен fulfillment_status_changed.

PUT/admin/orders/4.json
Параметр Описание
order[custom_status_permalink] необязательный
строка		 Permalink пользовательского статуса. Системный код записывается как fulfillment_status.
order[fulfillment_status] необязательный
строка		 Системный статус исполнения.
order[financial_status] необязательный
строка		 pending, paid или partially_paid.
order[version] необязательный
число		 Время updated_at в секундах. Более старое значение даёт 409. 
PUT /admin/orders/4.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "order": {
    "custom_status_permalink": "docs-api-sborka"
  }
}

Ответ · 200

{
  "id": 4,
  "fulfillment_status": "approved",
  "custom_status": {
    "permalink": "docs-api-sborka",
    "title": "docs-api сборка 2"
  }
}

Промокод, группа и бонусы в заказе

Чтобы применить промокод при создании заказа, передайте его в coupon. Регистр не учитывается: DOCSAPI10 и docsapi10 обозначают один код. Скидка возвращается в discounts, а поле discount дублирует первую скидку.

Для строки стоимостью 100 код на 10% даёт итог 90, код на 50 рублей — итог 50. Повторное использование кода с act_once: true отклоняется со статусом 422: «Указан несуществующий купон, убедитесь, что он введен верно».

Если клиент входит в группу со скидкой 15%, при стоимости строки 100 итог заказа составит 85. Скидка возвращается в discounts с reference_type: ClientGroup. При этом sale_price остаётся 100, а discounts_amount строки — 0. Поля заказа items_price и total_price уже учитывают скидку 15.

Для списания бонусных баллов передайте use_bonus_points: true и количество в client_bonus_points. Например, если у клиента 50 баллов, списание 20 даёт скидку 20 и оставляет 30 баллов. При стоимости товаров 100 итог составит 80. В discounts у такой скидки reference_type равен BonusSystem, описание — «Скидка по бонусной программе». Начисление баллов описано в разделе «Бонусные транзакции».

POST/admin/orders.json
Параметр Описание
order[coupon] необязательный
строка		 Код промокода, регистр не важен.
order[client_id] обязательный
число		 Клиент.
order[use_bonus_points] необязательный
логический		 true списывает баллы клиента.
order[client_bonus_points] необязательный
число		 Сколько баллов списать.
order[order_lines_attributes][][variant_id] обязательный
число		 Вариант товара.
order[order_lines_attributes][][quantity] обязательный
число		 Количество. 
POST /admin/orders.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "order": {
    "client_id": 57,
    "use_bonus_points": true,
    "client_bonus_points": 20,
    "order_lines_attributes": [
      {"variant_id": 2176487172, "quantity": 1}
    ],
    "shipping_address": {
      "name": "Бонус",
      "phone": "+79990001130",
      "full_locality_name": "г Москва",
      "address": "ул. Бонуса, 1"
    },
    "delivery_variant_id": 9,
    "payment_gateway_id": 6101770,
    "not_send_email_to_account": true,
    "not_send_email_to_client": true
  }
}

Ответ · 201

{
  "total_price": 80.0,
  "items_price": 80.0,
  "discounts": [
    {
      "description": "Скидка по бонусной программе",
      "discount": "20.0",
      "type_id": 2,
      "reference_type": "BonusSystem"
    }
  ]
}

Дополнительное поле

Список полей можно прочитать, если у приложения есть право читать заказы. Создавать и менять поле можно, если есть право на настройки магазина.

GET /admin/fields.json возвращает одним массивом дополнительные поля заказа, клиента, адреса и контактов. Удалённые поля в ответ не включаются.

Поле destiny определяет, к какому объекту относится дополнительное поле:

Число Куда относится
1 Адрес доставки
2 Клиент, физическое лицо
3 Заказ
5 Клиент, юридическое лицо
6 Контакты

destiny 4 — строка заказа. Создание такого поля отвечает 500, тело — HTML-страница.

Типы, которые можно создать:

  • адрес: Field::TextField, Field::TextArea, Field::Select, Field::Checkbox;
  • физлицо, юрлицо и контакты: те же и Field::DateField;
  • заказ: те же, Field::DateField и Field::FileField.

Field::Phone и поле без type отвечают 404, тело — HTML-страница. Системные поля (system_name заполнен) этим запросом не создаются: имя, телефон, email, населённый пункт уже есть в списке.

handle — латиница, цифры, _ и -. Иначе 422, тело {"handle":["имеет неверное значение"]}. handle уникален в магазине.

POST/admin/fields.json
Параметр Описание
field[type] обязательный
строка		 Класс поля из списка выше.
field[destiny] обязательный
число		 1 адрес, 2 физлицо, 3 заказ, 5 юрлицо, 6 контакты.
field[office_title] обязательный
строка		 Название в бэк-офисе.
field[title] необязательный
строка		 Название для покупателя.
field[handle] необязательный
строка		 Код поля. Латиница, цифры, _ и -.
field[obligatory] необязательный
логический		 Обязательность. По умолчанию false.
field[for_buyer] необязательный
логический		 Показывать покупателю.
field[example] необязательный
строка		 Пример значения.
field[show_in_checkout] необязательный
логический		 Показывать в чекауте.
field[show_in_result] необязательный
логический		 Показывать в результате заказа. 
POST /admin/fields.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "field": {
    "type": "Field::TextField",
    "destiny": 3,
    "office_title": "docs-api комментарий",
    "title": "Комментарий к заказу",
    "handle": "docs_api_comment",
    "obligatory": false,
    "for_buyer": true,
    "show_in_checkout": true,
    "example": "Позвоните за час"
  }
}

Ответ · 201

{
  "id": 193,
  "destiny": 3,
  "position": 2,
  "office_title": "docs-api комментарий",
  "title": "Комментарий к заказу",
  "handle": "docs_api_comment",
  "type": "Field::TextField",
  "example": "Позвоните за час",
  "for_buyer": true,
  "obligatory": false,
  "active": true,
  "system_name": null,
  "show_in_checkout": true,
  "show_in_result": true
}

Тот же запрос с Field::Checkbox и destiny 3, с Field::DateField и destiny 5, с Field::FileField и destiny 3, с Field::TextArea и destiny 6 отвечает 201.

Выпадающий список — Field::Select. Варианты — field_options_attributes, не меньше двух непустых value. Один вариант отвечает 422, тело {"base":["Вариантов выбора не должно быть меньше 2."]}. В ответе у списка есть field_options: id, position, value.

POST/admin/fields.json
Параметр Описание
field[type] обязательный
строка		 Field::Select.
field[destiny] обязательный
число		 2 — поле физического лица.
field[office_title] обязательный
строка		 Название в бэк-офисе.
field[field_options_attributes] обязательный
массив		 Не меньше двух вариантов. У элемента value и position. 
POST /admin/fields.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "field": {
    "type": "Field::Select",
    "destiny": 2,
    "office_title": "docs-api менеджер",
    "title": "Менеджер",
    "handle": "docs_api_manager",
    "field_options_attributes": [
      {"value": "Анна", "position": 1},
      {"value": "Борис", "position": 2}
    ]
  }
}

Ответ · 201

{
  "id": 201,
  "destiny": 2,
  "type": "Field::Select",
  "office_title": "docs-api менеджер",
  "title": "Менеджер",
  "handle": "docs_api_manager",
  "field_options": [
    {"id": 1, "position": 1, "value": "Анна"},
    {"id": 9, "position": 2, "value": "Борис"}
  ]
}

При обновлении через PUT можно изменить название поля и варианты списка. Поля type и destiny игнорируются: тип и назначение дополнительного поля остаются прежними. Элемент вариантов без id добавляет новый вариант; элемент с id меняет его value.

PUT/admin/fields/201.json
Параметр Описание
id обязательный
число		 id поля в пути.
field[title] необязательный
строка		 Новое название для покупателя.
field[field_options_attributes] необязательный
массив		 Существующий вариант с id, новый — без id. 
PUT /admin/fields/201.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "field": {
    "title": "Ваш менеджер",
    "type": "Field::TextField",
    "destiny": 3,
    "field_options_attributes": [
      {"id": 9, "value": "Вера"},
      {"value": "Галина", "position": 3}
    ]
  }
}

Ответ · 200

{
  "id": 201,
  "destiny": 2,
  "type": "Field::Select",
  "title": "Ваш менеджер",
  "field_options": [
    {"id": 1, "position": 1, "value": "Анна"},
    {"id": 9, "position": 2, "value": "Вера"},
    {"id": 17, "position": 3, "value": "Галина"}
  ]
}

DELETE созданного текстового поля, списка, флажка, даты, файла и многострочного текста отвечает 200 и {"status":"ok"}. Системное поле, например имя с id 9, отвечает 422, тело {"base":["Данное поле нельзя удалять"]}. Неизвестный id — 404 и HTML-страница.

Значение в заказе пишется массивом fields_values_attributes с field_id и value. В карточке у значения есть name (служебное название поля) и type «Текст».

PUT/admin/orders/3.json
Параметр Описание
order[fields_values_attributes][][field_id] обязательный
число		 id поля.
order[fields_values_attributes][][value] обязательный
строка		 Значение. 
PUT /admin/orders/3.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "order": {
    "fields_values_attributes": [
      {"field_id": 241, "value": "хрупкое"}
    ]
  }
}

Ответ · 200

{
  "fields_values": [
    {
      "id": 1,
      "field_id": 241,
      "value": "хрупкое",
      "name": "docs-api склад",
      "type": "Текст"
    }
  ]
}

Задачи пользователя

Список задач можно прочитать, если у приложения есть право читать заказы. Создавать и менять задачу можно, если есть право изменять информацию заказа.

GET /admin/user_tasks.json возвращает массив задач без общего количества записей. У задачи есть id, complete, order_id, assignee_id, title, description, created_at, updated_at, deadline_at и order. Если задача связана с заказом, order содержит объект {id, number}; иначе в списке возвращается null. Данные автора в JSON не включаются.

assignee_id — идентификатор пользователя магазина. У запроса приложения assignee=me выбирает задачи с пустым assignee_id.

Создание задачи возвращает 200. Если deadline_at не передан, срок устанавливается на один час позже времени создания.

Если complete не передан, поле сохраняется как null. Явно переданное false сохраняется как false. Фильтр complete=false не включает задачи с null. Для фильтрации используйте строки true или false: значение complete=1 не включает фильтр. Если одновременно переданы completed и complete, применяется completed.

API сохраняет order_id и assignee_id, даже если соответствующего заказа или пользователя нет. Для несуществующего заказа объект order отсутствует в ответе создания, а в списке равен null.

title обязателен, длиннее 1000 символов отвечает 422, тело {"title":["слишком большой длины (не может быть больше чем 1000 символов)"]}. Пустой title при изменении отвечает 422, тело {"title":["Не заполнены обязательные поля"]}.

Создание

POST/admin/user_tasks.json
Параметр Описание
title обязательный
строка		 Текст задачи, до 1000 символов.
description необязательный
строка		 Пояснение.
order_id необязательный
число		 Идентификатор заказа. Сохраняется и для неизвестного заказа.
assignee_id необязательный
число		 Идентификатор пользователя магазина.
complete необязательный
логический		 false остаётся false. Без поля в ответе null.
deadline_at необязательный
строка		 Срок. Без поля — час после создания. 
POST /admin/user_tasks.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "user_task": {
    "title": "docs-api отгрузить",
    "description": "до полудня",
    "order_id": 4,
    "assignee_id": 6178456,
    "complete": false,
    "deadline_at": "2026-12-01T10:00:00.000+03:00"
  }
}

Ответ · 200

{
  "id": 3,
  "complete": false,
  "order_id": 4,
  "assignee_id": 6178456,
  "title": "docs-api отгрузить",
  "description": "до полудня",
  "created_at": "2026-10-21T22:22:39.999+03:00",
  "updated_at": "2026-10-21T22:22:39.999+03:00",
  "deadline_at": "2026-12-01T10:00:00.000+03:00",
  "order": {
    "id": 4,
    "number": 1003
  }
}

Тело без обёртки user_task тоже создаёт задачу и отвечает 200.

Список

По умолчанию задачи сортируются по complete, затем по deadline_at. Для выбора сортировки передайте sort: title, created_at, deadline_at или status. Другие значения не меняют сортировку. Параметр sort_order задаёт направление: asc или desc.

Размер страницы задаётся через per_page или limit в диапазоне от 25 до 1000. Значения за пределами диапазона заменяются ближайшей границей. Если переданы оба параметра, используется limit. Нумерация page начинается с 1. Для страницы за концом списка возвращается [].

q ищет без учёта регистра по названию, описанию, имени автора, имени исполнителя и по номеру заказа, если строка — целое меньше 2^31.

GET/admin/user_tasks.json?complete=true&order_id=4
Параметр Описание
complete необязательный
строка		 true или false. Значение 1 не включает фильтрацию.
completed необязательный
строка		 То же, что complete. Если переданы оба, действует completed.
order_id необязательный
число		 Задачи этого заказа.
assignee_id необязательный
число		 Задачи этого пользователя.
assignee необязательный
строка		 me — задачи с пустым исполнителем, у запроса приложения пользователя нет.
q необязательный
строка		 Поиск по тексту и по номеру заказа.
sort необязательный
строка		 title, created_at, deadline_at или status.
sort_order необязательный
строка		 asc или desc.
per_page необязательный
число		 Размер страницы. Ниже 25 становится 25, выше 1000 — 1000.
limit необязательный
число		 То же ограничение. Если передан вместе с per_page, берётся он.
page необязательный
число		 Номер страницы, начиная с 1. 
GET /admin/user_tasks.json?complete=true&order_id=4
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {
    "id": 3,
    "complete": true,
    "order_id": 4,
    "assignee_id": 6178456,
    "title": "docs-api отгружено",
    "description": "уточнение",
    "created_at": "2026-10-21T22:22:39.999+03:00",
    "updated_at": "2026-10-21T22:22:40.923+03:00",
    "deadline_at": "2026-12-01T10:00:00.000+03:00",
    "order": {
      "id": 4,
      "number": 1003
    }
  }
]

page=0 отвечает 422.

GET/admin/user_tasks.json?page=0
Параметр Описание
page обязательный
число		 Ноль и отрицательное значение не принимаются. 
GET /admin/user_tasks.json?page=0
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 422

{
  "message": "page должен иметь значение, большее 0"
}

GET /admin/user_tasks/ID.json возвращает одну задачу. Неизвестный id отвечает 404, тело — HTML-страница. PUT и PATCH отвечают 200. DELETE отвечает 200 с пустым телом.

Клиенты

Карточка клиента содержит контакты, type, registered, subscribe, bonus_points, client_group_id, fields_values, default_address, client_tags и full_name. У физлица есть surname и middlename. У юрлица есть inn, kpp, ogrn, juridical_address, bank_name, bik, correspondent_account, settlement_account. full_name физлица собирается как фамилия, имя и отчество.

Параметры orders_count=1, turnover=1 и last_order=1 добавляют в ответ количество заказов, оборот и сведения о последнем заказе. В обороте учитываются только оплаченные заказы, а в количестве — также неоплаченные. Поэтому у клиента только с неоплаченными заказами turnover равен 0.0. Значения last_order_id и last_order_number определяются по дате создания заказа.

Список

GET /admin/clients.json возвращает массив клиентов. Размер страницы ограничен диапазоном от 10 до 500: меньшее значение заменяется на 10, большее — на 500. Заголовок X-TOTAL-PAGES содержит количество страниц.

q ищет подстроку в фамилии, имени, отчестве, телефоне и почте. type=individual и type=juridical различают физлицо и юрлицо. created_at_from и created_at_to ограничивают день создания. orders_count_from и orders_count_to сравнивают число заказов. updated_since и from_id работают так же, как у изменившихся данных.

Удалённый клиент из списка уходит. GET по его id отвечает 404 с HTML-телом.

GET/admin/clients/9.json?orders_count=1&turnover=1&last_order=1
Параметр Описание
orders_count необязательный
строка		 1 добавляет число заказов.
turnover необязательный
строка		 1 добавляет сумму оплаченных заказов.
last_order необязательный
строка		 1 добавляет id и номер последнего заказа. 
GET /admin/clients/9.json?orders_count=1&turnover=1&last_order=1
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

{
  "id": 9,
  "name": "Докс",
  "orders_count": 2,
  "turnover": "0.0",
  "last_order_id": 4,
  "last_order_number": 1003,
  "type": "Client::Individual"
}

Создание

Для создания клиента достаточно передать телефон. Если имя пустое, оно сохраняется как «Имя не указано»; поля consent_to_personal_data и subscribe получают значение true, а type — Client::Individual.

Если телефон обязателен в настройках магазина, запрос с именем и почтой без телефона вернёт 422: «Не заполнено обязательное поле "Контактный телефон"».

Фамилию, имя и отчество можно передавать по отдельности: все три поля одновременно не обязательны. Из переданных значений формируется full_name в порядке «Фамилия Имя Отчество», а contact_name совпадает с именем. Эти поля возвращаются и при повторном чтении. Фамилию и отчество можно изменить через PUT.

Для создания юридического лица передайте type: juridical и обязательное поле contact_name («Ваше имя»). Поле name используется как название организации. Также сохраняются inn, kpp и juridical_address. В ответе type будет равен Client::Juridical.

Чтобы зарегистрировать клиента, передайте registered: true, почту, телефон и password длиной не менее 6 символов. Параметр skip_send_mail: true отключает отправку письма. Пароль в ответ не включается. Если в магазине работает бонусная система с начислением за регистрацию, новый клиент сразу получит баллы: например, при бонусе 50 поле bonus_points будет равно 50.

POST/admin/clients.json
Параметр Описание
client[name] необязательный
строка		 Имя. Пустое сохраняется как «Имя не указано».
client[surname] необязательный
строка		 Фамилия.
client[middlename] необязательный
строка		 Отчество.
client[phone] обязательный
строка		 Телефон, если поле в магазине обязательное.
client[email] необязательный
строка		 Почта.
client[comment] необязательный
строка		 Комментарий.
client[subscribe] необязательный
логический		 Подписка. Пустое значение становится true.
client[client_group_id] необязательный
число		 Группа клиента. 
POST /admin/clients.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "client": {
    "name": "Имя",
    "surname": "Фамилия",
    "middlename": "Отчество",
    "phone": "+79990001140",
    "email": "docs-api-fio2@example.com"
  }
}

Ответ · 201

{
  "id": 65,
  "name": "Имя",
  "surname": "Фамилия",
  "middlename": "Отчество",
  "full_name": "Фамилия Имя Отчество",
  "contact_name": "Имя",
  "phone": "+79990001140",
  "email": "docs-api-fio2@example.com",
  "type": "Client::Individual",
  "registered": false,
  "subscribe": true,
  "consent_to_personal_data": true,
  "bonus_points": 0
}
POST/admin/clients.json
Параметр Описание
client[type] обязательный
строка		 juridical для организации.
client[contact_name] обязательный
строка		 Контактное лицо. Без него ответ `422`.
client[name] необязательный
строка		 Название организации.
client[phone] обязательный
строка		 Телефон.
client[inn] необязательный
строка		 ИНН.
client[kpp] необязательный
строка		 КПП.
client[juridical_address] необязательный
строка		 Юридический адрес.
client[email] необязательный
строка		 Почта. 
POST /admin/clients.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "client": {
    "type": "juridical",
    "contact_name": "Петр",
    "name": "ООО Докс",
    "phone": "+79990001120",
    "inn": "7707083893",
    "kpp": "770701001",
    "juridical_address": "г Москва, ул. Документации, 1",
    "email": "docs-api-jur@example.com"
  }
}

Ответ · 201

{
  "id": 49,
  "type": "Client::Juridical",
  "name": "ООО Докс",
  "contact_name": "Петр",
  "inn": "7707083893",
  "kpp": "770701001",
  "juridical_address": "г Москва, ул. Документации, 1",
  "phone": "+79990001120",
  "email": "docs-api-jur@example.com"
}

Адрес по умолчанию передаётся в default_address_attributes на одном уровне с client. При чтении карточки адрес возвращается в default_address. Если телефон адреса пуст, InSales подставляет телефон клиента.

POST/admin/clients.json
Параметр Описание
client[name] обязательный
строка		 Имя.
client[phone] обязательный
строка		 Телефон.
default_address_attributes[full_locality_name] обязательный
строка		 Населённый пункт адреса.
default_address_attributes[address] необязательный
строка		 Улица и дом.
default_address_attributes[zip] необязательный
строка		 Индекс. 
POST /admin/clients.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "client": {
    "name": "Садресом",
    "phone": "+79990001122",
    "email": "docs-api-addr@example.com"
  },
  "default_address_attributes": {
    "full_locality_name": "г Москва",
    "address": "ул. Клиента, 5",
    "zip": "101000"
  }
}

Ответ · 201

{
  "id": 41,
  "name": "Садресом",
  "phone": "+79990001122",
  "default_address": {
    "full_locality_name": "г Москва",
    "address": "ул. Клиента, 5",
    "zip": "101000",
    "full_delivery_address": "101000, г Москва, ул. Клиента, 5",
    "phone": "+79990001122",
    "location_valid": true
  }
}

DELETE /admin/clients/:id.json убирает клиента из списка. Тело ответа — JSON-строка "ok". Повторное чтение отвечает 404.

Группы клиентов

GET /admin/client_groups.json возвращает массив. У группы есть id, title, discount, discount_description, is_default, b2b. Скидка в ответе — строка, например "15.0". У обычной группы b2b равен false.

Создание и чтение одной группы возвращают этот объект, создание — со статусом 201. PUT отвечает {"status":"ok"}, новое значение видно следующим GET. DELETE отвечает 200 с пустым телом, затем GET этой группы — 404.

Клиент связывается с группой полем client_group_id. В карточке тогда есть group_discount. Новый заказ этого клиента получает скидку группы.

POST/admin/client_groups.json
Параметр Описание
client_group[title] обязательный
строка		 Название группы.
client_group[discount] необязательный
число		 Скидка в процентах.
client_group[discount_description] необязательный
строка		 Текст скидки в заказе.
client_group[is_default] необязательный
логический		 Группа по умолчанию. 
POST /admin/client_groups.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "client_group": {
    "title": "docs-api опт",
    "discount": 10,
    "discount_description": "скидка группы 10%",
    "is_default": false
  }
}

Ответ · 201

{
  "id": 1,
  "title": "docs-api опт",
  "discount": "10.0",
  "discount_description": "скидка группы 10%",
  "is_default": false,
  "b2b": false
}

Теги клиентов

Тег создаётся POST /admin/client_tags.json с text и color. Ответ — {"success": true, "tag": {...}}, а не сам тег. PUT /admin/client_tags/:id.json отвечает {"success": true} и не возвращает тег. DELETE /admin/client_tags/:id.json отвечает тем же {"success": true}.

POST, PUT и DELETE требуют Content-Type: application/json, даже с пустым телом {}.

Без параметра client_id список возвращает теги, не привязанные ни к одному клиенту. После привязки тег больше не входит в этот список. Для чтения тегов клиента используйте GET /admin/client_tags.json?client_id=ID или поле client_tags его карточки. У каждого элемента есть поле attached.

Привязка — POST /admin/client_tags/:id/add.json?client_id=ID. Снятие — DELETE /admin/client_tags/:id/remove.json?client_id=ID. Закрепление одного тега — PUT /admin/client_tags/:id/attach.json?client_id=ID с телом {"attached": true}. В карточке клиента attached становится true.

GET /admin/client_tags/search.json?q=...&client_id=ID ищет тег через поиск магазина. Сразу после создания поиск по тексту тега ещё может быть пустым. Список по client_id тег уже возвращает.

POST/admin/client_tags.json
Параметр Описание
client_tag[text] обязательный
строка		 Текст тега.
client_tag[color] необязательный
строка		 Цвет, например #85C5E0. 
POST /admin/client_tags.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "client_tag": {
    "text": "docs-api vip",
    "color": "#85C5E0"
  }
}

Ответ · 200

{
  "success": true,
  "tag": {
    "id": 1,
    "text": "docs-api vip",
    "color": "#85C5E0"
  }
}
POST/admin/client_tags/1/add.json?client_id=25
Параметр Описание
id обязательный
число		 id тега в пути.
client_id обязательный
число		 Клиент, которому ставится тег. 
POST /admin/client_tags/1/add.json?client_id=25
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{}

Ответ · 200

{
  "success": true,
  "tag": {
    "id": 1,
    "text": "docs-api vip2",
    "color": "#7ABF24"
  }
}

Пользовательские статусы

GET /admin/custom_statuses.json возвращает пользовательские статусы магазина. Если пользовательские статусы включены, запрос также создаёт недостающие статусы по умолчанию для системных статусов.

permalink system_status title
novyy new Новый
v-obrabotke accepted В обработке
soglasovan approved Согласован
otgruzhen dispatched Отгружен
dostavlen delivered Доставлен
v-protsesse-vozvrata returning В процессе возврата
otmenen declined Отменен
vozvrat returned Возврат

Пока для системного статуса существует только одна запись, её is_default равен true. Объект также содержит id, position, color, created_at и updated_at.

Чтение, обновление и удаление идут по permalink, а не по id. GET /admin/custom_statuses/1.json отвечает 404 с HTML-телом. GET /admin/custom_statuses/novyy.json возвращает статус «Новый».

Для создания передайте title и один из восьми кодов system_status из таблицы. Значение permalink формируется из названия транслитерацией, цвет выбирается автоматически и возвращается в ответе.

При изменении PUT /admin/custom_statuses/:permalink.json возвращает {"status":"ok"}. Новое название отображается в заказе и при следующем чтении статуса. При удалении DELETE возвращает {"status":"ok"}, а повторное чтение — 404.

POST/admin/custom_statuses.json
Параметр Описание
custom_status[title] обязательный
строка		 Название. Из него строится permalink.
custom_status[system_status] обязательный
строка		 Один из системных кодов: new, accepted, approved, dispatched, delivered, returning, declined, returned. 
POST /admin/custom_statuses.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "custom_status": {
    "title": "docs-api сборка",
    "system_status": "approved"
  }
}

Ответ · 201

{
  "id": 65,
  "system_status": "approved",
  "permalink": "docs-api-sborka",
  "is_default": false,
  "title": "docs-api сборка",
  "color": "#86AA60"
}

Бонусные транзакции

Для работы с бонусными транзакциями в магазине должна действовать бонусная система.

GET /admin/bonus_system_transactions.json — общий список. GET /admin/clients/:client_id/bonus_system_transactions.json — транзакции клиента. Одна транзакция читается GET /admin/bonus_system_transactions/:id.json. Списки принимают page, updated_since и from_id.

Чтобы изменить баланс клиента, отправьте POST /admin/clients/:client_id/bonus_system_transactions.json. Поле bonus_points должно быть целым: положительное значение начисляет баллы, отрицательное списывает. Например, начисление 100 и списание 30 оставляют баланс 70. После сохранения status равен charged; у транзакции приложения initiator_type равен ApplicationPassword.

POST/admin/clients/33/bonus_system_transactions.json
Параметр Описание
client_id обязательный
число		 Клиент в пути.
bonus_system_transaction[bonus_points] обязательный
число		 Целые баллы. Отрицательное значение списывает.
bonus_system_transaction[description] необязательный
строка		 Комментарий транзакции. 
POST /admin/clients/33/bonus_system_transactions.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "bonus_system_transaction": {
    "bonus_points": 100,
    "description": "docs-api начисление"
  }
}

Ответ · 201

{
  "id": 1,
  "bonus_points": 100,
  "client_id": 33,
  "bonus_system_id": 1,
  "initiator_type": "ApplicationPassword",
  "description": "docs-api начисление",
  "status": "charged"
}

Промокоды

GET /admin/discount_codes.json возвращает промокоды по убыванию идентификаторов. Параметр q ищет подстроку в коде и описании: например, q=docs возвращает записи с этой подстрокой. Для чтения изменений поддерживаются updated_since и from_id.

Новый код по умолчанию выключен: disabled равен true, worked равен false, act_once равен true, type_id равен 2. Код приводится к нижнему регистру: DOCSAPI10 сохраняется как docsapi10. Повтор того же кода отвечает 422, тело {"code":["уже существует"]}.

type_id 1 — процент, 2 — сумма. Процент больше либо равный 100 не проходит проверку. min_price — минимальная сумма товаров. Код применяется, если сумма не ниже порога.

Чтобы промокод можно было применить к заказу, передайте disabled: false при создании или обновлении. Запрос PUT возвращает {"status":"ok"}; обновлённую карточку получите отдельным GET. Запрос DELETE также возвращает {"status":"ok"}.

collection_ids ограничивает код коллекциями. В ответе появляется discount_collections с collection_id. discount_collections_group_id связывает код с группой коллекций. В самом коде этого id нет: связь видна в GET /admin/discount_collections_groups/:id/discount_codes.json.

Поле worked равно false, если код выключен или одноразовый код уже использован. После применения к заказу кода с act_once: true его worked становится false. Создать второй заказ с тем же купоном нельзя.

POST/admin/discount_codes.json
Параметр Описание
discount_code[code] обязательный
строка		 Код. Сохраняется в нижнем регистре.
discount_code[discount] обязательный
число		 Размер скидки. Для процента меньше 100.
discount_code[type_id] необязательный
число		 1 — процент, 2 — сумма. По умолчанию 2.
discount_code[disabled] необязательный
логический		 true выключает код. По умолчанию код выключен.
discount_code[act_once] необязательный
логический		 true разрешает одно применение. По умолчанию true.
discount_code[min_price] необязательный
число		 Минимальная сумма товаров.
discount_code[description] необязательный
строка		 Описание, до 200 символов.
discount_code[collection_ids] необязательный
массив чисел		 Коллекции, на которые действует код.
discount_code[discount_collections_group_id] необязательный
число		 Группа коллекций. В карточке кода не возвращается. 
POST /admin/discount_codes.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "discount_code": {
    "code": "DOCSAPI10",
    "discount": 10,
    "type_id": 1,
    "disabled": false,
    "act_once": false,
    "min_price": 50,
    "description": "docs-api 10%"
  }
}

Ответ · 201

{
  "id": 1,
  "code": "docsapi10",
  "type_id": 1,
  "discount": "10.0",
  "description": "docs-api 10%",
  "disabled": false,
  "act_once": false,
  "min_price": "50.0",
  "worked": true,
  "discount_collections": []
}

Чтобы включить выключенный промокод, отправьте отдельный запрос на обновление. Ответ не содержит карточку: проверьте состояние кода запросом на чтение.

PUT/admin/discount_codes/1.json
Параметр Описание
discount_code[disabled] необязательный
логический		 false включает код.
discount_code[act_once] необязательный
логический		 false снимает одноразовость. 
PUT /admin/discount_codes/1.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "discount_code": {
    "disabled": false,
    "act_once": false
  }
}

Ответ · 200

{"status": "ok"}

Группы скидок на коллекции

GET /admin/discount_collections_groups.json и GET /admin/discount_collections_groups/:id.json возвращают группы, которые заведены в бэк-офисе. У группы есть id, title, collection_ids и collections с id, title, parent_id, permalink. Создать или изменить группу этим API нельзя: POST /admin/discount_collections_groups.json отвечает 404.

Коды, привязанные к группе, читаются отдельно.

GET/admin/discount_collections_groups/1.json
Параметр Описание
id обязательный
число		 id группы. 
GET /admin/discount_collections_groups/1.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

{
  "id": 1,
  "title": "docs-api каталог",
  "collection_ids": [53486010],
  "collections": [
    {
      "id": 53486010,
      "title": "Каталог",
      "parent_id": null,
      "permalink": "all"
    }
  ]
}
GET/admin/discount_collections_groups/1/discount_codes.json
Параметр Описание
id обязательный
число		 id группы. 
GET /admin/discount_collections_groups/1/discount_codes.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {
    "id": 1,
    "code": "docsapi10",
    "type_id": 1,
    "discount": "10.0",
    "worked": true
  }
]