Руководство администратора

Введение

Сокращения

Назначение

Руководство администратора предназначено для специалистов, осуществляющих настройку, сопровождение и контроль использования LIFE POS API в составе информационных систем пользователя.

Сведения о правообладателях

Авторские права на ПО «LIFE POS API» принадлежат ООО «Ритейл Бизнес Софт», 123112, г. Москва, вн. тер. г. Муниципальный округ Пресненский, Пресненская наб., дом 10, строение 2, помещ. 5Н. Сайт: life-pay.ru.

Управление продажами

В рамках быстрого старта вы открыли тестовую продажу. Как эта продажа соотносится с вашими реальными процессами? Чтобы разобраться в этом, рассмотрим пример.

У Василия служба доставки. Покупатели заказывают еду из ресторанов, а курьеры её привозят и получают оплату. Василий берёт из оплаты свою долю за доставку, а остальное передаёт ресторанам.

Пока курьер ходит по покупателям, Василий в офисе видит все открытые продажи и может получить информацию о каждой из них. Он может изменить данные заказа или отменить его. Когда работу над заказом закончили, Василий переносит его в архив.

Добавление продажи

Для всех заказов в API LIFE POS используется объект Продажа. Он объединяет информацию о товаре, передаваемом покупателю, его стоимости, статусе передачи и т. д. Именно продажу мы создавали в рамках быстрого старта.

Продажа создаётся POST-запросом по адресу:

{base_url}/orgs/{org_guid}/deals/sales

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

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

Описание запроса

Можно создать сразу несколько продаж. Для этого измените адрес POST-запроса:

{base_url}/orgs/{org_guid}/deals/sales.batch

Адреса сервиса · Описание запроса

Вместо одной продажи в теле запроса передайте массив сделок.

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

Созданные продажи появятся в приложении LIFE POS. Чтобы работать с продажей в приложении, включите приложение, откройте раздел Продажи и нажатием выберите продажу из списка. Подробнее: как в приложении LIFE POS редактировать созданную ранее продажу.

Изменение статуса продажи

Когда курьер доставил заказ, а покупатель оплатил его, можно изменить статус продажи. Для этого отправьте PATCH-запрос по адресу:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}

Адреса сервиса · Описание запроса

Модель статусов продажи описывается тремя параметрами:

В нашем примере нужно передать payment_status=Paid и shipping_status=Shipped.

С помощью PATCH-запроса на изменение продажи можно менять не только статус, но и другие данные. Например, если покупатель попросил добавить в заказ новый товар.

Получение данных о продаже

Если вам нужно видеть все открытые продажи, получите их список, отправив GET-запрос по адресу:

{base_url}/orgs/{org_guid}/deals/sales

Адреса сервиса · Описание запроса

Данные выводятся постранично, по 20 записей на страницу. Если нужно получить данные второй страницы, возьмите из ответа значение параметра next_page_token и отправьте новый запрос, передав это значение в параметре page_token. Продолжайте до тех пор, пока параметр next_page_token не придёт пустым.

Например, вы запросили данные о сотрудниках и получили такой ответ:

"next_page_token": "OdDEFa2CzpYdp1CmlO9s9mjBn4NkUZB3CXKOtNfQWM0",
"page_number": 1,
"pages_total": 2,
"items_per_page": 20,
"items_total": 27,

В ответе представлены только записи 1–20. Чтобы посмотреть записи с 21 по 27, отправьте новый GET-запрос, указав page_token="OdDEFa2CzpYdp1CmlO9s9mjBn4NkUZB3CXKOtNfQWM0".

Чтобы получить информацию о конкретной продаже, отправьте GET-запрос по следующему адресу:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}

Адреса сервиса · Описание запроса

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

Получение информации об оплате

Вы можете выгружать из системы LIFE POS информацию о движении денежных средств. Она отражена в прямой сессии, которая будет создана, когда курьер примет оплату.

Чтобы получить список прямых сессий, отправьте GET-запрос по адресу:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}/sessions

Адреса сервиса · Описание запроса

Данные выводятся постранично, по 20 записей на страницу. Если нужно получить данные второй страницы, возьмите из ответа значение параметра next_page_token и отправьте новый запрос, передав это значение в параметре page_token. Продолжайте до тех пор, пока параметр next_page_token не придёт пустым.

