Методы API. Заказы и клиенты

Отправляйте запросы на адрес https://домен-магазина/api/v2/… с API-токеном в заголовке X-Service-Token, без слова Bearer. API-токен — секретный ключ, по которому магазин узнаёт связку и проверяет её права. Токен выпускают в разделе «Подключения» на вкладке «Альбато» и отмечают флажками нужные права — подробнее в статье «API-токены». У каждого метода ниже указано, какой флажок нужен.

Тело запроса передаётся в формате JSON (текст из пар «поле — значение») с заголовком Content-Type: application/json. Магазин определяется по токену, storeId передавать не нужно. Время в адресе запроса передавайте в UTC, например 2026-09-16T10:00:00Z, или кодируйте знак + как %2B: иначе он прочитается как пробел.

Списки приходят в виде {"count": …, "rows": […]}. У списков заказов и клиентов ограничения по умолчанию нет: всегда передавайте limit и перебирайте страницы через offset.

Сам API о новых заказах и оплатах не сообщает — для этого магазин отправляет вебхуки. Вебхук — автоматический запрос, который магазин отправляет на адрес из настроек, когда происходит событие. Поля событий описаны в статье «События вебхуков».

Методы этой статьи передают персональные данные клиентов: имена, телефоны, адреса и переписку. Обязанности оператора персональных данных лежат на владельце магазина — что учесть, описано в статье «Персональные данные», документы проверьте с юристом.

Связка — сценарий в Альбато. Товары и остатки описаны во второй части справочника «Методы API. Товары и остатки», исполнители и записи на услуги — в третьей, «Методы API. Исполнители и записи».

• 200, 201 — запрос выполнен. 201 — объект создан.
• 400 — ошибка в параметрах или теле запроса. Причина — в поле message.
• 401 — токен не передан, неверный, отозван или истёк: invalid or revoked service token.
• 403 — запрос понят, но выполнить его нельзя. Причину показывает текст ответа, варианты разобраны в разделе «Короткие ответы».
• 404 — команда неприменима к объекту в текущем состоянии, например заказ уже отменён. Некоторые методы возвращают здесь не JSON, а текст Not Found.
• 409 — конфликт: такой externalId или адрес почты уже есть, товара не хватает на складе, интервал доставки занят.
• 429 — слишком много запросов: больше 300 в минуту с одного сетевого адреса. Тело ответа — текст, а не JSON. Сделайте паузу и повторите.
• 500, 502, 503 — сбой на стороне магазина или платёжного сервиса. Повторите запрос позже.

💡 Обычно ошибка приходит в виде {"message": "…"}, но у отдельных методов тело другое: поле error или простой текст. В условиях связки сначала проверяйте код ответа, а текст используйте для диагностики.

Статус хранится числом в поле status. Для каждого перехода есть своя команда, они описаны в разделе «Сменить статус заказа»:

• 0 — «Новый». Присваивается при создании, вернуть заказ в этот статус можно командой status.
• 1 — «Подтверждён», команда confirm.
• 2 — «В обработке», команда status.
• 4 — «Доставляется», команда status.
• 3 — «Выполнен», команда done.
• -1 — «Отменён», команда cancel. Отменённый заказ вернуть в работу нельзя.

Поле source показывает, откуда пришёл заказ: web — сайт, max — бот MAX, manual — панель или API, yandex_market — Яндекс Маркет. Заказы Маркета меняются только через Маркет: команды API вернут ошибку 409.

Получить заказ

GET /api/v2/order?id=123

Права: «Заказы и записи на услуги» → «Чтение».

Ответ — объект заказа. Если связке нужен ответ в виде списка, добавьте &format=list: придёт {"count": 1, "rows": [заказ]}.

{
  "id": 123,
  "status": 1,
  "source": "web",
  "clientId": 45,
  "fullValue": 1450,
  "discount": 50,
  "deliveryValue": 300,
  "currency": "RUB",
  "isPayment": false,
  "isWaitClientPayment": true,
  "paymentId": 3,
  "contactName": "Иван Петров",
  "contactPhone": "+79990000001",
  "email": "ivan@example.com",
  "comment": "Позвонить заранее",
  "deliveryType": "courier",
  "address": "г. Москва, ул. Ленина, д. 1",
  "externalId": null,
  "createdAt": "2026-09-16T10:00:00.123456Z",
  "client": {"id": 45, "caption": "Иван Петров", "phone": "+79990000001"},
  "payment": {"caption": "Картой онлайн"},
  "delivery": {"caption": "Курьер", "kind": "courier", "provider": null},
  "orderCompositions": [
    {
      "id": 301,
      "goodId": 10,
      "count": 2,
      "price": 500,
      "optionsSnapshot": [{"groupCaption": "Размер", "valueCaption": "M"}],
      "good": {"caption": "Футболка", "article": "SHIRT-M"}
    }
  ]
}

