API для интеграции — APMcheck

Главная → API

Документация для разработчиков

API APMcheck для интеграции

Как отправлять чеки участников на проверку, получать результат и принимать уведомления о статусе чека на своём сервере. Для промо-сайтов, чат-ботов и мобильных приложений.

Версия документа: 28.10.2026 · Базовый адрес: https://api.apmcheck.ru

Быстрый старт

API принимает чек участника, проверяет его в ФНС и по правилам акции и сообщает результат. Все запросы идут на https://api.apmcheck.ru по HTTPS, данные — JSON в кодировке UTF-8.

  1. Получите ключ API у менеджера APMcheck. Ключ привязан к одной акции.
  2. Отправьте чек одним из трёх способов: строкой QR-кода, файлами фото или ссылками на фото. В ответ придёт uuid — идентификатор чека в APMcheck.
  3. Получайте статус на свой сервер. Сообщите менеджеру адрес коллбека: APMcheck пришлёт туда события «чек получен», «чек найден в ФНС» и итоговый результат.
  4. Или запрашивайте результат сами по uuid, если коллбеки не нужны.

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

Ключ API

Ключ передаётся в заголовке api-key каждого запроса:

api-key: ВАШ_КЛЮЧ_API
  • Ключ API — для запросов с вашего сервера. Храните его только на сервере и не публикуйте в коде страниц.
  • Ключ виджета — отдельный ключ той же акции для виджета на сайте. Он виден в коде страницы, поэтому через него можно только отправлять чеки.

Неверный или отсутствующий ключ — ответ 401 с кодом ошибки 0002-0008. Чтобы выпустить или заменить ключ, напишите на contact@apmcheck.ru.

Отправить чек по QR-коду

POST/api/receipts/qr

Самый быстрый способ: передать строку из QR-кода чека. Фото не нужно. Тело запроса — JSON.

ПолеТипОписание
qrStrстрокаОбязательно. Строка из QR-кода чека, например t=20261023T1830&s=349.00&fn=7380440700076549&i=41397&fp=2857024131&n=1
userUuidстрокаОбязательно. Идентификатор участника в вашей системе
externalIdчислоИдентификатор чека в вашей системе
metaстрокаВаши данные о чеке — JSON, упакованный в строку. Вернутся в результате
channelстрокаКанал, откуда пришёл чек. По умолчанию api
configстрокаНастройки проверки этого чека — JSON в строке. Используйте, только если согласовали с менеджером

Поля строки QR-кода:

ПолеЗначение
tдата и время покупки, ГГГГММДДTЧЧММ или ГГГГММДДTЧЧММСС
sсумма чека в рублях
fnномер фискального накопителя (ФН)
iномер фискального документа (ФД)
fpфискальный признак документа (ФП, ФПД)
nпризнак расчёта: 1 — приход
curl -X POST https://api.apmcheck.ru/api/receipts/qr \
  -H "api-key: ВАШ_КЛЮЧ_API" \
  -H "Content-Type: application/json" \
  -d '{
    "qrStr": "t=20261023T1830&s=349.00&fn=7380440700076549&i=41397&fp=2857024131&n=1",
    "userUuid": "user-12345",
    "externalId": 98765,
    "meta": "{\"utm_source\":\"promo-site\"}",
    "channel": "web"
  }'

Отправить чек по фото

POST/api/receipts

Запрос multipart/form-data: файлы фото и поля формы.

ПолеТипОписание
photosфайлыОбязательно. От 1 до 5 файлов, каждый до 20 МБ. JPEG, PNG, GIF, TIFF или PDF (PDF разбивается на страницы). Длинный чек можно снять несколькими частями
userUuidстрокаОбязательно. Идентификатор участника
externalId, meta, channel, configКак в отправке по QR-коду

По фото APMcheck сам находит QR-код или реквизиты чека и проверяет его в ФНС.

curl -X POST https://api.apmcheck.ru/api/receipts \
  -H "api-key: ВАШ_КЛЮЧ_API" \
  -F "photos=@receipt-top.jpg" \
  -F "photos=@receipt-bottom.jpg" \
  -F "userUuid=user-12345" \
  -F "externalId=98765"

Отправить чек по ссылкам на фото

POST/api/receipts/url

Если фото уже лежат у вас на сервере или в хранилище, передайте ссылки — APMcheck скачает файлы сам. Параметры те же, что у отправки по фото, только в photos — публичные ссылки (до 5). Ссылки должны открываться из интернета без авторизации; адреса внутренних сетей не принимаются.