Например, вы запросили данные о сотрудниках и получили такой ответ:

"next_page_token": "OdDEFa2CzpYdp1CmlO9s9mjBn4NkUZB3CXKOtNfQWM0",
"page_number": 1,
"pages_total": 2,
"items_per_page": 20,
"items_total": 27,

В ответе представлены только записи 1–20. Чтобы посмотреть записи с 21 по 27, отправьте новый GET-запрос, указав page_token="OdDEFa2CzpYdp1CmlO9s9mjBn4NkUZB3CXKOtNfQWM0".

Данные конкретной прямой сессии получаются другим GET-запросом:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}/sessions/{session_type}/{session_guid}

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

Описание запроса

Если покупатель платил по карте, можете также получить данные транзакции. Для этого отправьте GET-запрос по адресу:

{base_url}/orgs/{org_guid}/terminals/{method}/{terminal_guid}/transactions/{transaction_guid}

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

Описание запроса для банковской карты · Описание запроса для СБП

Получение чека

Вы можете выгружать из системы LIFE POS фискальные документы, в том числе и чеки. Чтобы выгрузить список чеков, отправьте GET-запрос по адресу:

{base_url}/orgs/{org_guid}/fiscal-registrars/{registrar_guid}/docs

Адреса сервиса · Описание запроса

Данные выводятся постранично, по 20 записей на страницу. Если нужно получить данные второй страницы, возьмите из ответа значение параметра next_page_token и отправьте новый запрос, передав это значение в параметре page_token. Продолжайте до тех пор, пока параметр next_page_token не придёт пустым.

Например, вы запросили данные о сотрудниках и получили такой ответ:

"next_page_token": "OdDEFa2CzpYdp1CmlO9s9mjBn4NkUZB3CXKOtNfQWM0",
"page_number": 1,
"pages_total": 2,
"items_per_page": 20,
"items_total": 27,

В ответе представлены только записи 1–20. Чтобы посмотреть записи с 21 по 27, отправьте новый GET-запрос, указав page_token="OdDEFa2CzpYdp1CmlO9s9mjBn4NkUZB3CXKOtNfQWM0".

Чтобы получить данные конкретного кассового чека, отправьте GET-запрос по адресу:

{base_url}/orgs/{org_guid}/fiscal-registrars/{registrar_guid}/docs/receipts/{doc_guid}

Адреса сервиса · Описание запроса

Архивирование и восстановление продажи

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

Чтобы архивировать продажу, отправьте DEL-запрос по адресу:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}

Адреса сервиса · Описание запроса

Никакая информация не удаляется навсегда — из архива продажу можно вернуть. Для этого отправьте POST-запрос по адресу:

{base_url}/orgs/{org_guid}/deals/sales/{deal_guid}:unarchive

Адреса сервиса · Описание запроса

Продажа маркированных товаров

До сих пор мы разбирали продажу обычных товаров. Рассмотрим теперь специфику передачи данных о маркированных товарах.

Коды маркировки нужны, чтобы товар можно было отследить по всей цепочке от производителя до конечного покупателя. Данные о лекарствах собирает ИС МДЛП, а об остальных маркированных товарах — система «Честный знак».

Данные о маркировке передаются вместе с данными о товаре в POST-запросе создания сделки:

{base_url}/orgs/{org_guid}/deals/sales

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

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

Описание запроса

За данные о товаре отвечает массив positions. В нём с маркировкой связаны следующие поля:

В массиве marking_attributes передаются следующие поля:

В массиве marks передаются следующие поля:

Чтобы код маркировки правильно обрабатывался во всех системах, он должен соответствовать требованиям «Честного знака». Специальные символы нужно экранировать по стандарту RFC 8259, а <GS> заменять на \u001D.

Исходный код: 0104650117240408211dmfcZNcM"4
Экранированный код: 0104650117240408211dmfcZNcM\"4

Вы можете и не передавать код маркировки по API. В этом случае его обязательно нужно отсканировать на кассе.

К примеру, у Василия заказали две пары кожаных ботинок. В сделке появится массив positions, содержащий среди своих объектов маркированную позицию «Ботинки рабочие кожаные размер 41 черные Трейл Плюс ТЗ».