В ответе больше полей, чем в примере. Для связок обычно нужны эти:

• fullValue — итог к оплате: товары, доставка, включённая в заказ, и наценка способа оплаты минус скидки.
• discount, promoValue — ручная скидка; скидка по промокоду вместе с реферальной скидкой и оплатой бонусами.
• deliveryValue, paymentValue — стоимость доставки, включённая в заказ; наценка способа оплаты.
• isPayment — true, если заказ оплачен.
• isWaitClientPayment — true, если клиенту выставлена ссылка на оплату и магазин ждёт платёж.
• isWaitClientCancel — true, если клиент попросил отменить заказ.
• paymentId, paymentMethod — ID способа оплаты магазина; онлайн-провайдер: yookassa, yandexpay или null.
• contactName, contactPhone, email, comment — контакты и комментарий из заказа. Могут отличаться от профиля клиента.
• deliveryType, deliveryTypeId — код и ID способа доставки.
• address, addressEntrance, addressFloor, addressApt, addressComment — адрес доставки: адрес, подъезд, этаж, квартира, комментарий.
• deliveryDate, deliverySlotFrom, deliverySlotTo — дата и интервал доставки: 2026-09-20, 10:00:00, 12:00:00.
• externalId, externalSource — ID заказа во внешней системе и название этой системы.
• client — профиль клиента: id, caption, firstName, lastName, phone, email и другие.
• orderCompositions — позиции: id позиции, goodId, count, price за единицу, выбранные опции optionsSnapshot, название и артикул в good.

Список заказов

GET /api/v2/order?limit=50

Права: «Заказы и записи на услуги» → «Чтение».

Заказы идут от новых к старым, count — число заказов по фильтрам без учёта страниц. Без limit придут все заказы магазина одним ответом. Фильтры можно сочетать:

• status — коды статусов через запятую, например 0,1,2.
• paymentStatus — состояние оплаты: paid — оплачен, waiting — ждёт оплаты по ссылке, unpaid — не оплачен. Можно через запятую.
• dateFrom, dateTo — дата создания заказа. Если dateTo указан без времени, день входит в выборку целиком.
• source — источники через запятую: web, max, manual, yandex_market.
• externalId, externalSource — точное совпадение ID и названия внешней системы.
• search — номер заказа или часть имени, телефона, имени пользователя из профиля клиента. Контакты, введённые в самом заказе, не ищутся.
• totalFrom, totalTo — диапазон итоговой суммы.
• waitingCancel — true, чтобы получить только заказы, по которым клиент запросил отмену.
• deliveryTypeId — ID одного способа доставки.
• limit, offset — размер страницы и сдвиг от начала.

Заказы, созданные записями на услуги, в список не попадают: их получают методами записей из статьи «Методы API. Исполнители и записи». По id такой заказ доступен. Фильтров по клиенту и дате изменения нет — об изменениях сообщают вебхуки.

Справочники для фильтров

GET /api/v2/orderFilters

Права: «Заказы и записи на услуги» → «Чтение».

Возвращает способы доставки deliveryTypes (id, caption, kind, provider), зоны курьерской доставки courierZones, список источников sources и статусы с названиями statuses. В списки попадают и выключенные способы доставки, и удалённые зоны — учитывайте это, если подставляете ID в новый заказ.

Заказ в виде формы редактирования

GET /api/v2/newOrder?id=123

Права: «Заказы и записи на услуги» → «Чтение».

Отдаёт заказ так, как его показывает форма редактирования заказа в панели. Набор полей близок к ответу метода «Получить заказ», но есть отличия:

• fullValue — не итог к оплате, а сумма позиций (количество × цена) без скидок, доставки и наценки способа оплаты;
• в позициях orderCompositions нет выбранных опций optionsSnapshot;
• есть сводка скидок discounts: скидка по промокоду promo, реферальная скидка referral с кодом и именем пригласившего, списанные бонусы bonus, ручная скидка manual и их сумма totalDiscount;
• для способа доставки с отдельной оплатой есть блок orderDelivery.

