API сервиса

Для работы с сервисом необходимо отправить чек POST запросом

POST-запрос отправляется на адрес https://api.check4promo.ru/api/v1/check/add и должен включать в себя следующие параметры:

• contractor_id — идентификатор контрагента (выдается при регистрации в системе)
• project_id — идентификатор проекта (выдается при регистрации проекта)
• check_data — строка с данными чека

1. Формат строки с данными чека

Строка с данными чека следующего формата — t=20211126T1312&s=217.92&fn=9280440301243863&i=130322&fp=3526159982&n=1, где:

t — дата и время;

s — сумма чека;

fn — номер фискального накопителя;

i — номер фискального документа;

fp — фискальный признак документа;

n — тип операции (Приход/Возврат прихода/Расход/Возврат расхода);

sign — подпись.

2. Алгоритм формирования подписи

/** * @param array $data Массив данных c полями contractor_id,project_id,check_data,sign * @param string $secretKey Ключ указанный в личном кабинете * @return string */ function createSign(array $data, string $secretKey): string { ksort($data); $sign = ''; foreach($data as $key = & gt; $value) { if ($key != 'sign') { if (!is_array($value)) { $sign. = "|$key=$value"; } else { $sign. = "|$key=".json_encode($value); } } } $sign. = '|secret_key='.$secretKey. '|'; return md5($sign); }

3. Вариации ответа

• Успешный ответ:
  

  {
    "success": true,
    "payload": {
      "contractor_id": 2,
      "project_id": 9,
      "check_id": 54695
    }
  }
  

• Ответ с ошибкой:
  

  {
    "success": false,
    "payload": {
      "errorKey": "bad_signature",
      "message": "Bad signature",
    }
  }
  

• Возможные ошибки:
  

  1. Запрос с неразрешенного IP

  {
    "errorKey": "ip_not_allowed",
    "message": "IP not allowed",
  }
  

  2. Неверная подпись

  {
    "errorKey": "bad_signature",
    "message": "Bad signature"
  }
  

  3. Чек не принят, так как продавец заблокирован

  {
    "errorKey": "block_inn",
    "message": "Too many requests for inn"
  }
  

  4. Исчерпан суточный лимит запросов

  {
    "errorKey": "request_limit_daily",
    "message": "The daily limit of requests has been exceeded"
  }
  

  5. Превышен суточный лимит запросов для данного чека

  {
    "errorKey": "check_limit_daily",
    "message": "The daily limit of checks has been exceeded"
  }
  

  6. Превышен общий лимит запрос для данного чека

  {
    "errorKey": "check_limit_total",
    "message": "The total limit of checks has been exceeded"
  }
  

  7. Ошибка валидации данных запроса(messages содержит названия полей, которые были заполнены с ошибкой)

  {
    "errorKey": "validation",
    "messages": {
      "check_data": [
        "Invalid check data"
      ]
    }
  }
  

4. Выполнение вебхука и возможные ошибки

Далее будет выполнен вебхук (асинхронный POST) запрос по ссылке указанный в настройках личного кабинета

• Ответ вебхука без ошибки:
  { "contractor_id": 2, "project_id": 9, "check_id": 56669, "success": true, "data": { "id": 4006401313179427330, "ofdId": "ofd22", "address": "413113,Россия,Саратовская область,Энгельсский м.р-н.,город Энгельс г.п.,Энгельс г,Энгельс-1 мкр.,,,д. 57,,,,", "content": { "code": 3, "user": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"АГРОТОРГ\"", "items": [{ "nds": 1, "sum": 1699, "name": "*ЧУПА ЧУПС Карамель ФРУТ-ТЕЛ.17г", "price": 1699, "quantity": 1, "paymentType": 4, "productType": 1, "moderation": { "status": "blacklist_project", "promoaction_products": [] } }, { "nds": 1, "sum": 9999, "name": "РОДНЫЕ ПРОСТОРЫ Конфеты с ваф/крошко", "price": 9999, "ndsSum": 1667, "quantity": 1, "moderation": { "status": "greylist", "promoaction_products": [ "Родные Просторы®. Конфеты с вафельной крошкой. 200гр", "Родные Просторы®. Конфеты с вафельной крошкой 125гр" ] }, "paymentType": 4 } ], "nds10": 1681, "nds18": 950, "region": "64", "userInn": "7825706086", "dateTime": 1638813240, "kktRegId": "0003242677026901", "operator": "Cнегур Юлия Андреевна, Продавец-каccир", "totalSum": 24195, "creditSum": 0, "numberKkt": "00106906199406", "fiscalSign": 311934807, "prepaidSum": 0, "operatorInn": "644922545881", "retailPlace": "337G 17122-Пятерочка", "shiftNumber": 140, "cashTotalSum": 0, "provisionSum": 0, "ecashTotalSum": 24195, "operationType": 1, "redefine_mask": 14, "requestNumber": 456, "fiscalDriveNumber": "9280440301382512", "messageFiscalSign": 9.297393879985013e+18, "appliedTaxationType": 1, "fiscalDocumentNumber": 85458, "fiscalDocumentFormatVer": 2 }, "subtype": "receipt", "receiveDate": "2021-12-06T17:15:26Z", "moderation_unique_counts": { "blacklist_project": 4 } }, "sign": "8c9a7c64cd1e2867afa40d0db23dfb3e" }
• Ответ вебхука c ошибкой:
  { "contractor_id": 2, "project_id": 9, "check_id": 54695, "success": false, "error_data": { "error": { "code": 456, "message": "Ошибка hsm. Чек не валиден или любая внутренняя ошибка hsm" }, "add_dt": "14.12.2021 19:52:12" }, "sign": "0286baaeef7f5feb375c5f633379a33b" }

• Возможные ошибки вебхука:
  

  1.{
    "error": {
      "code": 400,
      "message": "Формат отправленных данных некорректен"
    }
  }
  

  2.{
    "error": {
      "code": 455,
      "message": "Не найдены данные в сервисе поиска чека"
    }
  }
  

  3.{
    "error": {
      "code": 456,
      "message": "Ошибка hsm. Чек не валиден или любая внутренняя ошибка hsm"
    }
  }
  

  4.{
    "error": {
      "code": 503,
      "message": "Сервис недоступен"
    }
  }
  

  5.{
    "error": {
      "code": 532,
      "message": "Внутренняя ошибка сервиса получения чеков"
    }
  }
  

  6.{
    "error": {
      "code": 544,
      "message": "Не прошла проверка пара ККТ    +ФН"
    }
  }
  

  7.{
    "error": {
      "code": 545,
      "message": "ККТ в автономном режиме"
    }
  }