Сессии

Сессия — это объект в LIFE POS API, отвечающий за движения денег и товаров между вами и покупателем. Это любое ваше взаимодействие с покупателем, в рамках которого передаются деньги или позиции номенклатуры.

Сессии делятся на прямые и обратные. Оплата заказа, отгрузка товара или предоставление услуги — это прямые сессии, а возврат — обратная.

Например, у Василия интернет-магазин одежды. Покупатель заказал джинсы, пришёл в пункт выдачи, оплатил покупку и забрал её. Возникает прямая сессия — Василий получил от покупателя оплату и отгрузил ему товар. В терминах способов расчёта это полный расчёт.

Если бы покупатель оплачивал джинсы картой на сайте, а получал их у курьера, то прямых сессий возникло бы две: в рамках первой Василий получил бы от покупателя аванс, а в рамках второй отгрузил бы ему товар.

Внимание!

API LIFE POS пока не поддерживает работу со всеми признаками расчёта. Можно оформить только полный расчёт, т. е. получить оплату и отгрузить товар в рамках одной сессии.

Теперь представим, что покупатель примерил джинсы и они ему не подошли. Покупатель отдаёт их обратно курьеру, а Василий возвращает деньги на карту покупателю. Возникает обратная сессия: товар вернулся Василию, а деньги — покупателю. Сессия возврата должна быть привязана к исходной сессии продажи, чтобы было понятно, какая именно позиция и какие именно деньги возвращаются.

Бывает так, что в момент оплаты чек пробить не удалось. Тогда в момент создания чека коррекции возникает прямая сессия коррекции. Если же вы корректируете возврат, это обратная сессия коррекции. Как и обратная сессия, сессия коррекции должна быть привязана к той сессии, которую она корректирует.

Структура объекта Сессия

Рассмотрим структуру объекта Сессия в API LIFE POS — она одинакова и для прямых сессий, и для обратных, и для сессий коррекции; содержит следующие данные:

• sale — объект Продажа, содержащий guid продажи и тип объекта type_of.
• actions — массив объектов Действия, который описывает, что именно произошло в рамках сессии.
• fiscal_documents — массив объектов Фискальные документы. Когда по сессии появится чек, здесь появятся guid чека и тип объекта type_of.

При необходимости каждый объект массива fiscal_documents можно раскрыть, чтобы получить полную информацию о каждой транзакции. Для этого надо передать в запросе параметр expand:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}/sessions?expand=expand=fiscal_documents[:].fiscal_registrar&presentation=full

base_url — адрес сервиса. Возможные значения:

• https://api-dev.life-pos.ru — тестовый API,
• https://api.life-pos.ru — рабочий API.

Раскрытый объект будет содержать объект fiscal_registrar, который, в свою очередь, содержит следующие поля:

• model — модель фискального регистратора;
• registration_number — регистрационный номер;
• serial_number — серийный номер.

В массиве actions передаются следующие данные:

• money_action — объект Операция с деньгами и позициями. Содержит следующие поля:
  • purposes — массив объектов Предметы расчёта.
  • payment_parts — массив объектов Части платежа.
• non_purpose_money_action — объект Операция с деньгами. Пока не используется, поскольку признаки способа расчёта не поддержаны и подразумевается, что при получении каждой оплаты вы передаёте покупателю товар.
• shipping_action — объект Операция с позициями. Содержит массив объектов purposes, каждый из которых должен содержать (знаком * отмечены обязательные поля):
  • quantity * — количество позиций;
  • marking_attributes — данные о маркировке;
  • position — объект Позиция, содержащий guid позиции и тип объекта type_of.

В объекте money_action.purposes передаются следующие данные (знаком * отмечены обязательные поля):

• amount * — объект Стоимость товара. Содержит поля:
  • value — сумма;
  • currency * — валюта. Возможные значения: RUB, GBP, USD, EUR, Unknown.
  • position — объект Позиция, содержащий guid позиции и тип объекта type_of.

Объект money_action.payment_parts содержит данные о частях платежа. Частей платежа может быть сколько угодно, а конкретное содержимое каждой части зависит от способа, которым покупатель оплачивает заказ.

Сервис оплаты частями «Подели» (BnplPaymentPart):

• podeli_details – объект, содержащий обязательное поле order_id — идентификатор заказа.

Оплата картой (CardPaymentPart):

• transactions — массив ссылок на транзакции; каждая ссылка содержит поля guid и type_of.

При необходимости каждый объект массива transactions можно раскрыть, чтобы получить полную информацию о каждой транзакции. Для этого надо передать в запросе параметр expand:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}/sessions?expand=actions.*.payment_parts[:].transactions[:].bank_terminal&presentation=full

Адреса сервиса

Раскрытый объект будет содержать объект bank_terminal, который, в свою очередь, содержит следующие поля:

• model — модель банковского терминала;
• terminal_id — идентификатор банковского терминала;
• merchant_id — идентификатор продавца, выданный банком;
• reference_retrieval_number — RRN операции;
• card_number— номер карты покупателя.

Наличные (CashPaymentPart) — специальных полей нет.

Незарегистрированный перевод (CashlessPaymentPart) — специальных полей нет. Этот способ оплаты используется, если покупатель расплатился с вами переводом без использования платёжного шлюза LIFE POS. Например, отправил деньги по СБП.

Платёжная ссылка (LinkPaymentPart):

• external_id — внешний идентификатор.
• ttl — время жизни ссылки в минутах, от 5 до 2880.
• payment_url — адрес ссылки.
• expired_at – дата и время истечения срока жизни ссылки.
• transactions — массив ссылок на транзакции; каждая ссылка содержит поля guid и type_of.

Система быстрых платежей (QuickPaymantPaymentPart)

• transactions — массив ссылок на транзакции; каждая ссылка содержит поля guid и type_of.

При необходимости каждый объект массива transactions можно раскрыть, чтобы получить полную информацию о каждой транзакции. Для этого надо передать в запросе параметр expand:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}/sessions?expand=actions.*.payment_parts[:].transactions[:].quick_payments_terminal&presentation=full

Адреса сервиса

Раскрытый объект будет содержать объект quick_payments_terminal, который, в свою очередь, содержит следующие поля:

• model — модель терминала СБП;
• terminal_id — идентификатор терминала СБП;
• reference_retrieval_number — RRN операции.

Поля объекта money_action.purposes, общие для всех способов оплаты:

• amount * — объект Стоимость товара. Содержит поля:
  • value — сумма;
  • currency * — валюта. Возможные значения: RUB, GBP, USD, EUR, Unknown.
  • position — объект Позиция, содержащий guid позиции и тип объекта type_of.
• status * – статус платежа. Возможные значения: Draft, Accepted, Refunded.
• guid – идентификатор.

С помощью такой модели можно реализовать комбинированную оплату (например, часть картой, часть наличными), частичную предоплату с последующей доплатой, частичный возврат и т. д.

Вот и всё, что вам нужно знать о сессиях. В следующей статье поговорим о том, как использовать эту модель для получения оплаты.