Документация API

REST API для автоматической проверки и валидации чеков Kaspi. Загружайте PDF-чеки, проверяйте подлинность через QR-код и базу Kaspi.

Чеки обрабатываются менее чем за 1 секунду. Скорость обработки зависит от времени ответа платёжной системы. Рекомендуемый timeout для запросов: 10 секунд.

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

Получите API-ключ и отправьте первый запрос за 2 минуты.

1. Получите API-ключ

Запустите Telegram бот — вы получите 10 бесплатных проверок и API-ключ автоматически.

2. Отправьте чек на проверку

# Отправка чека через URL
curl -X POST https://api.proverkacheka.kz/upload \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ваш-api-ключ",
    "file": "https://example.com/receipt.pdf",
    "user_id": "123456789",
    "price": 5000,
    "iin": "123456789012"
  }'

3. Получите результат

{
  "message": "Чек валиден и добавлен в базу данных.",
  "check_number": "QR13973837513",
  "amount": 1000.50,
  "company_name": "ИП АЛИБЕКОВ",
  "payment_method": "с Kaspi Gold"
}

Аутентификация

Все запросы к /upload требуют API-ключ (UUID), который передаётся в теле запроса в поле api_key.

API-ключ привязан к вашему аккаунту с балансом кредитов. Вы можете получить ключ через Telegram бот или запросить у администратора.

Лимиты и ограничения

Загрузка и проверка чека

# Отправка чека через URL на PDF
curl -X POST https://api.proverkacheka.kz/upload \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "550e8400-e29b-41d4-a716-446655440000",
    "file": "https://example.com/receipt.pdf",
    "user_id": "123456789",
    "price": 5000,
    "ip_name": "ИП АЛИБЕКОВ",
    "iin": "123456789012"
  }'

# Отправка PDF файлом напрямую
curl -X POST https://api.proverkacheka.kz/upload \
  -F "api_key=550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@/path/to/receipt.pdf" \
  -F "user_id=123456789" \
  -F "price=5000" \
  -F "ip_name=ИП АЛИБЕКОВ" \
  -F "iin=123456789012"

# Проверка с валидацией ИИН продавца (ip_name не нужен)
curl -X POST https://api.proverkacheka.kz/upload \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "550e8400-e29b-41d4-a716-446655440000",
    "file": "https://example.com/receipt.pdf",
    "user_id": "123456789",
    "price": 5000,
    "iin": "123456789012"
  }'

// 200 OK
{
  "message": "Чек валиден и добавлен в базу данных.",
  "check_number": "QR13973837513",
  "amount": 1000.50,
  "company_name": "ИП АЛИБЕКОВ",
  "payment_method": "с Kaspi Gold",
  "balance": null,
  "due": null
}

// 200 OK — чек уже был обработан ранее
{
  "message": "Чек уже обработан ранее.",
  "check_number": "QR13973837513",
  "amount": 1000.50,
  "company_name": "ИП АЛИБЕКОВ",
  "previous_user_id": "123456789",
  "payment_method": "с Kaspi Gold"
}

// 200 OK — use_balance: true, сумма < price
{
  "message": "Баланс пополнен",
  "check_number": "QR13973837513",
  "amount": 500.00,
  "company_name": "ИП АЛИБЕКОВ",
  "balance": 500.00,
  "due": 500.00,
  "payment_method": "с Kaspi Gold"
}

Система кредитов

Каждый успешный запрос на проверку чека расходует 1 кредит. Кредиты действительны 30 дней с момента последнего пополнения.

Как это работает

• При пополнении кредитов обновляется дата подписки
• Через 30 дней после последнего пополнения кредиты автоматически сбрасываются до 0
• При недостаточном количестве кредитов возвращается ошибка 402
• Дубликаты чеков не расходуют кредиты

Накопление баланса

Режим накопления позволяет принимать частичные оплаты. Включается параметром use_balance: true в запросе /upload.

Логика работы

• Каждый чек добавляет свою сумму к балансу пользователя
• Пока сумма баланса < price, ответ содержит текущий balance и оставшуюся сумму due
• Когда сумма баланса ≥ price, оплата считается завершённой
• Баланс привязан к конкретному user_id и api_key

Пример сценария

// price = 10000

// Чек #1 — 6000 тенге
{ "balance": 6000, "due": 4000 }

// Чек #2 — 4000 тенге, оплата завершена
{ "balance": 10000, "due": 0 }

ИИН/БИН валидация

Самый надёжный способ валидации. Используйте ИИН/БИН вместо имени продавца (ip_name) — это гарантирует точную идентификацию. Имена ИП/ТОО могут совпадать у разных продавцов, и чек другой организации с таким же названием пройдёт проверку по ip_name. ИИН/БИН уникален для каждого продавца, поэтому подмена исключена.

Как использовать

