PASSAGE API
Один сервер на магазин: касса в зале, приложения покупателя, владельца и курьера ходят сюда же. Здесь — что можно спросить и как ответить.
Как подписываются запросы
Ключ выдаёт владелец магазина. У ключа есть область: полный доступ или только доставка. Ключ курьерского приложения в чужие разделы не пустит.
curl -H "X-API-Key: ваш-ключ" https://api.passage.kz/api/catalog
# кто продаёт — сервер пишет это имя в чеки и журнал
curl -H "X-API-Key: ваш-ключ" -H "X-Kassa-User: Асхат" \
-H "Content-Type: application/json" \
-d '{"items":[{"productId":12,"variantId":48,"price":24900,"qty":1}],"payment":"наличные","cashGiven":25000}' \
https://api.passage.kz/api/pos/checkout
Ответ всегда JSON и всегда с полем ok. Если что-то не так — {"ok": false, "error": "человеческое объяснение"}, а не голый код ошибки.
Каталог и товары
Покупателю видны только оформленные товары — те, что владелец включил в приложении.
| GET |
/api/catalog |
Витрина магазина: карточки с ценами, размерами и фото. Параметр since — отдать только изменённое. |
| GET |
/api/pos/products |
Полный список для кассы: остатки, штрихкоды, цвета и размеры. |
| GET |
/api/pos/models |
Модели одной строкой: сколько у каждой цветов и размеров. |
| GET |
/api/pos/model/{id} |
Карточка модели: матрица «цвет × размер» с остатками и штрихкодами. |
| GET |
/api/pos/scan?code= |
Что это за штрихкод: вернёт готовую строку чека. |
| GET |
/api/pos/stock |
Остатки со средней себестоимостью. |
Покупатели и бонусы
| GET |
/api/pos/client?code= |
Кто это: по QR карты, номеру карты или телефону. Вернёт бонусы и уровень. |
| POST |
/api/pos/sale |
Начислить и списать бонусы за покупку. |
| GET |
/api/crm/segments |
Группы покупателей: постоянные, давно не заходили, именинники. |
| GET |
/api/crm/client/{id} |
История покупок, любимый размер, заметки. |
| GET |
/api/wallet/pass?phone= |
Карта покупателя для Apple Wallet (.pkpass). |
Касса
Смена обязательна: без открытой смены чек не пробить — иначе деньги в ящике не сойдутся.
| GET |
/api/pos/shift |
Открыта ли смена, сколько наличных в ящике. |
| POST |
/api/pos/shift/open |
Открыть смену: cashStart — размен. |
| POST |
/api/pos/checkout |
Пробить чек: позиции, оплата, скидка, бонусы. Повтор с тем же uid второй чек не создаст. |
| POST |
/api/pos/refund |
Возврат по чеку. |
| POST |
/api/pos/cash |
Внести или изъять деньги из ящика. |
| GET |
/api/pos/analytics?kind= |
Отчёты: продажи, прибыль, кассиры, залежавшийся товар, размеры. |
| GET |
/api/pos/profit |
Выручка, себестоимость, расходы и чистая прибыль за срок. |
Склад и деньги
| POST |
/api/pos/purchase |
Приёмка от поставщика. |
| POST |
/api/pos/inventory |
Пересчёт: сколько реально лежит на полке. |
| POST |
/api/pos/writeoff |
Списание: брак, порча, витрина. |
| GET |
/api/pos/expenses |
Расходы магазина за период. |
| GET |
/api/pos/payroll |
Зарплата: оклад по дням плюс процент с личных продаж. |
| GET |
/api/pos/log |
Журнал действий сотрудников. |
Доставка
Ключ курьерского приложения открывает только этот раздел — ни выручки, ни покупателей ему не видно.
| POST |
/api/delivery |
Завести доставку. В ответ придёт код вручения из четырёх цифр. |
| GET |
/api/delivery |
Список доставок с расстоянием и временем в пути. |
| POST |
/api/delivery/{id}/take |
Курьер берёт заказ. |
| POST |
/api/delivery/{id}/point |
Точка курьера: широта, долгота, погрешность, курс, заряд телефона. |
| POST |
/api/delivery/{id}/status |
Состояние. Для done нужен код от покупателя. |
| GET |
/api/delivery/watch?id=&phone= |
Для покупателя: где курьер, сколько ехать, код получения. Без ключа, но чужую доставку не покажет. |
| GET |
/api/courier/orders?courierId= |
Заказы курьера: свои и свободные. |
Прочее
| GET |
/api/kassa/version |
Какая версия кассы сейчас на сервере — по ней программа обновляется сама. |
| GET |
/map/almaty.json |
Наша карта Алматы: улицы, реки, парки. Без ключа. |
| GET |
/kassa/PASSAGE-Kassa-Setup.exe |
Установщик кассы для Windows. |
Правила, которые стоит знать
Чек с тем же uid второй раз не проведётся — касса без связи может прислать его повторно, и это нормально. |
| Считает всегда сервер: скидки, бонусы, сдачу и себестоимость. Программе передаются готовые числа. |
| Остатки ведутся по паре «цвет + размер», а не по модели целиком. |
| Точки курьера с погрешностью больше 100 метров и невозможные скачки сервер отбрасывает сам. |