⚠️ Для связок используйте «Получить заказ» (GET /api/v2/order): по этому методу итог к оплате считать нельзя. Кроме того, метод не только читает данные, хотя токену хватает права на чтение. Если доставка в заказе оплачивается отдельно, метод может создать для заказа запись о доставке (блок orderDelivery), а если по ней ожидается платёж через ЮKassa — запросить его статус и отметить доставку оплаченной.

Ошибки:

• 400 id is required — не передан id;
• 400 invalid resource id — id не число или отрицательный;
• 403 resource does not belong to service token store — заказа нет, он удалён или принадлежит другому магазину;
• 404 — при id=0, ответ приходит текстом Not Found, а не JSON.

Создать заказ

POST /api/v2/newOrder

Права: «Заказы и записи на услуги» → «Создание заказов, отправка клиенту и действия с записями».

• clientId — ID клиента магазина. Обязательное поле.
• items — позиции: goodId — ID товара или варианта, count — количество, price — цена за единицу. Цена берётся из запроса, а не из каталога. Обязательное поле.
• contactName, contactPhone, email — контакты для заказа.
• comment — комментарий, до 2000 символов.
• paymentId — ID способа оплаты. Для онлайн-оплаты магазин сразу создаст ссылку на оплату.
• deliveryTypeId, deliveryType — ID и код способа доставки. Передавайте оба: без кода не сработают правила, завязанные на тип доставки, например автоотправка цифровых товаров.
• deliveryValue — стоимость доставки.
• address, addressEntrance, addressFloor, addressApt, addressComment — адрес доставки.
• pickupPointId — ID точки самовывоза.
• courierZoneId, deliveryDate, deliverySlotFrom, deliverySlotTo — зона курьера, дата и интервал доставки: 2026-09-20, 10:00, 12:00. Интервал бронируется сразу.
• discount, promoId — ручная скидка в рублях; ID промокода.
• externalId, externalSource — ID заказа во внешней системе и её название. Повторный заказ с той же парой получит ошибку 409.

POST https://myshop.ru/api/v2/newOrder
X-Service-Token: ваш_токен
Content-Type: application/json

{
  "clientId": 45,
  "contactName": "Иван Петров",
  "contactPhone": "+79990000001",
  "items": [
    {"goodId": 10, "count": 2, "price": 500},
    {"goodId": 11, "count": 1, "price": 250}
  ],
  "deliveryTypeId": 5,
  "deliveryType": "courier",
  "deliveryValue": 300,
  "address": "г. Москва, ул. Ленина, д. 1",
  "externalId": "CRM-5521",
  "externalSource": "amocrm"
}

Ответ — код 201: {"id": 124, "fullValue": 1550, "status": 0, "message": "Заказ создан"}. Заказ получает статус «Новый», валюту RUB и источник manual.

• Остатки резервируются сразу. Если товара не хватает, заказ не создаётся, ответ — 409 insufficient stock. Для товаров с учётом остатка количество должно быть целым. Движения резерва видны в истории остатка — см. статью «Методы API. Товары и остатки».
• Если интервал доставки уже занят, придёт 409 «Интервал доставки уже занят, выберите другой», и заказ тоже не создастся.
• Ошибки проверки оплаты приходят в поле error, например {"error": "для создания платежа необходимо указать email или телефон клиента"}.
• Защиты от повторного создания, кроме пары externalId и externalSource, нет. Если связка может повторить шаг, передавайте эту пару: повтор получит 409, и дубля не будет.
• ID способов оплаты, точек самовывоза и промокодов через API не получить. Возьмите их из уже оформленного заказа с нужными настройками: поля paymentId, pickupPointId и promo.

После создания отправляются события «Новый заказ» и «Изменение остатков» по каждой позиции с учётом остатка, а сотрудники получают уведомление о новом заказе.

Изменить заказ

PUT /api/v2/newOrder?id=123

Права: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка».

Передавайте только поля, которые нужно изменить: comment, contactName, contactPhone, email, поля адреса вместе с addressMode, lat и lng, deliveryTypeId, deliveryType, pickupPointId, courierZoneId, deliveryDate, deliverySlotFrom, deliverySlotTo, discount, promoId, clientId и items. Поле, которого метод не знает, например status, paymentId или externalId, вернёт ошибку 400 unknown field.

Состав заказа меняется через items:

• поля нет — позиции не меняются;
• позиция с id — у неё меняются count и price;
• позиция без id — добавляется, нужен goodId;
• позиции заказа, которых нет в списке, удаляются. Пустой массив удалит все позиции.