Обратим внимание на параметр "quantity": 2.0. Так как каждый код маркировки уникален, кодов должно быть передано два. Но Василий хочет одну марку передать по API, а вторую отсканировать на кассе. В этом случае объектов в массиве marks всё равно должно быть два, однако второй объект содержит только счётный параметр for_quantity.

"positions": [
  {
    "settlement_subject": "Product",
    "name": "Ботинки рабочие кожаные размер 41 черные Трейл Плюс Т3",
    "uom": {
      "guid": "25865e33-2efc-11df-942d-0023543d7b52",
      "type_of": "Uom"
    },
    "tax": "Tax20",
    "sale_price": {
      "value": 48800,
      "currency": "RUB",
      "type_of": "Money"
    },
    "quantity": 2.0,
    "total_sum": {
      "value": 48800,
      "currency": "RUB",
      "type_of": "Money"
    },
    "barcode": "4678599263104",
    "is_markable": true,
    "marking_attributes": {
      "marks": [
        {
          "marking_code": "010290000002493921AqjmFon,CoD_)\u001D91003E\u001D92DNI4UMPkN5SpwqPRN7c2ihHTHmM4ZnGm81A6qlFMNkedQnPm6SmcbDKfYt3XAJ+WVdl05ewWpGg/dpJEBAnI6g==",
          "for_quantity": 1.0,
          "checking_result": [
            "KPKMCheckedAutonomously"
          ]
        },
        {
          "for_quantity": 1.0
        }
      ]
    },
    "meta": "good_guid=0a135191-6469-11ea-80c8-00155dfc0b56",
    "guid": "2c9619d4-f005-49f6-a2b4-4014815b26f1",
    "type_of": "DealPosition"
  },

Неправильно — при значении "quantity": 2.0 передавать в массиве marks только один объект кода маркировки:

"is_markable": true,
"marking_attributes": {
  "marks": [
    {
      "marking_code": "010290000002493921AqjmFon,CoD_)\u001D91003E\u001D92DNI4UMPkN5SpwqPRN7c2ihHTHmM4ZnGm81A6qlFMNkedQnPm6SmcbDKfYt3XAJ+WVdl05ewWpGg/dpJEBAnI6g==",
      "for_quantity": 1.0,
      "checking_result": [
        "KPKMCheckedAutonomously"
      ]
    }
  ]
},

Готово! Вы зарегистрировали сделку с маркированным товаром.

Данные покупателя

LIFE POS позволяет собирать и хранить значительные данные о клиентах. Передав данные по API, вы упростите работу курьеру: ему не нужно будет вводить их руками при продаже — останется только передать товар, получить деньги и пробить чек.

Данные покупателя хранятся в сделке в объекте customer_data. Передать их в API можно POST-запросом, а получить — GET-запросом по адресу:

{base_url}/orgs/{org_guid}/deals/sales

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

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

Описание POST-запроса · Описание GET-запроса

Вот как выглядят сами данные:

"customer_data": {
  "name": "string",
  "inn": "string",
  "contacts": "string",
  "citizenship": "RUS",
  "identity_document_type": "RFPassport",
  "identity_document_data": "string",
  "date_of_birth": "2019-08-24T14:15:22Z",
  "address": "string"
}

Нюансы работы с полями:

Возможные значения поля identity_document_type:

• RFPassport,
• RFSpecialPassport,
• RFTemporaryIdentity,
• RFBirthCertificate,
• RFOtherDocuments,
• ForeignPassport,
• ForeignOtherDocuments,
• ForeignIdentity,
• ForeignResidence,
• ForeignTemporaryResidence,
• RefugeeApplication.

Чаще всего эти поля используются для передачи ФИО и ИНН или данных паспорта покупателя на фискальный регистратор — если нужно указать их в чеке.

Продажа по агентской схеме

LIFE POS поддерживает продажу товаров по агентской схеме. Такая схема подразумевает, что поставщик продаёт свои товары через стороннее лицо — агента. Агентом может быть ИП, компания, кредитная организация или торговый посредник. Агент занимается доставкой товара и принимает оплату. Для расчётов с физическими клиентами ему нужна онлайн-касса.

По закону касса должна передавать в ФНС информацию об агенте, поставщике и операторе перевода. В LIFE POS эти реквизиты нужно передать в сделке в объекте additional_attributes. Он находится внутри объекта positions. Это позволяет продавать часть позиций по агентской схеме, а другую часть как собственные товары.

Чтобы провести сделку по агентской схеме, заполните additional_attributes и отправьте POST-запрос для создания продажи:

{base_url}/orgs/{org_guid}/deals/sales

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

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

Описание запроса

Вот так выглядят сами данные:

"additional_attributes": {
  "as_agent_type_of": "String",
  "transfer_operator_name": "String",
  "transfer_operator_phones": "String",
  "transfer_operator_address": "String",
  "transfer_operator_inn": "String",
  "paying_agent_operation": "String",
  "paying_agent_phones": "String",
  "payment_operator_phones": "String",
  "supplier_name": "String",
  "supplier_inn": "String",
  "supplier_phones": "String"
}

Особенности работы с полями:

Организация

Организация в системе LIFE POS — это ваш бизнес. В организации может быть несколько юридических лиц, как и несколько магазинов. Их объединяет то, что они работают на вас. Рассказываем, что можно сделать с организацией через API LIFE POS.

Проверить псевдоним

У каждой организации в системе LIFE POS есть псевдоним — значение поля alias. Этот псевдоним должен быть уникальным. Чтобы проверить доступность придуманного псевдонима, отправьте POST-запрос по адресу:

{base_url}/orgs:check-alias-availability

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

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

Описание запроса

Добавить организацию

Чтобы добавить организацию, отправьте POST-запрос по адресу:

{base_url}/orgs

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

Метод отправит вам смс с логином и пин-кодом для входа в приложение LIFE POS.

Кроме организации, метод создаст:

• Роли пользователей по умолчанию.
• Страницу с контактами техподдержки, если вы заполнили поле support.
• Сотрудника организации с ролью Владелец. Сотрудник привязывается к аккаунту, от которого поступил запрос на создание организации.
• Сущность Системная валюта (OrganizationOption: SYSTEM_CURRENCY) со значением RUB.
• Единицы измерения: Не задана, Килограмм, Штука, Литр.
• Расширения, данные которых вы указали в объекте extensions.

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

Подробное описание запроса

Получить данные организации

Чтобы получить список организаций, отправьте GET-запрос по адресу:

{base_url}/orgs

Адреса сервиса · Описание запроса

Данные выводятся постранично, по 20 записей на страницу. Если нужно получить данные второй страницы, возьмите из ответа значение параметра next_page_token и отправьте новый запрос, передав это значение в параметре page_token. Продолжайте до тех пор, пока параметр next_page_token не придёт пустым.

Например, вы запросили данные о сотрудниках и получили такой ответ:

"next_page_token": "OdDEFa2CzpYdp1CmlO9s9mjBn4NkUZB3CXKOtNfQWM0",
"page_number": 1,
"pages_total": 2,
"items_per_page": 20,
"items_total": 27,

В ответе представлены только записи 1–20. Чтобы посмотреть записи с 21 по 27, отправьте новый GET-запрос, указав page_token="OdDEFa2CzpYdp1CmlO9s9mjBn4NkUZB3CXKOtNfQWM0".

Чтобы получить данные о конкретной организации, отправьте GET-запрос по другому адресу:

{base_url}/orgs/{org_guid}

Описание запроса

Изменить данные организации

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

Подробнее про расширения

Чтобы скорректировать данные, отправьте PATCH-запрос по адресу:

{base_url}/orgs/{org_guid}

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

В теле запроса передайте изменения.

Описание запроса

Удалить и восстановить данные организации

Полностью удалить данные организации нельзя, но их можно отправить в архив. Данные исчезнут из интерфейса, но сохранятся на сервере LIFE POS. Чтобы заархивировать данные, отправьте DELETE-запрос по адресу:

{base_url}/orgs/{org_guid}

Адреса сервиса · Описание запроса

Чтобы восстановить данные из архива, отправьте POST-запрос по адресу:

{base_url}/orgs/{org_guid}:unarchive

Вот и всё, что касается настроек организации.