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

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

Это API приложения, а не сессия покупателя на витрине. Список заказов клиента после входа на сайт через session.json отсюда не берётся: заказы клиента читаются параметром client_id у GET /admin/orders.json.

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

Заказы

id — идентификатор заказа в URL. number — номер, который магазин показывает покупателю. Номер задаётся отдельно от id: у заказа могут быть 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 срезается до 100. per_page=1 возвращает одну запись. per_page=0 возвращает пустой массив.

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

GET /admin/orders/count.json считает тот же отбор и отдаёт {"count": N}.

GET/admin/orders.json?per_page=1
Параметр Описание
per_page необязательный
число		 Размер страницы. Больше 100 срезается до 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 список не ограничивает. Номер читается границами number_from и number_to. Один номер — обе границы равны ему.

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

client_id оставляет заказы клиента. ids[] повторяется для нескольких id. 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[].

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

При заданном updated_since порядок меняется на updated_at, затем id. per_page=1 в таком списке возвращает самый старый подходящий заказ. Следующий запрос с его updated_at и from_id, равным его 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.

Архив

Обычный список и GET /admin/orders/:id.json архивный заказ не отдают: для удалённого id ответ 404 с HTML-телом. deleted=true оставляет только архив. with_deleted=true отдаёт текущие и архивные, у архивного archived равен true. Те же флаги работают у карточки и у count.

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}

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

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

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

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

delivery_variant_id и payment_gateway_id выбирают доставку и оплату. Цена доставки при создании берётся у способа. Тариф внешней доставки и точка самовывоза передаются объектом delivery_info_attributes: в нём tariff_id, price, title и outlet. Для DeliveryVariant::PickUp в outlet нужны latitude и longitude, иначе ответ 422 с текстом «Не выбрана точка самовывоза». Поля доставки — в доставке. Поля оплаты — в способах оплаты. Письма магазину и клиенту отключают not_send_email_to_client и not_send_email_to_account.

Клиента можно передать объектом client или готовым client_id. Вложенный client сохраняет имя, почту, телефон и согласие. Фамилию и отчество записывает отдельное создание клиента, после него в заказ уходит 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": "Video QA B 20261021 (Красный)"
    }
  ],
  "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 комплекта. В сохранённом заказе строки комплекта нет. На её месте стоят составляющие, у каждой bundle_id равен id товара-комплекта. Количество составляющей — количество в комплекте, умноженное на количество комплектов. Цены составляющих в сумме дают цену комплекта.

Рядом может лежать тот же вариант отдельной строкой. У неё bundle_id пустой, а variant_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": "Video QA B 20261021 (Красный)",
      "product_id": 625,
      "variant_id": 2176487172,
      "bundle_id": 689,
      "quantity": 1,
      "sale_price": 88.24,
      "full_total_price": 88.24
    },
    {
      "id": 11,
      "title": "Gallery QA Host 20261021",
      "product_id": 617,
      "variant_id": 2176487171,
      "bundle_id": 689,
      "quantity": 2,
      "sale_price": 0.88,
      "full_total_price": 1.76
    },
    {
      "id": 12,
      "title": "Video QA B 20261021 (Красный)",
      "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 меняет заказ. Существующая строка находится по 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. Вместе с ним записывается системный статус этой записи. Системный код (new, accepted, approved и остальные из списка выше) в этом поле записывается как fulfillment_status.

Одновременно переданные несовместимые исполнение и permalink отвечают 422:

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

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

version — целое время updated_at. Если у заказа время больше переданного version, ответ 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 дублирует первую. Код на 10% снизил строку за 100 до итога 90. Код на 50 рублей снизил ту же строку до 50. Повтор кода с act_once: true ответил 422: «Указан несуществующий купон, убедитесь, что он введен верно».

Клиент из группы со скидкой 15% получил заказ с итогом 85 при цене строки 100. Скидка лежит в 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, итог 80 и остаток 30. Скидка в 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 отдаёт поля заказа, клиента, адреса и контактов одним массивом. Удалённые в него не входят. Короткий список активных полей по группам — GET /admin/orders/fields.json: ключи order_fields, client_fields, juridical_client_fields, shipping_address_fields. У элемента этой группировки есть id, office_title, title, type, obligatory, system_name.

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 в теле обновления игнорируются: список остаётся списком и на том же 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": "Текст"
    }
  ]
}

Доставка и оплата без сохранения

POST /admin/orders/delivery_variants.json считает доступные способы по составу и адресу и заказ не сохраняет. У способа есть id, title, price, customer_pickup. В delivery_info есть tariff_id. У самовывоза и фиксированного курьера он равен null.

POST /admin/orders/payment_gateways.json считает оплату для уже выбранного delivery_variant_id. Без него ответ 422, в order текст delivery_variant_id not present.