curl -X POST https://api.apmcheck.ru/api/receipts/url \
  -H "api-key: ВАШ_КЛЮЧ_API" \
  --data-urlencode "photos=https://cdn.example.ru/receipts/98765-1.jpg" \
  --data-urlencode "userUuid=user-12345" \
  --data-urlencode "externalId=98765"

Общие параметры

  • userUuid — по нему APMcheck считает лимиты на участника (сколько чеков в день, в неделю, за акцию) и возвращает его в результате.
  • externalId — ваш номер чека. Вернётся в результате и в коллбеках. Если для акции включена уникальность, повторная отправка тех же файлов с тем же externalId вернёт 409.
  • meta — любой JSON-объект, упакованный в строку. APMcheck сохранит его и добавит поле channel. Удобно передавать UTM-метки, номер заказа, версию приложения.
  • channel — откуда пришёл чек: web, telegram, wapp, cbot_vk, sms и т.д. Используется в аналитике акции.

Ответ на отправку

Чек принят в обработку — 200:

{
  "status": "success",
  "uuid": "6f1c2a8e-3b4d-4f5a-9c7e-1d2e3f4a5b6c"
}

Сохраните uuid: по нему запрашивается результат, он же приходит в коллбеках.

КодЧто значитЧто делать
200Чек принят, проверка началасьЖдать коллбека или запрашивать результат
400Ошибка в запросе или сработал лимит участникаСмотреть code в теле ошибки
401Неверный ключПроверить ключ
409Этот чек уже отправляли (при включённой уникальности externalId)Взять existing_request_uuid из ответа — это uuid первой отправки
503Чек не принят: сервис не успел его принять или временно не смог сохранить фотоОтправить тот же запрос повторно — см. ниже
HTTP/1.1 409 Conflict
{
  "status": "failure",
  "existing_request_uuid": "6f1c2a8e-3b4d-4f5a-9c7e-1d2e3f4a5b6c"
}

Ответ 503: чек не принят, отправьте повторно

APMcheck принимает чек только после того, как сохранил его фото. Если хранилище фото временно не отвечает, чек не сохраняется и uuid не выдаётся:

HTTP/1.1 503 Service Unavailable
{
  "status": "failure",
  "code": "PHOTO_STORAGE_UNAVAILABLE",
  "userFacingMessage": "Не удалось сохранить фото чека. Отправьте чек ещё раз через минуту."
}

Тот же код 503 без поля code (только "status": "failure") означает, что сервис не успел принять чек за 10 секунд. Действовать в обоих случаях одинаково:

  • Повторите тот же запрос с теми же файлами и externalId, например через 5, 15 и 60 секунд, затем раз в минуту в течение 10 минут. Чек не принят, поэтому повторная отправка не создаст дубль и не вернёт 409.
  • Если участник ждёт ответа на экране, покажите ему userFacingMessage или свой текст с просьбой отправить чек позже.
  • Не считайте 503 отказом по чеку: решения по нему нет, коллбеков по нему не будет.

Добавление фото к уже принятому чеку при недоступном хранилище отвечает так же — 503 с кодом PHOTO_STORAGE_UNAVAILABLE.

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

GET/api/receipts/{uuid}

Возвращает текущий результат по uuid из ответа на отправку. Ключ должен принадлежать той же акции, что и чек.

curl https://api.apmcheck.ru/api/receipts/6f1c2a8e-3b4d-4f5a-9c7e-1d2e3f4a5b6c \
  -H "api-key: ВАШ_КЛЮЧ_API"

Пока проверка не закончена:

{ "message": "The receipt is not checked yet" }

Когда есть решение — объект результата. Если вы получаете результат коллбеком, опрашивать не нужно. Если опрашиваете — не чаще раза в 10–15 секунд на чек.

Объект результата

Один и тот же формат приходит в ответе на GET /api/receipts/{uuid} и в коллбеке с итоговым результатом.

