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

Документация Telegram Mini App, API и webhooks программы лояльности LoyalPlus.

Подключение бота и Mini App

Получите bot token в BotFather.
Настройте команды и описание бота.
Добавьте ярлыки Mini App и задайте URL интеграции.

Webhooks

Подпишитесь на события покупки, визита и награды. Формат payload содержит идентификаторы клиента, сумму чека и событие.

POST /webhooks/loyalty
{
  "event": "purchase",
  "customer_id": "12345",
  "amount": 890,
  "timestamp": "2024-08-01T10:00:00Z"
}

API интеграций

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

curl -X POST https://api.loyalplus.ru/v1/stamps
  -H "Authorization: Bearer YOUR_TOKEN"
  -H "Content-Type: application/json"
  -d '{"customer_id": "12345", "count": 1}'

Примеры кода

import requests

payload = {"customer_id": "12345", "count": 1}
requests.post(
    "https://api.loyalplus.ru/v1/stamps",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json=payload,
    timeout=10,
)

FAQ

Что такое webhook? Это событие, которое система отправляет на ваш сервер.

Нужен ли HTTPS? Да, для безопасного приема событий.

Можно ли использовать свою CRM? Да, через API и webhooks.

Безопасность и рекомендации

Рекомендуем хранить API‑ключи в переменных окружения и ограничивать доступ к endpoint‑ам. Для верификации запросов используйте подписи или IP‑белые списки. Это снижает риск несанкционированных начислений.

При высокой нагрузке используйте очередь задач для обработки webhooks. Это помогает избежать потери событий и сохраняет точность начислений.

Связанные разделы

Если вы подключаете кассу, ознакомьтесь с разделом интеграции и страницей API и Webhooks. Для бизнес‑сценариев полезны страницы штамп‑карта и купоны.

Процесс запуска программы описан в разделе как это работает, а доступ к расширенным возможностям зависит от тарифов.

Ошибки и коды ответов

Если запрос не прошел, проверьте статус ответа и тело ошибки. Типичные причины: неверный токен, неправильный идентификатор клиента, отсутствие прав для метода. Рекомендуем логировать запросы и ответы для быстрой диагностики.

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

Ссылки на GitHub/SDK

Если у вас есть репозиторий, добавьте ссылку и подпишитесь на обновления. Также смотрите страницы штампов и купонов. Процесс запуска описан в как это работает, а доступ к API зависит от тарифов.