PUT /admin/orders/build.json собирает заказ в ответе и не сохраняет его: id равен null. У строки есть variant_quantity — остаток варианта. POST на этот путь не принят, метод именно PUT.

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

{
  "order": {
    "order_lines_attributes": [
      {"variant_id": 2176487172, "quantity": 1}
    ],
    "shipping_address": {
      "full_locality_name": "г Москва",
      "address": "ул. Клиента, 5"
    }
  }
}

Ответ · 200

[
  {
    "id": 9,
    "title": "Самовывоз",
    "price": 0,
    "customer_pickup": true,
    "delivery_info": {"delivery_variant_id": 9, "tariff_id": null, "price": 0.0}
  }
]

Удаление

DELETE /admin/orders/:id.json переносит заказ в архив. Тело — {"status":"ok"}. Дальше заказ виден с deleted=true или with_deleted=true.

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

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

GET /admin/user_tasks.json отдаёт массив. В ответе нет общего числа записей. Поля: id, complete, order_id, assignee_id, title, description, created_at, updated_at, deadline_at, order. У задачи с заказом order — объект {id, number}. У задачи без заказа в списке order равен null. Автора в JSON нет.

assignee_id — id из GET /admin/users.json. У запроса приложения assignee=me выбирает задачи с пустым assignee_id.

Создание отвечает 200. Если deadline_at не передан, он становится временем создания плюс один час. Если complete не передан, в JSON стоит null. Явное false сохраняется как false. Фильтр complete=false такие null не возвращает. Строки true и false фильтруют. complete=1 фильтр не включает. Если в запросе есть и completed, и complete, действует completed.

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 поднимаются до 25, выше 1000 опускаются до 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, при этом orders_count их считает. last_order_id и last_order_number берутся по дате создания.

Список и число

GET /admin/clients.json отдаёт массив. Размер страницы меньше 10 поднимается до 10, больше 500 срезается до 500. В ответе есть заголовок X-TOTAL-PAGES. GET /admin/clients/count.json отдаёт {"count": N} по тому же отбору.

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 становится true, subscribe становится true, type — Client::Individual. Имя и почта без телефона отвечают 422: «Не заполнено обязательное поле "Контактный телефон"», если телефон в магазине обязателен.

Фамилия, имя и отчество все три сразу не требуются. Переданные сохраняются, full_name равен «Фамилия Имя Отчество», contact_name совпадает с именем. Повторный GET отдаёт те же поля. 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"
}

Адрес по умолчанию передаётся рядом с client, ключом default_address_attributes, а не внутри клиента. В карточке он лежит в default_address. Телефон адреса пустым не остаётся: он дополняется телефоном клиента.

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 строится из названия транслитом. system_status — один из восьми кодов таблицы. Цвет выбирается сам, в ответ он входит. 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"
}

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

Транзакции пишутся в работающую бонусную систему. Система создаётся так:

POST/admin/bonus_systems.json
Параметр Описание
bonus_system[type] обязательный
строка		 BonusSystem::Internal — бонусы магазина.
bonus_system[bonus_percent] обязательный
число		 Процент начисления.
bonus_system[max_discount] обязательный
число		 Максимальная доля заказа, которую можно оплатить баллами, до 100.
bonus_system[ratio] обязательный
число		 Курс балла. При значении `1` списание 20 баллов даёт скидку 20.
bonus_system[worked] необязательный
логический		 true делает систему текущей.
bonus_system[registration_bonus] необязательный
число		 Баллы новому зарегистрированному клиенту. В ответе создания поля нет, баллы видны у клиента. 
POST /admin/bonus_systems.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "bonus_system": {
    "type": "BonusSystem::Internal",
    "bonus_percent": 5,
    "max_discount": 30,
    "ratio": 1,
    "worked": true,
    "registration_bonus": 50
  }
}

Ответ · 200

{
  "id": 1,
  "type": "BonusSystem::Internal",
  "type_name": "InSales",
  "worked": true,
  "title": "InSales",
  "bonus_percent": 5,
  "max_discount": 30,
  "ratio": "1.0"
}

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

Начисление — POST на клиента или на заказ. bonus_points целое: положительное увеличивает баланс, отрицательное уменьшает. 100 и затем −30 оставили на карточке 70 баллов. status после сохранения равен charged. У начисления с клиента initiator_type равен ApplicationPassword. У начисления через заказ initiator_type равен Order, а client_id берётся из заказа: десять баллов заказу 3 увеличили баланс его клиента.

DELETE /admin/clients/:client_id/bonus_system_transactions/:id.json транзакцию не удаляет.

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 отдаёт коды, новые id впереди. 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 — минимальная сумма товаров. Код применяется, если сумма не ниже порога.

Чтобы код работал в заказе, в создании или в PUT нужно 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
  }
]