ПолеТипОписание
stateстрокаЭтап: ARRIVED, INSPECTED или REVIEWED (итог). См. события
approvedбулевоtrue — чек принят, false — отклонён (в итоговом результате)
rejectKeyстрокаКлюч причины отказа — для логики вашей системы. Список ключей
rejectReasonстрокаТекст причины для участника. Может меняться, на него не опирайтесь в коде
uuidстрокаИдентификатор чека в APMcheck
receiptIdчислоНомер чека в APMcheck — его называйте в обращениях в поддержку
userUuidстрокаУчастник, переданный при отправке
promoIdчислоНомер акции
receiptDateстрокаДата и время покупки по чеку
createdAtстрокаКогда чек получен APMcheck, ISO 8601 в UTC
retailerобъектПродавец: id, name (сеть), inn, store и storeId (магазин)
cityобъектМесто покупки: id, city, region, address
totalобъектИтоги по чеку: sum — сумма чека, count — количество акционных товаров, sum_subtotal — сумма акционных товаров
answersобъектЧто найдено в чеке по условиям акции: акционные товары с количеством, бренды и т.д. Состав зависит от настроек акции
rules, rulesCount, rulesPointsРезультат правил начисления, если они настроены в акции
promoPointsобъектБаллы участника, если акция балльная: earned — за этот чек, totalEarned — всего, leftovers — остаток
duplicateобъектЕсли чек — дубль ранее отправленного: id, promoId, external_id первого чека и его статус
matchedPromosмассивДругие акции, под условия которых подходит чек: id, name, meta
fnsReceiptобъектДанные чека из ФНС: позиции, суммы, реквизиты. Очень большие чеки приходят без этого поля
qrStringстрокаСтрока QR-кода чека
photosмассивСсылки на фото чека
source, channelстрокаОткуда пришёл чек: api, widget, канал из запроса
metaобъектВаши данные из meta при отправке

Пример итогового результата — чек принят:

{
  "state": "REVIEWED",
  "uuid": "6f1c2a8e-3b4d-4f5a-9c7e-1d2e3f4a5b6c",
  "receiptId": 24105517,
  "userUuid": "user-12345",
  "promoId": 812,
  "approved": true,
  "rejectKey": null,
  "rejectReason": null,
  "receiptDate": "2026-10-23T18:30:00",
  "createdAt": "2026-10-23T15:31:12Z",
  "retailer": { "id": 17, "name": "Пятёрочка", "inn": "7825706086", "store": "Пятёрочка", "storeId": 5531 },
  "city": { "id": 1, "city": "Москва", "region": "Москва", "address": "ул. Примерная, 1" },
  "total": { "sum": 349.0, "count": 2, "sum_subtotal": 198.0 },
  "answers": { "products_with_count": [ { "id": 8, "name": "Йогурт питьевой 270 г", "count": 2 } ] },
  "promoPoints": { "earned": 2, "totalEarned": 6, "leftovers": 0.0, "leftoversInt": 0 },
  "duplicate": null,
  "matchedPromos": null,
  "qrString": "t=20261023T1830&s=349.00&fn=7380440700076549&i=41397&fp=2857024131&n=1",
  "photos": [],
  "source": "api",
  "channel": "web",
  "meta": { "utm_source": "promo-site", "channel": "web" }
}

Чек отклонён:

{
  "state": "REVIEWED",
  "uuid": "6f1c2a8e-3b4d-4f5a-9c7e-1d2e3f4a5b6c",
  "receiptId": 24105517,
  "approved": false,
  "rejectKey": "OUTSIDE_INTERVAL",
  "rejectReason": "Дата чека не соответствует условиям Акции",
  ...
}

Коллбеки

Коллбек — запрос, который APMcheck отправляет на ваш сервер, когда у чека меняется статус. Адрес, HTTP-метод (обычно POST) и заголовки (например, ваш токен авторизации) задаются в настройках акции — сообщите их менеджеру. Тело — JSON.

Для чеков, споров и выплат можно указать разные адреса.

События чека

Все события чека приходят на один адрес. Тип события — в поле state.

stateКогдаapprovedrejectKey
ARRIVEDЧек сохранён в APMcheck, проверка началасьfalsenull
INSPECTEDЧек проверен в ФНС: найден — rejectKey пуст; не найден или не подходит по дате — заполненfalsenull или ключ
REVIEWEDИтоговое решениеtrue или falsenull или ключ

ARRIVED содержит uuid, receiptId, userUuid, promoId, createdAt, photos, source, channel, meta. INSPECTED — то же плюс receiptDate, duplicate, rejectKey, rejectReason. REVIEWED — полный объект результата.

POST https://your-site.ru/apmcheck/callback
Content-Type: application/json
Authorization: Bearer ВАШ_ТОКЕН        ← заголовок из настроек акции

