API Справочник

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

Base URL: https://yourdomain.com/api

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

• Bearer Token: Для административных запросов.
• X-API-Key: Для публичных запросов (виджеты).
• Webhook Signature: Валидация входящих webhook-запросов.

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

JSON:

{
  "success": true,
  "data": { ... },
  "message": "OK"
}

Webhook API (Входящие данные)

Endpoint: POST /api/webhook/{secret}

Регистрация (register_user)

Создает пользователя.

{
  "action": "register_user",
  "payload": {
    "email": "user@example.com",
    "phone": "+79990000000",
    "first_name": "Иван"
  }
}

Покупка (purchase)

Начисляет бонусы.

{
  "action": "purchase",
  "payload": {
    "user_email": "user@example.com",
    "order_id": "1001",
    "amount": 5000,
    "products": [...]
  }
}

Списание (spend_bonuses)

Уменьшает баланс.

{
  "action": "spend_bonuses",
  "payload": {
    "user_email": "user@example.com",
    "bonuses_amount": 500,
    "order_id": "1002"
  }
}

Отмена (cancel_order)

Откатывает начисление.

{
  "action": "cancel_order",
  "payload": {
    "order_id": "1001"
  }
}

Публичные API

Баланс

GET /api/projects/{projectId}/users/balance Query: email или phone

Промокод

POST /api/projects/{projectId}/promocodes/validate Body: { email, promocode, order_amount }

Админ API

Проекты

• GET /api/projects — Список.
• POST /api/projects — Создание.
• PUT /api/projects/{id} — Обновление.

Пользователи

• GET /api/projects/{id}/users — Поиск и список.
• GET /api/projects/{id}/users/{uid} — Детали.
• POST /api/projects/{id}/users/{uid}/bonuses/add — Начисление.
• POST /api/projects/{id}/users/{uid}/bonuses/subtract — Списание.

Аналитика

• GET /api/projects/{id}/analytics — Полная статистика.
  • Response:
    • stats: Оборот, заказы, средний чек.
    • cohorts: Когортный анализ (Retention).
    • financial: ARPU, LTV, ARPPU.
    • advancedReferralStats: Эффективность реферальной программы.

Лимиты (Rate Limits)

• Webhooks: 1000 RPM
• Public: 100 RPM
• Admin: 500 RPM

Коды ошибок:

• 400: Bad Request
• 401: Unauthorized
• 429: Too Many Requests
• 500: Internal Server Error

SDK

Node.js пример:

const client = new GupilAPI({ apiKey: '...' });
await client.users.getBalance('user@mail.com');