Outofbox.54-FZ : API для интернет-магазина

Для фискализации онлайн оплат на стороне интернет-магазина необходимо реализовать API для возврата чеков на фискализацию. API должно отдавать по GET запросу список чеков.

Пример списка чеков

Пример ответа
[
    {
        "id": 85,
        "created_at": "2018-01-10T03:57:38+0000",
        "version": 8,
        "type": "sell",
        "email": "my-favorite-client@gmail.com",
        "print": false,
        "items": [{
            "name": "Чипсы Lays",
            "price": 100,
            "quantity": 1
        }, {
            "name": "Сухарики",
            "price": 50,
            "quantity": 12
        }],
        "_links": {
            "lock": {
                "rel": "self",
                "href": "http:\/\/ecommerce.ru\/\/payment-receipts\/85\/actions\/lock"
            },
			"status": {
                "rel": "self",
                "href": "http:\/\/ecommerce.ru\/\/payment-receipts\/85\/status"
            }
        }
    },
    {
        "id": 86,
        "created_at": "2018-01-10T03:57:40+0000",
        "version": 1,
        "type": "return",
        "email": "my-favorite-client@gmail.com",
        "print": false,
        "items": [{
            "name": "Чипсы Lays",
            "price": 100,
            "quantity": 1
        }, {
            "name": "Сухарики",
            "price": 50,
            "quantity": 12
        }],
        "_links": {
            "lock": {
                "rel": "self",
                "href": "http:\/\/ecommerce.ru\/\/payment-receipts\/86\/actions\/lock"
            }
        }
    }
]

Описание полей

Наименование Тип данных Описание
id Integer|String Внутренний идентификатор чека в системе интернет-магазина
created_at String Дата создания чека
version Integer Версия чека. Используется для механизма защиты от одновременной печати чеков несколькими аппаратами
type String

Тип чека. Может принимать одно из значений:

  • sell – чек продажи
  • return – чек возврата продажи
email String

Email клиента, на который будет отправлен кассовый чек

print Bool Печатать или нет бумажный чек. Имеет смысл только если указан email клиента. Если email не указан, то бумажный чек будет напечатан вне зависимости от этой настройки.
items Array Массив позиций чека
_links Object Ассоциативный массив с указанием URL для работы

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

Последовательность действий следующая:

  • Outofbox.54-FZ запрашивает список чеков
  • Приложение в объекте _links ищет ссылку на lock, чтобы исключить вероятность печати чека повторно
  • Приложение отправляет POST запрос на lock url с указанием version, полученном из предыдущего шага. Здесь реализован механизм OPTIMISTIC LOCK
  • Интернет-магазин при запросе на lock url должен пометить чек как отпечатанный, либо вообще удалить его из базы, чтобы при последующем запросе списка чеков данный чек больше не появлялся в списке
  • В случае, если запрос на lock url завершился кодом HTTP 200, то приложение начинает фискализацию данного чека

Данный процесс запускается с определенной периодичностью.

Отчет о статусе печати чека

Также система может опционально сообщить на удаленный сервер о статусе печати чека. Для этого помимо ссылки lock, следует передать ссылку status. Чеки, у которых задан этот параметр, после печати (успешной или не успешной), будут отправлять информацию о печати на сервер. Делается это посредством POST запроса на указанный URL с передачей в теле сообщения JSON структуры с информацией.

При удачной печати чека

{
    "status": "success",
    "requisites": {
		"date": "13-03-2018",
		"time": "17:59",
		"fdn": "1234",
		"fp": "123456789",
		"session": "123"
	}
}

В объекте requisites будет содержаться информация о чеке:

Наименование Описание
date Дата фискализации в формате ДД-ММ-ГГГГ по времени, настроенном на ККМ
time Время фискализации в формате ЧЧ:ММ по времени, настроенном на ККМ
fdn Номер документа
fp Фискальный признак чека
session Номер смены

При неудачной печати чека:

{
    "status": "error",
    "error": {
        "message": "Ошибка: закончилась бумага"
	}
}