{
  "state": "ARRIVED",
  "uuid": "6f1c2a8e-3b4d-4f5a-9c7e-1d2e3f4a5b6c",
  "receiptId": 24105517,
  "userUuid": "user-12345",
  "promoId": 812,
  "createdAt": "2026-10-23T15:31:12Z",
  "photos": [],
  "source": "api",
  "channel": "web",
  "meta": { "utm_source": "promo-site", "channel": "web" }
}

Обрабатывайте события идемпотентно, по uuid + state: при повторах одно и то же событие может прийти дважды. Итоговым считайте только REVIEWED.

Ответ вашего сервера

APMcheck читает код ответа на коллбек:

Ваш ответЧто делает APMcheck
2xxДоставлено. Если в теле ответа есть externalId (или external_id) и meta, APMcheck сохранит их у чека
5xx, таймаут, нет соединения, 401, 407, 408, 429Сбой на вашей стороне — коллбек будет повторён
404 на REVIEWEDAPMcheck считает, что вы не получили ARRIVED: отправит ARRIVED и сразу повторит результат
403, 422 и другие 4xx на ARRIVED / INSPECTED (кроме перечисленных и 400, 409)Чек отклоняется с ключом BLOCKED_USER — так ваша система может не принять чек от заблокированного участника. На 424 чек отклоняется без отправки результата
Прочие ответы (400, 409, 3xx)Доставка не принята. ARRIVED не повторяется, остальные события — по отдельному короткому графику. Если событие обработано, отвечайте 2xx

Пример ответа, который сохранит ваш номер чека:

HTTP/1.1 200 OK
Content-Type: application/json

{ "externalId": 98765, "meta": { "order": "A-1024" } }

Повторы

  • Итоговый результат (REVIEWED) — до 9 попыток примерно за 44 часа: через 3, 10, 30, 60 минут, 2, 4, 12 и 24 часа после неудачи.
  • Промежуточные события (ARRIVED, INSPECTED) — до 3 попыток за ~15 минут: через 3 и 10 минут. Если к этому времени есть итог, промежуточное событие уже не нужно.

Если ваш сервер был недоступен дольше, результат всегда можно забрать запросом по uuid.

Споры

Если участник оспаривает решение по чеку, на адрес для споров приходят события спора:

ПолеОписание
receiptUuid, receiptId, promoIdЧек и акция
disputeStatusTODO — создан, IN_PROGRESS — в работе, DONE — решён, CLOSED — закрыт
disputeTitle, disputeQuestionТема и текст обращения
{
  "receiptUuid": "6f1c2a8e-3b4d-4f5a-9c7e-1d2e3f4a5b6c",
  "receiptId": 24105517,
  "promoId": 812,
  "disputeStatus": "IN_PROGRESS",
  "disputeTitle": "Чек отклонён неверно",
  "disputeQuestion": "В чеке есть акционный товар, проверьте, пожалуйста"
}

Актуальное решение по чеку после спора всегда можно получить запросом по uuid.

Выплаты призов

Для акций с денежными призами APMcheck сообщает о выплате на адрес для выплат:

ПолеОписание
idНомер приза
statePAID — выплачен, IN PROGRESS — в работе, NON PAID — не выплачен, ERROR — ошибка, CANCELED — отменён
paidtrue, если выплачен
valueСумма приза
user_uuid, phone_numberУчастник и номер телефона, на который шла выплата
promo_id, prize_definition_id, external_idАкция, вид приза, ваш номер
try_countСколько было попыток выплаты
created_at, updated_at, retrieved_atКогда приз создан, изменён, получен

Причины отказа

Ключ rejectKey стабилен — стройте логику на нём. Текст rejectReason предназначен для участника и может уточняться.