PUT https://myshop.ru/api/v2/newOrder?id=123
X-Service-Token: ваш_токен
Content-Type: application/json

{
  "comment": "Перезвонить после 18:00",
  "items": [
    {"id": 301, "goodId": 10, "count": 3, "price": 500},
    {"goodId": 12, "count": 1, "price": 990}
  ]
}

Ответ — обновлённый заказ без вложенных объектов. Итог пересчитывается, а неоплаченная ссылка на оплату сбрасывается. Выполненный и отменённый заказы менять нельзя (400), скидку и промокод оплаченного заказа — тоже (409). Смена интервала доставки этим методом интервал не бронирует.

Событий о заказе метод не отправляет. При изменении состава уходят события «Изменение остатков».

Позиции заказа

Отдельные позиции удобно менять тремя методами. ID позиции — поле id в orderCompositions.

• POST /api/v2/orderComposition — добавить позицию, право «Создание заказов, отправка клиенту и действия с записями». Тело: {"orderId": 123, "goodId": 12, "count": 1, "price": 990}. Всегда передавайте count и price. Ответ — 201 и созданная позиция.
• PUT /api/v2/orderComposition?id=305 — изменить позицию, право «Редактирование, статусы, оплата и доставка». Тело: {"count": 2, "price": 950}. Ответ — позиция с новыми значениями.
• DELETE /api/v2/orderComposition?id=305 — удалить позицию, право «Удаление». Ответ — код 200 и текст OK.

Резерв остатка пересчитывается сразу, а итог заказа — в фоне, за несколько секунд. Если следующий шаг связки читает сумму заказа, добавьте перед ним паузу. Позиции выполненного и отменённого заказа менять нельзя.

Сменить статус заказа

Все команды передают ID заказа в адресе, тело нужно только команде status. Ответ — {"success": true}. Права: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка».

PUT /api/v2/order/confirm?id=123
PUT /api/v2/order/status?id=123
PUT /api/v2/order/done?id=123
PUT /api/v2/order/cancel?id=123
PUT /api/v2/order/rejectCancel?id=123

• confirm — подтверждает заказ, статус 1.
• status — ставит статус из тела запроса: {"status": 2}. Допустимы только 0, 2 и 4, для остальных статусов есть свои команды.
• done — выполняет заказ, статус 3. Резерв списывается окончательно, остаток не меняется. Для отменённого или уже выполненного заказа ответ — 404.
• cancel — отменяет заказ, статус -1. Резерв возвращается на склад, ожидающие ссылки на оплату, интервал доставки и записи на услуги по заказу отменяются. Повторная отмена — 404.
• rejectCancel — отклоняет запрос клиента на отмену. Статус не меняется, клиенту сообщение не отправляется. Если запроса нет — 404.

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

После команд уходят события: «Изменение статуса заказа» для confirm, status и done, «Отмена заказа» и «Изменение остатков» для cancel.

⚠️ Важно: отмена оплаченного заказа не возвращает деньги клиенту — возврат оформляется в платёжной системе. Не переводите выполненный заказ обратно в другой статус: после этого состав заказа перестанет редактироваться.

Отметка об оплате

PUT /api/v2/order/changePayment?id=123

Права: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка».

Метод переключает отметку об оплате на противоположную: неоплаченный заказ становится оплаченным, оплаченный — неоплаченным. Тело не нужно. Ответ показывает новое значение: {"success": true, "isPayment": true}.

⚠️ Важно: перед вызовом прочитайте заказ и проверьте, что isPayment равен false. Если Альбато повторит шаг, второй вызов снимет оплату.

Когда заказ становится оплаченным, отправляется событие «Оплата заказа», а цифровые товары уходят автоматически, если это настроено. Статус заказа не меняется. Снятие отметки события не создаёт.

Список клиентов и поиск

GET /api/v2/clients/list?limit=50

Права: «Клиенты и сообщения» → «Чтение».

• search — часть имени, телефона, адреса почты или имени пользователя в мессенджере.
• externalId, externalSource — точное совпадение ID клиента во внешней системе и её названия.
• limit, offset — размер страницы и сдвиг от начала.

Клиенты идут от новых к старым. Телефон ищется как часть строки в том виде, в каком его сохранили, поэтому надёжнее искать по последним десяти цифрам: search=9991234567.

Поля клиента, которые обычно нужны связкам:

• id, caption — ID и отображаемое имя;
• firstName, lastName, middleName, phone, email;
• source — как появился клиент: manual — панель или API, web — посетитель сайта, registration — регистрация на сайте, max — мессенджер MAX;
• externalId, externalSource — ID во внешней системе;
• maxId — заполнен, если клиент писал боту в MAX;
• createdAt, updatedAt.

