Работа с заказами

Заказы — основной канал обмена с CRM, ERP и собственным сервисом: чтение, создание из проценки или каталога, смена статусов, meta (ID сделки), архив.

Базовый путь: /api/integrations/v1/orders
Авторизация: ключ и права · обозначения

Перед созданием обычно нужны:

• delivery_method / payment_method из GET /modules
• pickup_point_id из GET /pickup-points
• оффер из проценки или товар из каталога

Сценарий для CRM

1. GET /orders?since=… (или webhook модуля) — новые/изменённые заказы.
2. В CRM сохраните id заказа PlatParts.
3. POST /orders/{id}/meta — запишите свой ID сделки: { "meta": { "crm_deal_id": "…" } }.
4. При смене этапа в CRM — POST /orders/{id}/status с status_code магазина.
5. Документы: external-ref.

Права минимум: orders.read, orders.write_status, orders.write_meta.

Суммы и цены

В теле создания (items.*.price, price_purchase)	копейки (150000 = 1500 ₽)
В snapshot ответа (items[].price, total_price, total)	рубли

---

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

GET /orders — право orders.read

Query	Тип	Описание
pickup_point_id	int	Фильтр по точке (если у ключа точка — только она)
since	datetime	updated_at ≥ значения
status_code	string	Например order.created
per_page	int	1–100, по умолчанию 50
cursor	string	Курсор следующей страницы

Без права orders.read_archived архивные заказы в списке не показываются.

curl -sS "https://ВАШ_ДОМЕН/api/integrations/v1/orders?per_page=50&status_code=order.created" \
 -H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
 -H "Accept: application/json"

{
 "data": [
 {
 "id": 42,
 "user_id": 10,
 "pickup_point_id": 1,
 "status_id": 1,
 "status_code": "order.created",
 "status_semantic": "CREATED",
 "status_name": "Новый",
 "status_locked": false,
 "comment": "из внешней системы",
 "customer_name": "Иванов Иван",
 "total_price": 3000,
 "total": 3000,
 "items": [
 {
 "id": 1,
 "product_name": "Колодки",
 "quantity": 2,
 "price": 1500,
 "status_code": "item.created",
 "status_name": "Новая"
 }
 ],
 "archived_at": null,
 "created_at": "2026-07-15T14:22:00+03:00",
 "updated_at": "2026-07-15T14:22:00+03:00"
 }
 ],
 "per_page": 50,
 "next_cursor": null,
 "path": "https://ВАШ_ДОМЕН/api/integrations/v1/orders"
}

---

Карточка заказа

GET /orders/{id} — orders.read

HTTP	Когда
404	Нет заказа / чужая точка / скрыт из API по id
403	Ключ привязан к другой точке

Ответ — тот же snapshot, что элемент списка.

---

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

POST /orders — orders.write → 201

Тело запроса

Поле	Тип	Обяз.	Описание
user_id	int|null	нет	Существующий пользователь
pickup_point_id	int	да	Точка выдачи
delivery_method	int	да	id модуля доставки (GET /modules → delivery)
payment_method	int	да	id модуля оплаты (payment)
delivery_data	object	нет	JSON данных доставки
payment_data	object	нет	JSON данных оплаты
comment	string≤5000	нет	Комментарий
guest_surname / guest_name	string	нет	Гость
guest_phone	string	нет	Гость
items	array≥1	да	Позиции

Позиция items[]

Поле	Тип	Обяз.	Описание
type	string	нет	storage / catalog = из каталога; иначе поставщик (manufacturer)
product_id	int	для каталога	Id товара
storage_id	int	да	Склад / поставщик
quantity	int≥1	да	Количество
price	int≥0	нет	Цена продажи, копейки
price_purchase	int≥0	нет	Закупка, копейки (для поставщика)
brand / article / name	string	нет	Для позиции из проценки
payload	object	нет	Доп. данные
comment	string	нет	Комментарий позиции

curl -sS -X POST "https://ВАШ_ДОМЕН/api/integrations/v1/orders" \
 -H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
 -H "Content-Type: application/json" \
 -H "Accept: application/json" \
 -d '{
 "user_id": 10,
 "pickup_point_id": 1,
 "delivery_method": 2,
 "payment_method": 3,
 "comment": "из CRM",
 "items": [
 {
 "type": "manufacturer",
 "storage_id": 5,
 "quantity": 2,
 "price": 150000,
 "price_purchase": 100000,
 "brand": "BOSCH",
 "article": "0986AB1234",
 "name": "Колодки"
 }
 ]
 }'

