В CASHOFF есть два способа загрузки чеков: из ЛК программ лояльности магазинов и через реквизиты чека.

Первый способ предполагает подключение профиля программы лояльности с последующим импортом из неё чеков. Чеки импортируются из провайдеров с типом retail_store и gas_station, при чем импортируются все чеки, которые доступны в ЛК провайдера. Процесс подключения профилей подробно описан в разделе Импорт данных из внешних провайдеров.

Второй способ предполагает загрузку чеков по отдельности через реквизиты чека, которые либо печатаются на самом чеке, либо указаны в электронном чеке. В этом способе чеки импортируются из ФНС/ОФД. Данный способ описывается в этом разделе.

Получение реквизитов чека

Реквизитами чека являются поля с названиями ФН, ФД, ФПД, а так же дата, время и сумма покупки. По этим данным CASHOFF может загрузить полную информацию по чеку.

В чеке реквизиты указываются двумя способами: непосредственно напечатанными значениями этих полей и с помощью QR кода.

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

В случае QR кода, если его просканировать, будут получены данные следующего вида:

t=20190312T180300&s=221.16&fn=8710000101843462&i=238355&fp=3156582516&n=1

Эта строка и содержит все необходимые для загрузки чека поля.

Следует обратить внимание на то, что на чеках могут быть и другие QR коды, содержащие другие данные: ссылки на сайт магазина, промоакции или еще что-то.

Такие QR не подходят, как не подходят и QR коды ЕГАИС - по ним CASHOFF не загрузит чек, а при попытке добавления вернет статус invalid_format.

Передача реквизитов чека в CASHOFF

Предусмотрено два способа передачи реквизитов в CASHOFF:

1. передача данных QR кода в виде строки
2. передача фотографии чека - в таком случае CASHOFF самостоятельно извлечет реквизиты с фотографии и сформирует строку из п. 1

Для передачи готовых реквизитов используется запрос POST /receipts/import-from-qr, которому в поле qr_data необходимо предать текст строки QR. Если QR по какой-то причине не доступен/не читается, то можно данную строку сформировать вручную из распечатанных на чеке данных.

Для передачи фото используется запрос POST /receipts/import-from-photo. В теле этого запроса нужно передать фото в бинарном виде. Для успешной загрузки необходимо, что бы реквизиты на фото были в читаемом виде, предпочтительно что бы это был QR код.

Вне зависимости от способа отправки  формат ответа будет одинаковый:

{
    "status": "accepted",
    "pending_receipt": {
        "id": 185938,
        "add_date": "2019-03-28T09:12:52Z",
        "status": "loading"
    }
}

Тут поле status первого уровня отвечает за статус передачи реквизитов (реквизиты приняты), а поле status второго уровня сообщает статус загрузки принятого чека (идет загрузка).

В CASHOFF нельзя повторно добавлять один и тот же чек одному и тому же пользователю, по этому при попытке добавить вернется статус exist. Если данный чек уже добавлен для загрузки, но еще не загружен, то вернется существующий объект pending_receipt.

Фоновая загрузка чека

При добавлении в CASHOFF чека в загрузку приложение в ответ получит объект pending_receipt - это промежуточная сущность, которая используется для отслеживания процесса загрузки чека. Она содержит в себе реквизиты чека, дату добавления, статус загрузки и ссылку на загруженный чек.

Если чек загружен через фотографию, то реквизитов по началу может не быть - они будут извлечены из фотографии в фоновом режиме. Однако если в фоновом режиме реквизиты извлечь не удастся, то запись получит статус invalid.

Пример чека в загрузке:

{
    "status": "accepted",
    "pending_receipt": {
        "id": 186313,
        "qr_data": "t=20190321T1419&s=509.90&fn=8710000101091314&i=103220&fp=2098419135&n=1",
        "add_date": "2019-03-28T11:47:59Z",
        "amount": 509.9,
        "date": "2019-03-21T14:19:00Z",
        "status": "loading"
    }
}

Данные по чеку могут быть не сразу доступны в ФНС, по этому в ряде случаев загрузка может занять время - обычно это 1-2 минуты, но может и растянутся до нескольких дней.

CASHOFF пытается получить данные чека на протяжении 30 дней, по окончанию которых загрузка чека прекращается и он получает статус timed_out.

Для записей о загружаемых чеков доступны запросы по получению списка (GET /receipts/pending), просмотра конкретной записи (GET /receipts/pending/{pending_id}) и её удаление (DELETE /receipts/pending/{pending_id}).

Успешная загрузка чека

После успешной загрузки данных чека в запись о загрузке будет добавлена ссылка на загруженный чек (receipt_id) и статус loaded:

{
  "id": 45,
  "add_date": "2019-02-15T11:14:28.000Z",
  "amount": "123.50",
  "date": "2019-02-05T00:00:00.000Z",
  "status": "loaded",
  "receipt_id": 6347
}

В таком случае загруженный чек можно будет получить в списке чеков по указанному id (receipt_id). 

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

В CASHOFF предусмотрено событие receipt.pending_resolved, которое отправляется в тех случаях, когда запись о загрузке получает конечный статус: это как успех (loaded), так и прекращение загрузки (timed_out, invalid). Тело события будет содержать полную информацию по pending_receipt. Подробнее о получении уведомлений описано в разделе Нотификации.