Быстрый старт
API принимает чек участника, проверяет его в ФНС и по правилам акции и сообщает результат. Все запросы идут на https://api.apmcheck.ru по HTTPS, данные — JSON в кодировке UTF-8.
- Получите ключ API у менеджера APMcheck. Ключ привязан к одной акции.
- Отправьте чек одним из трёх способов: строкой QR-кода, файлами фото или ссылками на фото. В ответ придёт
uuid— идентификатор чека в APMcheck. - Получайте статус на свой сервер. Сообщите менеджеру адрес коллбека: APMcheck пришлёт туда события «чек получен», «чек найден в ФНС» и итоговый результат.
- Или запрашивайте результат сами по
uuid, если коллбеки не нужны.
Обычно чек проверяется автоматически за десятки секунд. Если чек отправлен на ручную проверку модератором, результат может прийти позже.
Ключ API
Ключ передаётся в заголовке api-key каждого запроса:
api-key: ВАШ_КЛЮЧ_API
- Ключ API — для запросов с вашего сервера. Храните его только на сервере и не публикуйте в коде страниц.
- Ключ виджета — отдельный ключ той же акции для виджета на сайте. Он виден в коде страницы, поэтому через него можно только отправлять чеки.
Неверный или отсутствующий ключ — ответ 401 с кодом ошибки 0002-0008. Чтобы выпустить или заменить ключ, напишите на contact@apmcheck.ru.
Отправить чек по 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"
}'
Отправить чек по фото
Запрос 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"
Отправить чек по ссылкам на фото
Если фото уже лежат у вас на сервере или в хранилище, передайте ссылки — 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.
Получить результат проверки
Возвращает текущий результат по 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 | Когда | approved | rejectKey |
|---|---|---|---|
ARRIVED | Чек сохранён в APMcheck, проверка началась | false | null |
INSPECTED | Чек проверен в ФНС: найден — rejectKey пуст; не найден или не подходит по дате — заполнен | false | null или ключ |
REVIEWED | Итоговое решение | true или false | null или ключ |
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 на REVIEWED | APMcheck считает, что вы не получили 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 | Чек и акция |
disputeStatus | TODO — создан, IN_PROGRESS — в работе, DONE — решён, CLOSED — закрыт |
disputeTitle, disputeQuestion | Тема и текст обращения |
{
"receiptUuid": "6f1c2a8e-3b4d-4f5a-9c7e-1d2e3f4a5b6c",
"receiptId": 24105517,
"promoId": 812,
"disputeStatus": "IN_PROGRESS",
"disputeTitle": "Чек отклонён неверно",
"disputeQuestion": "В чеке есть акционный товар, проверьте, пожалуйста"
}
Актуальное решение по чеку после спора всегда можно получить запросом по uuid.
Выплаты призов
Для акций с денежными призами APMcheck сообщает о выплате на адрес для выплат:
| Поле | Описание |
|---|---|
id | Номер приза |
state | PAID — выплачен, IN PROGRESS — в работе, NON PAID — не выплачен, ERROR — ошибка, CANCELED — отменён |
paid | true, если выплачен |
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. Сообщения участникам формулируйте на своей стороне.
code | HTTP | Что случилось |
|---|---|---|
0002-0008 | 401 | Ключ API неверный или не передан |
0002-0002 | 400 | Неверное значение параметра — какого, указано в localizedDescription (например, photos: нет файлов или их больше 5) |
0002-0003 | 400 | Не удалось разобрать запрос или строку QR-кода |
0002-0013 | 400 | Файл не является изображением или PDF |
0002-0015 | 400 | Файл больше 20 МБ |
0002-0017 | 400 | Слишком частая отправка: участник отправляет чеки быстрее, чем разрешено в акции |
0002-0014 | 400 | Участник исчерпал лимит чеков в день |
0002-0022 | 400 | Участник исчерпал лимит чеков в неделю |
0002-0023 | 400 | Участник исчерпал лимит чеков за акцию |
0002-0018 | 400 | Участник исчерпал дневной лимит отклонённых чеков |
0002-0001 | 400 | Чек с таким uuid не найден |
PHOTO_STORAGE_UNAVAILABLE | 503 | Хранилище фото временно недоступно, чек не принят — отправьте повторно |
0002-0004, 0002-0005 | 500 | Внутренняя ошибка — повторите запрос; если повторяется, напишите в поддержку с 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, результат — теми же коллбеками. Подробную настройку под дизайн сайта пришлёт менеджер.
Проверка доступности
Без ключа. Отвечает 200 и {"status":"ok"}, если API работает. Подходит для мониторинга.
Вопросы по интеграции — contact@apmcheck.ru. Укажите номер акции, а для вопросов по конкретному чеку — его receiptId или uuid.