Различия

Показаны различия между двумя версиями страницы.

--- external:procart:02_procart_api:01_api [2022/10/01 12:46] – [Типовая схема запросов] Александр Ильин
+++ external:procart:02_procart_api:01_api [2024/06/10 09:44] (текущий) – [Перечень методов API ProCart] Данил Володченко
@@ Строка 1: / Строка 1: @@
 ====== Описание API ======
-===== Перечень запросов API ProCart =====
+===== Перечень методов API ProCart =====
   * **/ping** - служебный метод для проверки связи, состояния лицензии, валидности токена.
   * **/getmenu** - метод для получения меню (классификация, блюда и их свойства, остатки, схемы модификаторов и комбо).
   * **/validate** - метод для проверки возможности создания заказа (заказ НЕ создается).
-  * **/postorder** - метод для создания заказа.
+  * **/postorder** - метод для создания заказа в кассовой системе.
   * **/getorders** - метод для получения информации о заказах.
-  * **/print_info** - служебный метод для получения длинных комментариев (используется в макетах печатных форм r_keeper).
+  * **/close** - метод для закрытия заказа.
+  * **/internal/print_info** - служебный метод для получения длинных комментариев (используется в макетах печатных форм r_keeper).
-===== Типовая схема запросов =====
+Документация к API - [[http://95.64.142.2:1112/swagger#|ссылка]]
+Токен API: 28bb0d65-d1a3-447d-a3eb-e4961b0ffd35
+Все запросы отправляются в "ip:port/api/v3"
+Например [[http://127.0.0.1:11111/api/v3/ping|127.0.0.1:11111/api/v3/ping]]
+**Важно!** Все методы возвращают ответы в кодировке UTF-8
+===== Некоторые особенности использования методов API =====
 Метод **/ping** не является обязательным и не приводит ни к каким действиям на стороне кассовой системы, но в то же время он очень полезен. С его помощью можно:
   * Проверить доступность ProCart
@@ Строка 18: / Строка 26: @@
 Рекомендуется выполнять запрос **/ping** при начале работы.
+----
 Метод **/getmenu** позволяет получить информацию о блюдах и их остатках, доступных для продажи во внешней системе. При большом количестве блюд, ответ на данный запрос может занимать значительное время (500-2000 мс), поэтому рекомендуется производить кеширование ответов на стороне внешней системы. Модуль ProCart так же кеширует меню на своей стороне и проверяет обновления с периодичностью 10-60 секунд. Поэтому для внешней системы вызывать метод **/getmenu** чаще чем 1 раз в минуту не имеет особого смысла.
-Метод **/validate** так же не является обязательным, но его использование крайне рекомендовано. Данный метод позволяет провалидировать содержимое корзины. Т.е. убедиться что такой заказ (можно создать в кассовой системе в текущий момент времени.
+----
-Данный метод так же нужен для корректного отображения "корзины" во внешней системе. Т.к. в зависимости от настроек r_keeper и передаваемых параметров ("категория заказа", стол, скидка и т.п.) кассовая система может менять стоимость блюд в заказе.
+Метод **/validate** так же не является обязательным, но его использование крайне рекомендовано. Данный метод позволяет провалидировать содержимое корзины. Т.е. убедиться что такой заказ можно создать в кассовой системе в текущий момент времени.
+Данный метод так же нужен для корректного отображения "корзины" во внешней системе. Т.к. в зависимости от настроек r_keeper и дополнительных параметров заказа ("категория заказа", стол, скидка и т.п.) кассовая система может изменять стоимость блюд в заказе.
 **Важно!** Вызов данного метода не приводит ни к каким событиям на кассе (заказ не создается).
-Метод **/postorder** создает заказ на кассе r_keeper.
+----
+Метод **/postorder** создает заказ на кассе r_keeper. Если заказ создан успешно, то в ответе на запрос вернется GUID созданного в системе r_keeper заказа, используя который в дальнейшем можно отслеживать изменения состояния этого заказа используя метод **/getorders**
 **Важно!** Если логика внешней системы подразумевает оплату заказа, то перед тем как вызвать метод **/postorder** необходимо провести оплату заказа (а сумму к оплате взять из ответа на запрос **/validate**). И только после успешной оплаты создавать заказ методом **/postorder**, не забыв при этом передать данные об оплате.
+===== Типовая схема запросов =====
 В итоге, для того что бы создать заказ на кассе, внешняя система должны последовательно выполнить запросы:
   - Убедиться в доступности шлюза ProCart (**/ping**).
@@ Строка 33: / Строка 48: @@
   - Убедиться в возможности создания заказа с нужным перечнем блюд в текущий момент времени (**/validate**).
   - Создать заказ (**/postorder**).
-  - При необходимости отслеживать изменения статуса заказа (**/getorders**).
+  - При необходимости отслеживать дальнейшие изменения статуса заказа (**/getorders**).
+----
+**Важно!**
+При создании заказа, через **callback_url** возможно указать адрес, куда будет отправляться состояние заказа при изменении его статуса.
+Заказ может иметь статус:
+  * deferred - заказа создан в кассовой системе как черновик
+  * open - заказ создан в кассовой системе и с ним ведётся работа
+  * bill - в заказе выбит пречек
+  * close - закрыт выполнен рассчёт по заказу и выбит чек
+  * deleted - заказ удалён в кассовой системе