{
 "ok": true,
 "order": {
 "id": 42,
 "user_id": 10,
 "pickup_point_id": 1,
 "status_code": "order.created",
 "status_name": "Новый",
 "total_price": 3000,
 "total": 3000,
 "items": [
 {
 "id": 1,
 "product_name": "Колодки",
 "quantity": 2,
 "price": 1500
 }
 ],
 "created_at": "2026-07-15T14:22:00+03:00"
 }
}

Позиция из каталога наличия:

{
 "type": "storage",
 "product_id": 100,
 "storage_id": 7,
 "quantity": 1,
 "price": 20000
}

HTTP	Когда
422	Не настроен статус CREATED; неверный/неактивный модуль оплаты/доставки; позиция недоступна
403	pickup_point_id не совпадает с точкой ключа

---

Изменить поля

PATCH /orders/{id} — orders.write

Тело (все поля необязательны): comment, delivery_data, payment_data.

Статус этим методом не меняется — см. ниже.

200: { "ok": true, "order": { ... } }

---

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

Сначала получите доступные статусы: Статусы (GET /statuses/orders).
POST /orders/{id}/status — orders.write_status

Тело: либо status_id, либо status_code (один обязателен). Произвольное название не принимается.

curl -sS -X POST "https://ВАШ_ДОМЕН/api/integrations/v1/orders/42/status" \
 -H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
 -H "Content-Type: application/json" \
 -d '{"status_id":5}'

{
 "ok": true,
 "unchanged": false,
 "order_id": 42,
 "status_id": 5,
 "status_code": "order.in_progress",
 "status_semantic": "IN_PROGRESS",
 "order": {
 "id": 42,
 "status_code": "order.in_progress",
 "previous_status_code": "order.created",
 "previous_status_name": "Новый"
 }
}

404 — неизвестный статус.

---

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

Позиции можно читать, создавать, менять, удалять и менять статус. Сначала смотрите состав в GET /orders/{id} или карточку позиции — чтобы править существующую строку, а не плодить дубли.

Метод	URL	Право
GET	/orders/{orderId}/items/{itemId}	orders.read
POST	/orders/{orderId}/items	order_items.write
PATCH	/orders/{orderId}/items/{itemId}	order_items.write
DELETE	/orders/{orderId}/items/{itemId}	order_items.delete
POST	/orders/{orderId}/items/{itemId}/status	orders.write_status
POST	/orders/{orderId}/items/{itemId}/archive	order_items.archive
POST	/orders/{orderId}/items/{itemId}/unarchive	order_items.unarchive

Добавить позицию

POST /orders/{orderId}/items — те же поля, что элемент items[] при создании заказа: storage_id и quantity обязательны; для каталога — type: storage + product_id. Цены в копейках.

curl -sS -X POST "https://ВАШ_ДОМЕН/api/integrations/v1/orders/42/items" \
 -H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
 -H "Content-Type: application/json" \
 -d '{"type":"storage","product_id":100,"storage_id":7,"quantity":1,"price":20000}'

201: { "ok": true, "item": { ... } }

Изменить позицию

PATCH /orders/{orderId}/items/{itemId} — опционально: quantity, price, price_purchase, comment, payload (merge). Статус этим методом не меняется.

Удалить позицию

DELETE /orders/{orderId}/items/{itemId} — жёсткое удаление строки (не архив). Архивные позиции сначала разархивируйте.

Статус позиции

Справочник: GET /statuses/order-items.
Тело: { "status_id": ... } или { "status_code": "..." }.

---

Meta, архив, удаление

Метод	URL	Право	Тело
POST	/orders/{id}/meta	orders.write_meta	{ "meta": { "crm_id": "CRM-9912" } }
POST	/orders/{id}/archive	orders.archive	—
POST	/orders/{id}/unarchive	orders.unarchive	—
DELETE	/orders/{id}	orders.delete	—

Meta мержится в namespace ключа (или заголовок X-Integration-Namespace).

curl -sS -X POST "https://ВАШ_ДОМЕН/api/integrations/v1/orders/42/meta" \
 -H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
 -H "Content-Type: application/json" \
 -d '{"meta":{"crm_id":"CRM-9912"}}'

Ответ удаления: { "ok": true, "deleted": true, "order_id": 42 }.

---

Дальше

• Получить предложение поставщика.
• Получить способы оплаты, доставки и точки выдачи.
• Создать платёж или связать документ · Документы.