Карточка клиента

GET /api/v2/clients/info?id=1542

Права: «Клиенты и сообщения» → «Чтение».

Возвращает профиль клиента, число его заказов orderCount и до 20 последних сообщений переписки в recentMessages, новые первыми. В сообщениях from: true означает сообщение магазина, from: false — сообщение клиента. Полей source, externalId и externalSource в карточке нет, их отдаёт список клиентов.

Создать клиента

POST /api/v2/clients/create

Права: «Клиенты и сообщения» → «Создание и изменение клиентов, бонусы и сообщения».

• caption — отображаемое имя, до 200 символов. Если не передать, соберётся из имени и фамилии или возьмётся адрес почты.
• firstName, lastName, middleName — имя, фамилия, отчество, до 100 символов каждое.
• phone — телефон, до 20 символов. Формат не проверяется, храните его единообразно, например +79991234567.
• email — адрес электронной почты. Должен быть уникальным.
• login, password — логин и пароль (от 6 символов) для входа на сайт. Без логина логином станет адрес почты.
• externalId, externalSource — ID клиента во внешней системе (строкой) и название системы.

POST https://myshop.ru/api/v2/clients/create
X-Service-Token: ваш_токен
Content-Type: application/json

{
  "firstName": "Иван",
  "lastName": "Петров",
  "phone": "+79991234567",
  "email": "ivan@example.com",
  "externalId": "CRM-778",
  "externalSource": "amocrm"
}

Ответ — код 201 и созданный клиент с source: "manual". После создания отправляется событие «Новый клиент».

• Занятый адрес почты или логин вернут 409 email already exists, повтор пары externalId и externalSource — 409 externalId already exists.
• Дубли по телефону не проверяются. Перед созданием ищите клиента по телефону или externalId.
• Клиента, созданного через API, нельзя связать с MAX. Если он потом напишет боту магазина, появится отдельная карточка.

Изменить клиента

POST /api/v2/clients/updateInfo

Права: «Клиенты и сообщения» → «Создание и изменение клиентов, бонусы и сообщения».

ID клиента передаётся в теле, в поле clientId. Изменить можно caption, firstName, lastName, middleName, phone, email, description, login, password, lang и block (true — не включать клиента в рассылки).

POST https://myshop.ru/api/v2/clients/updateInfo
X-Service-Token: ваш_токен
Content-Type: application/json

{"clientId": 1542, "phone": "+79990000010"}

Ответ — клиент с новыми значениями, после него уходит событие «Изменение клиента». Оно отправляется после каждого успешного вызова, даже если значения не изменились.

⚠️ Важно: каждое переданное поле перезаписывается, в том числе пустым значением. "email": "" удалит адрес почты клиента. Не передавайте поля, которые менять не нужно. externalId, externalSource и привязку к мессенджерам этим методом изменить нельзя.

Следующие действия с заказами выполняются только в панели, API ответит 403 service token is not allowed on this route:

• смена способа оплаты у существующего заказа;
• расчёт стоимости доставки, выставление и отмена счёта за доставку;
• отправка созданного заказа клиенту и ручная выдача цифровых товаров;
• журнал действий по заказу.

Ограничение по клиентам (привязка к MAX) описано в разделе «Клиенты».

Почему API отвечает 403 на заказ, который точно существует?

Чаще всего токену не хватает права: тогда в ответе rbac_forbidden, а в поле requiredCapability указано, какого именно. resource does not belong to service token store значит, что заказ удалён или принадлежит другому магазину. Для несуществующих ID API тоже отвечает 403, а не 404.

Как не создать заказ дважды, если Альбато повторил шаг?

Передавайте в заказе externalId и externalSource, например номер сделки и amocrm. Повторный запрос с той же парой получит ошибку 409, и второй заказ не появится. Перед созданием можно проверить заказ запросом списка заказов с параметрами externalSource и externalId.

Как отметить заказ оплаченным из платёжной системы?

Сначала получите заказ через GET /api/v2/order?id=… и убедитесь, что isPayment равен false. Только после этого вызывайте команду changePayment: она переключает отметку, и повторный вызов снимет оплату.

Сколько запросов в минуту принимает API магазина?

До 300 запросов в минуту с одного сетевого адреса. При превышении API отвечает кодом 429 с текстом вместо JSON: сделайте паузу и повторите запрос.