2.4 - Взаимодействие с платёжной системой или системой лояльности
2.4.1 Общее описание
web-сервис должен быть развёрнут со стороны back-офиса (со стороны 1С).
https-методы web-сервиса необходимы для получения информации о наличии карты, получения баланса по данной карте, правил использования средствами на карте, информации о владельце карты, а также для отправки информации об оплате заказа средствами с данной карты.
Ответ от сервера приходит в формате json
2.4.2 Команда получения информации по карте
Назначение: получение информации по карте, проверка баланса. Метод можно использовать дважды в сценарии работы с заказом: запрос с полной информацией по карте для отображения информации о владельце на экране для пользователя, далее перед процедурой оформления заказа повторить запрос для проверки баланса.
- Запрос от POS к web-сервису
Метод: [адрес сервера]/GetClientInfo
Обязательные поля запроса:
- request_id - уникальный идентификатор запроса типа GUID
- timestamp - время запроса в формате ISO 8601 ("2024-03-31T15:00:00Z")
- customer_identifier — способ идентификации клиента (объект):
- type - тип идентификатора (phone, card_number, email, qr_code)
- value - значение идентификатора
- get_customer_info - флаг, указывающий, нужно ли возвращать полную информацию о клиенте (true/false)
- total_amount - общая сумма чека до применения скидок (число ≥ 0)
- currency - валюта (например, RUB, USD)
- order_number - номер заказа (строка)
Опциональные поля запроса:
- remote_id - идентификатор удалённого подразделения (объекта)
- order_items — массив позиций заказа (может отсутствовать или быть null):
каждый элемент массива — объект с полями:
- product_id — внутренний ID товара (строка)
- quantity — количество (число ≥ 0, может быть дробным)
- price — цена за единицу (число ≥ 0)
- item_modifiers — массив модификаторов для позиции (может отсутствовать)
- каждый модификатор — объект с теми же полями (product_id, quantity, price)
- order — информация о заказе - текст в формате 1С (АРМ) (может отсутствовать или быть null)
Пункты:
Используется как альтернатива order_items.
Сервер должен вернуть ошибку, например, validation_error с кодом 400 если указано 2 поля (order_items и order).
Правила использования опциональных полей:
- Нельзя одновременно передавать заполненные order_items и order.
- Если нужны расчёты по составу заказа, должно быть заполнено одно из полей: order_items или order.
- Если оба поля отсутствуют или равны null, сервер возвращает только баланс и лимиты без учёта состава заказа.
Пример запроса:
POST
https://127.0.0.1/diningCard/GetClientInfo
Request body:
{
"request_id": "b2c3d4e5-f678-9012-3456-7890abcdef12",
"timestamp": "2025-07-22T12:00:00Z",
"remote_id": "POS-001",
"customer_identifier": {
"type": "card_number",
"value": "1234567890123456"
},
"get_customer_info": true,
"order_number": "00000895",
"order": "Чек 00000895/000000 22.07.25 12:00:00 1 1118.00 000000 Администратор
00089 1.0 318.00 318.00 0 000000 0.00% 0000000000000
~ 00086 1.0 76.00 76.00 0 000000 0.00% 0000000000000
00130 2.0 400.00 800.00 0 000000 0.00% 0000000000000",
"total_amount": 1118.00,
"currency": "RUB"
}
- Ответ от web-сервиса
Обязательные поля ответа:
- response_id - уникальный идентификатор ответа, соответствует request_id из запроса (строка в формате UUID).
- code – http-код ответа
- 200 - OK — для status = "success"
- 400 - Bad Request — для ошибок валидации
- 404 - Not Found — если транзакция не найдена;
- 500 - Internal Server Error — для внутренних ошибок сервера.
- balance_info - финансовые параметры (объект):
- card_balance - текущий баланс по карте клиента (число ≥ 0);
- max_redeem_amount - максимальная сумма, доступная для списания с карты в текущий момент (0 – запрет списания).
Опциональные поля ответа:
- error – информация об ошибке, null, если code = 200
- error_code – код ошибки (строка)
- message – текст ошибки
- details – информация об ошибке (поля зависят от кода ошибки)
- identifier_type – пример полей для описания ошибки
- identifier_value – пример полей для описания ошибки
- customer_info - информация о клиенте (может быть null)
Возвращается только если в запросе get_customer_info = true
Структура объекта:
- client_id - внутренний идентификатор клиента (строка)
- surname - фамилия клиента
- name - имя клиента
- second_name - отчество клиента (строка или null)
- sex - пол клиента (целое число: 1 — мужской, 2 — женский, 0 — не указан)
- birthday - дата рождения клиента (строка в формате ISO 8601, пример: “1984-03-31”)
- phone - номер телефона клиента (строка или null)
- email - электронная почта клиента (строка или null, формат email)
- registration_date - дата регистрации клиента в системе (строка в формате ISO 8601, пример: “2024-03-31”).
Пример положительного ответа:
Json:
{
"response_id": "b2c3d4e5-f678-9012-3456-7890abcdef12",
"code": 200,
"customer_info": {
"client_id": "CUST-00012345",
"surname": "Иванов",
"name": "Иван",
"second_name": "Иванович",
"sex": 1,
"birthday": "1985-05-15",
"phone": "+79123456789",
"email": "ivan.ivanov@example.com",
"registration_date": "2025-01-10T09:30:00"
},
"balance_info": {
"card_balance": 1500.00,
"max_redeem_amount": 1000.00
}
}
Пример ответа с ошибкой:
Json:
{
"response_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
"code": 404,
"error": {
"error_code": "customer_not_found",
"message": "Клиент с указанным идентификатором не найден",
"details": {
"identifier_type": "phone",
"identifier_value": "+79123456789"
}
}
}
2.4.3 Команда подтверждения транзакции (оплата средствами на карте или накопление)
Назначение: фиксация списания баллов/бонусов по карте в рамках чека.
- Запрос от POS к web-сервису
Метод: [адрес сервера]/ApplyTransaction
Обязательные поля запроса:
- request_id - уникальный идентификатор запроса типа GUID
- timestamp - время запроса в формате ISO 8601 ("2024-03-31T15:00:00Z")
- customer_identifier — способ идентификации клиента (объект):
- type - тип идентификатора (phone, card_number, email, qr_code)
- value - значение идентификатора
- total_amount - общая сумма чека для оплаты
- applied_amount - сумма баллов/бонусов, которая списывается при оплате заказа. Если 0 – возможно накопление баллов/бонусов, накопление происходит по внутренним правилам платёжной системы исходя из переданной информации о заказе. Поле applied_amount не должно быть больше max_redeem_amount – максимальной суммы, доступной для списания, иначе метод должен вернуть код ошибки 400.
- currency - валюта (например, RUB, USD)
- order_number - номер заказа (строка)
- transaction_id - уникальный ID транзакции списания (GUID). Генерируется POS для предотвращения дублирования.
Повторные запросы с тем же transaction_id должны возвращать тот же результат без повторного списания.
Опциональные поля запроса:
- remote_id - идентификатор удалённого подразделения (объекта)
- order_items — массив позиций заказа (может отсутствовать или быть null):
каждый элемент массива — объект с полями:
- product_id — внутренний ID товара (строка)
- quantity — количество (число ≥ 0, может быть дробным)
- price — цена за единицу (число ≥ 0)
- item_modifiers — массив модификаторов для позиции (может отсутствовать)
- каждый модификатор — объект с теми же полями (product_id, quantity, price)
- order — информация о заказе - текст в формате 1С (АРМ) (может отсутствовать или быть null)
Пункты:
Используется как альтернатива order_items.
Сервер должен вернуть ошибку, например, validation_error с кодом 400 если указано 2 поля (order_items и order).
Правила использования опциональных полей:
- Нельзя одновременно передавать заполненные order_items и order.
- Если нужны расчёты по составу заказа, должно быть заполнено одно из полей: order_items или order.
Пример запроса:
POST
https://127.0.0.1/diningCard/ApplyTransaction
Request body:
{
"request_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
"timestamp": "2026-03-25T14:30:00Z",
"remote_id": "STORE-001",
"customer_identifier": {
"type": "phone",
"value": "+79123456789"
},
"order_number": "ORD-20260325-001",
"total_amount": 445.00,
"applied_amount": 100.00,
"transaction_id": "b2b3c3d9-e5f6-7890-1234-56789abcdef0",
"order_items": [
{
"product_id": "P-123",
"quantity": 2.5,
"price": 150.00,
"item_modifiers": [
{
"product_id": "MOD-001",
"quantity": 1.0,
"price": 20.00
}
]
}
],
}
- Ответ web-сервиса
Обязательные поля ответа:
- response_id - уникальный идентификатор ответа, соответствует request_id из запроса (строка в формате UUID).
- code – http-код ответа
- 200 - OK — для status = "success"
- 400 - Bad Request — для ошибок валидации
- 404 - Not Found — если транзакция не найдена;
- 500 - Internal Server Error — для внутренних ошибок сервера.
Опциональные поля ответа:
- transaction_confirmation_id - идентификатор подтверждения транзакции. Используется для отслеживания и отмены операции. null, если status = «error».
- error – информация об ошибке, null, если code = 200
- error_code – код ошибки
- message – текст ошибки
- details – информация об ошибке (поля зависят от кода ошибки)
- available_balance – пример полей для описания ошибки
- requested_amount – пример полей для описания ошибки
Пример положительного ответа:
Json:
{
"response_id": "b2c3d4e5-f678-9012-3456-7890abcdef12",
"transaction_confirmation_id": "b4c3e7e5-f678-9012-3456-7890abcdef12",
"code": 200
}
Пример ответа с ошибкой:
Json:
{
"response_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
"code": 400,
"error": {
"error_code": "insufficient_balance",
"message": "Недостаточно баллов на карте для списания запрошенной суммы. Доступно: 120.00, запрошено: 150.00",
"details": {
"available_balance": 120.00,
"requested_amount": 150.00
}
}}
2.4.4 Команда отмены транзакции (возврат средств на карту или отмена накоплений)
Назначение: отмена ранее выполненной транзакции списания средств с карты (возврат средств на карту клиента) или отмены накоплений. Используется при отмене или возврате чека.
- Запрос от POS к web-сервису
Метод: [адрес сервера]/ReverseTransaction
Обязательные поля запроса:
- request_id - уникальный идентификатор запроса типа GUID
- timestamp - время запроса в формате ISO 8601 ("2024-03-31T15:00:00Z")
- original_transaction_id - GUID транзакции списания, которую нужно отменить. Это transaction_id из метода ApplyTransaction
- reversal_amount — сумма заказа, по которому выполняется возврат/отмена (сумма должна совпадать с суммой в исходной транзакции. Дополнительный контроль, частичная отмена не поддерживается).
- order_number - номер заказа (строка)
Опциональные поля запроса:
- remote_id - идентификатор удалённого подразделения (объекта)
- reason — причина отмены (строка, возможные значения):
- order_cancelled — полный отказ от заказа
- item_returned — возврат части товаров
- error_in_calculation — ошибка в расчётах
- duplicate_transaction — дублирование транзакции
- customer_request — по просьбе клиента
Пример запроса:
POST
https://127.0.0.1/diningCard/ReverseTransaction
Request body:
{
"request_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef4",
"timestamp": "2026-03-25T15:45:00Z",
"remote_id": "STORE-001",
"original_transaction_id": "b4c3e7e5-f678-9012-3456-7890abcdef12",
"reason": "order_cancelled",
"reversal_amount": 100.00,
"order_number": "ORD-20260325-001"
}
- Ответ от web-сервиса
Обязательные поля ответа:
- response_id - уникальный идентификатор ответа, соответствует request_id из запроса (строка в формате UUID).
- code – http-код ответа
- 200 - OK — для status = "success"
- 400 - Bad Request — для ошибок валидации
- 404 - Not Found — если транзакция не найдена;
- 500 - Internal Server Error — для внутренних ошибок сервера.
Опциональные поля ответа:
- error – информация об ошибке, null, если code = 200
- error_code – код ошибки
- message – текст ошибки
- details – информация об ошибке (поля зависят от кода ошибки)
- searched_transaction_id – пример полей для описания ошибки
Пример положительного ответа:
Json:
{
"response_id": "b2c3d4e5-f678-9012-3456-7890abcdef12",
"code": 200
}
Пример ответа с ошибкой:
{
"response_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef4",
"code": 404,
"error": {
"error_code": "transaction_not_found",
"message": "Транзакция не найдена в системе",
"details": {
"searched_transaction_id": "b4c3e7e5-f678-9012-3456-7890abcdef12"
}
}
}