API

Проверка чека

API для получения данных чека по фискальным параметрам.

• Оплата происходит только за первый успешный запрос чека
• Повторные запросы того же чека — бесплатны
• Если баланс отсутствует — запрос не выполняется

Endpoint

POST /api/scan

Авторизация

Передавайте API-ключ в заголовке:

X-API-KEY: your_api_key

Параметры

Все поля являются обязательными:

{
	"fn": "...", // номер фискального накопителя
	"fd": "...", // номер документа
	"fp": "...", // фискальный признак
	"n": "...",  // тип операции
	"s": "...",  // сумма чека (в рублях, формат: 123.45)
	"t": "..."   // дата чека (YYYYMMDDTHHmm или YYYYMMDDTHHmmss)
}

Пример запроса (cURL)

curl -X POST https://prover-chek.ru/api/scan \
-H "X-API-KEY: your_api_key" \
-H "Content-Type: application/json" \
-d '{
	"fn": "1234567890",
	"fd": "12345",
	"fp": "67890",
	"n": "1",
	"t": "20240101T1230",
	"s": "100.50"
}'

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

{
	"success": true,
	"message": "Чек найден",
	"code": "OK",
	"raw": {
		"data": {
			"json": {
				"nds0": null,
				"user": "ООО Агроторг",
				"items": [
					{
						"nds": 1,
						"sum": 8999,
						"name": "Батончик BOUNTY ТРИО - 82,5г",
						"price": 8999,
						"quantity": 1,
						"paymentType": 4,
						"productType": 1,
						"providerInn": null,
						"providerData": null,
						"paymentAgentData": null
					}
				],
				"nds10": null,
				"nds18": 30,
				"ndsNo": null,
				"fnsSite": null,
				"userInn": "7825706086",
				"dateTime": "2026-04-07T07:45:00",
				"kktRegId": "0006558435004306",
				"nds10110": null,
				"nds18118": null,
				"operator": null,
				"totalSum": 17998,
				"creditSum": 0,
				"fiscalSign": "246033475",
				"prepaidSum": 0,
				"receiptCode": null,
				"retailPlace": "8603 2613-Пятерочка+",
				"shiftNumber": 204,
				"buyerAddress": null,
				"cashTotalSum": 0,
				"internetSign": null,
				"provisionSum": 0,
				"taxationType": 1,
				"ecashTotalSum": 179.97999999999996,
				"machineNumber": "0143240006113404",
				"operationType": 1,
				"requestNumber": 9,
				"paymentAgentType": null,
				"amountsReceiptNds": null,
				"fiscalDriveNumber": "7384440900750672",
				"messageFiscalSign": null,
				"retailPlaceAddress": "443001, Самарская область, г.о. Самара, вн.р-н Ленинский, г Самара, ул Молодогвардейская, д. 139",
				"fiscalDocumentNumber": 55491,
				"fiscalDocumentFormatVer": "4"
			}
		}
	},
	"cached": false,
	"request": {
		"fn": "...",
		"fd": "...",
		"fp": "...",
		"n": "...",
		"s": "...",
		"t": "..."
	}
}

• cached — чек получен из базы (без запроса к ФНС)
• raw — нормализованные данные чека
• request — параметры исходного запроса

Ошибки

Авторизация

{
	"code": "API_KEY_REQUIRED", // 401 - API ключ не передан
	"code": "INVALID_API_KEY",  // 403 - неверный API ключ
}

Баланс

{
	"code": "NO_BALANCE" // 402 - недостаточно средств (запрос не выполнен)
}

Параметры

{
	"code": "MISSING_PARAMS", // 422 - не хватает параметров
	"code": "INVALID_CHECK"   // 422 - чек невалидный
}

Ограничения

{
	"code": "TOO_MANY_PARALLEL",  // 429 - слишком много параллельных запросов
	"code": "ALREADY_PROCESSING", // 429 - чек уже обрабатывается
	"code": "ALL_TOKENS_LIMITED", // 429 - лимит токенов исчерпан
	"code": "TOO_MANY_REQUESTS"   // 429 - превышен rate limit
}

Нет данных

{
	"code": "NO_DATA",      // 404 - чек не найден или еще не обработан ФНС
	"code": "CHECK_TOO_OLD" // 404 - чек слишком старый / недоступен
}

Ошибки ФНС

{
	"code": "FNS_HSM_ERROR",        // 502 - ошибка проверки подписи (возможно поддельный чек)
	"code": "FNS_UNKNOWN",          // 502 - неизвестный ответ (внутренняя ошибка ФНС)
	"code": "EMPTY_RESPONSE",       // 500 - нет ответа от ФНС
	"code": "INVALID_FNS_RESPONSE"  // 500 - некорректный ответ ФНС
}

Общие

{
	"code": "REQUEST_FAILED" // 500 - ошибка запроса
}

Особенности

Списание средств

• Списание происходит только при первом получении чека
• Если чек уже запрашивался этим API ключом — повторно не списывается

Ограничение запросов

Для защиты API применяются ограничения:

С API ключом:

• 60 запросов в минуту на ключ
• 120 запросов в минуту на IP
• 1000 запросов в минуту глобально

Без ключа / неверный ключ:

• 10 запросов в минуту на IP

Пример ошибки при превышении лимита:

{
	"success": false,
	"message": "Слишком много запросов",
	"code": "TOO_MANY_REQUESTS",
	"request": {
		"fn": "...",
		"fd": "...",
		"fp": "...",
		"n": "...",
		"s": "...",
		"t": "..."
	}
}

Формат ответа

{
	"success": boolean,
	"message": "string",
	"code": "string",
	"raw": {
		"data": {
			"json": {
				"nds0": number|null,
				"user": "string",
				"items": [
					{
						"nds": number,
						"sum": number,
						"name": "string",
						"price": number,
						"quantity": number,
						"paymentType": number,
						"productType": number,
						"providerInn": "string|null",
						"providerData": "object|null",
						"paymentAgentData": "object|null"
					}
				],
				"nds10": number|null,
				"nds18": number|null,
				"ndsNo": number|null,
				"fnsSite": "string|null",
				"userInn": "string",
				"dateTime": "string (ISO 8601)",
				"kktRegId": "string",
				"nds10110": number|null,
				"nds18118": number|null,
				"operator": "string|null",
				"totalSum": number,
				"creditSum": number,
				"prepaidSum": number,
				"fiscalSign": "string",
				"receiptCode": "string|null",
				"retailPlace": "string",
				"retailPlaceAddress": "string",
				"shiftNumber": number,
				"requestNumber": number,
				"cashTotalSum": number,
				"ecashTotalSum": number,
				"internetSign": number|null,
				"provisionSum": number,
				"taxationType": number,
				"operationType": number,
				"machineNumber": "string",
				"fiscalDriveNumber": "string",
				"fiscalDocumentNumber": number,
				"fiscalDocumentFormatVer": "string",
				"paymentAgentType": number|null,
				"amountsReceiptNds": "object|null",
				"messageFiscalSign": "string|null"
			}
		}
	},
	"cached": boolean,
	"request": {
		"fn": "string",
		"fd": "string",
		"fp": "string",
		"n": "string",
		"s": "string",
		"t": "string"
	}
}