• Передайте параметр iin (12 цифр) в запросе
• Параметр ip_name становится необязательным
• Система извлекает ИИН/БИН продавца из данных Kaspi и сравнивает с переданным
• Имя продавца автоматически берётся из ответа Kaspi API

Лучшие практики для Telegram-ботов

Рекомендации по обработке платежных чеков в Telegram-ботах, основанные на реальном опыте интеграций.

Состояние ожидания чека

После отправки пользователю ссылки на оплату Kaspi, установите флаг/состояние «ожидание чека» для этого пользователя:

• Держите состояние активным до подтверждения оплаты или отмены — пользователь может оплатить спустя часы
• Обрабатывайте PDF в любой момент, пока состояние активно, а не только сразу после отправки ссылки
• После успешной валидации: сбросьте состояние и прекратите приём PDF для этого платежа

Управление ссылками на оплату

Сохраняйте message_id сообщения со ссылкой на оплату Kaspi:

• После успешной оплаты: удалите или отредактируйте сообщение со ссылкой, чтобы пользователь не кликнул повторно
• Перед отправкой ссылки: проверяйте, что товар/услуга ещё доступны
• Пользователь может нажать старую ссылку через дни — валидируйте актуальность предложения на сервере
• Если предложение истекло: покажите дружелюбное сообщение (это избавит от ручных возвратов)

Обработка PDF вне контекста

Пользователи отправляют PDF на любом экране бота — не игнорируйте их:

• Реализуйте catch-all обработчик PDF, который маршрутизирует по состоянию аккаунта
• Приоритет: ожидание оплаты → платёжный чек; активный аккаунт → обычная проверка
• Всегда отвечайте на PDF — никогда не «проглатывайте» документ молча

Коды ошибок

Сообщения валидации (200 OK)

Следующие сообщения возвращаются с кодом 200 и означают проблему с самим чеком, а не с запросом:

Встраиваемый виджет BETA

Добавьте проверку чеков на ваш сайт одной строкой HTML. Виджет использует HMAC-подписанные токены — параметры проверки (цена, продавец, срок) зашиты в токен и не могут быть изменены пользователем.

<div data-proverkacheka-widget
     data-api-key="ВАШ_API_KEY"
     data-token="СГЕНЕРИРОВАННЫЙ_ТОКЕН"
     data-user-id="order-123"></div>
<script src="https://api.proverkacheka.kz/widget.js"></script>

Атрибуты

Генерация токена

Токен генерируется на вашем сервере с использованием вашего API ключа как секрета HMAC. Формат: base64url(JSON).hmac_sha256_hex

Параметры токена (JSON)

Python

import hmac, hashlib, base64, json, time

def generate_token(params, api_key):
    payload = base64.urlsafe_b64encode(
        json.dumps(params).encode()
    ).rstrip(b'=').decode()
    signature = hmac.new(
        api_key.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()
    return f"{payload}.{signature}"

token = generate_token({
    "price": 5000,
    "iin": "123456789012",
    "max_age": 7,
    "exp": int(time.time()) + 3600  # 1 час
}, "ВАШ_API_KEY")

Node.js

const crypto = require('crypto');

function generateToken(params, apiKey) {
  const payload = Buffer.from(JSON.stringify(params))
    .toString('base64url');
  const signature = crypto
    .createHmac('sha256', apiKey)
    .update(payload)
    .digest('hex');
  return `${payload}.${signature}`;
}

const token = generateToken({
  price: 5000,
  iin: '123456789012',
  max_age: 7,
  exp: Math.floor(Date.now() / 1000) + 3600
}, 'ВАШ_API_KEY');

PHP

function generateToken(array $params, string $apiKey): string {
    $payload = rtrim(strtr(base64_encode(
        json_encode($params)
    ), '+/', '-_'), '=');
    $signature = hash_hmac('sha256', $payload, $apiKey);
    return "{$payload}.{$signature}";
}

$token = generateToken([
    'price' => 5000,
    'iin' => '123456789012',
    'max_age' => 7,
    'exp' => time() + 3600,
], 'ВАШ_API_KEY');

Kommo CRM виджет

Виджет для автоматизации приёма оплаты через Kaspi в Kommo CRM. Проверка чеков, валидация суммы и продавца, автоматическое продвижение сделок по воронке — всё без участия менеджера.

Возможности

• Проверка чеков Kaspi прямо из карточки сделки
• Автоматическая валидация суммы, продавца и срока давности
• Результат проверки сохраняется в примечаниях сделки
• Автоматизация приёма оплаты — настройте воронки в Kommo, чтобы сделки автоматически двигались по этапам после подтверждения оплаты

Заказать установку

Для подключения виджета к вашему Kommo аккаунту свяжитесь с нами:

Напишите в Telegram — обсудим детали и настроим виджет под ваш аккаунт.