rejectKeyПричина
DUPLICATEЭтот чек уже есть в базе
DUPLICATE_PHOTOЭто фото чека уже присылали
MATCHED_IN_OTHER_PROMOЧек уже засчитан в другой акции
OUTSIDE_INTERVAL, EXPIRED, FUTUREДата чека не соответствует условиям акции
FNS_SHORT_CHECK_FAILEDЧек не найден в базе ФНС
AUTO_REJECTЧек отсутствует в ФНС — участнику стоит обратиться в поддержку с фото чека
FNS_QR_MISSINGНе удалось распознать QR-код на фото
NOTARECEIPTНа фото нет чека
UNREADABLEПлохое качество фото, данные не читаются
NOTALLPARTSЧек сфотографирован не полностью
FEWRECEIPTSНа фото больше одного чека
NOT_ALLOWED_RECEIPT_TYPEВ чеке нет обязательных данных (дата, время, сумма, ФН, ФД, ФПД)
MODIFICATIONЧек не может быть проверен — участнику нужно обратиться в поддержку
BRANDSВ чеке нет акционного товара
NOT_QUANTITY_PRODUCTТовары в чеке не соответствуют условиям акции
TOTAL_PRODUCTS_COUNT_MINНедостаточно акционных товаров в чеке
TOTAL_PRODUCTS_PRICE_MINНедостаточная сумма по акционным товарам
PRODUCTS_PRICE_MINЦена единицы товара ниже допустимой
PRODUCTS_PRICE_MAXСумма товаров выше допустимой
REJECT_RULESНедостаточно товаров для начисления приза
INCORRECTSTOREМагазин не участвует в акции
ONLINE_RETAILERЧек онлайн-магазина не подходит для участия
INCORRECTCITYГород не участвует в акции
MAX_RECEIPTS_PER_DATEПревышено число чеков от одной даты покупки
MAX_RECEIPTS_PER_STOREПревышено число чеков из одного магазина
BLOCKED_USERУчастник заблокирован или больше не может отправлять чеки
ERRORОшибка обработки — чек нужно отправить ещё раз

Набор проверок и тексты причин настраиваются под каждую акцию.

Ошибки

При ошибке API возвращает HTTP-код и JSON с кодом ошибки:

HTTP/1.1 401 Unauthorized
{
  "code": "0002-0008",
  "description": "Api-key invalid or absent",
  "localizedDescription": "Invalid api key",
  "uri": "POST https://api.apmcheck.ru/api/receipts/qr",
  "userFacingMessage": "Oops, something went wrong",
  "requestId": null
}

Ориентируйтесь на code. Сообщения участникам формулируйте на своей стороне.

codeHTTPЧто случилось
0002-0008401Ключ API неверный или не передан
0002-0002400Неверное значение параметра — какого, указано в localizedDescription (например, photos: нет файлов или их больше 5)
0002-0003400Не удалось разобрать запрос или строку QR-кода
0002-0013400Файл не является изображением или PDF
0002-0015400Файл больше 20 МБ
0002-0017400Слишком частая отправка: участник отправляет чеки быстрее, чем разрешено в акции
0002-0014400Участник исчерпал лимит чеков в день
0002-0022400Участник исчерпал лимит чеков в неделю
0002-0023400Участник исчерпал лимит чеков за акцию
0002-0018400Участник исчерпал дневной лимит отклонённых чеков
0002-0001400Чек с таким uuid не найден
PHOTO_STORAGE_UNAVAILABLE503Хранилище фото временно недоступно, чек не принят — отправьте повторно
0002-0004, 0002-0005500Внутренняя ошибка — повторите запрос; если повторяется, напишите в поддержку с uri и временем запроса

Лимиты чеков на участника задаются в настройках акции.

Виджет на сайт

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

<link href="https://qr.apmcheck.ru/1.0.8/css/widget.min.css" rel="stylesheet">

<div id="apm-widget"></div>

<script src="https://qr.apmcheck.ru/1.0.8/js/widget-v2.min.js"></script>
<script>
  qrWidgetV2.init('apm-widget', {
    api: 'https://api.apmcheck.ru',
    apiKey: 'КЛЮЧ_ВИДЖЕТА',
    userUuid: 'user-12345',          // участник, вошедший на сайт
    channel: 'web',
    meta: { utm_source: 'promo-site' },
    callbacks: {
      onReceiptSentSuccess: function (res) { /* ответ API на отправку чека */ },
      onReceiptSentError: function (res) { }
    }
  });
</script>

Тексты кнопок и экранов, CSS-классы и размер фото настраиваются. Чеки из виджета приходят с source = widget, результат — теми же коллбеками. Подробную настройку под дизайн сайта пришлёт менеджер.

Проверка доступности

GET/api/health

Без ключа. Отвечает 200 и {"status":"ok"}, если API работает. Подходит для мониторинга.

Вопросы по интеграции — contact@apmcheck.ru. Укажите номер акции, а для вопросов по конкретному чеку — его receiptId или uuid.