Partner API ApiPay

POST /api/partner/organizations — создать организацию мерчанта

Идемпотентно по external_id — повторный POST вернёт существующую org. Лимит 10/min. Ответ 201 (создана) / 200 (идемпотентный повтор).

curl -X POST https://api.apipay.kz/api/partner/organizations \
  -H 'X-Partner-Key: <X-Partner-Key>' -H 'Content-Type: application/json' \
  -d '{"has_catalog":false,"external_id":"crm-client-42"}'

{ "success": true, "organization": {
  "id": 50, "name": "ТОО Example", "idn": "123456789012",
  "status": "verified", "sandbox_mode": true, "has_catalog": false,
  "kaspi_connected": true, "session_mode": "self", "external_id": "crm-client-42",
  "origin": "created", "payment_status": "active", "has_active_payment": true,
  "created_at": "2026-05-16T10:00:00+05:00" } }

Опциональное поле name (max 255): пусто → автоген PARTNER_<id>_<ts>, позже подменяется именем из Kaspi на verify-otp.

GET /api/partner/organizations — список организаций (мониторинг)

Мониторинг своих организаций: список с пагинацией. В карточке есть origin. Query: per_page (1–100, def 25), page (def 1), status (pending|verified|suspended), sandbox_mode (true/false/1/0), search (LIKE-поиск по name / external_id / idn, max 255). Фильтры применяются до пагинации. Ключ data — алиас organizations (back-compat).

{ "success": true, "organizations": ["<card>"], "data": ["<card>"],
  "current_page": 1, "per_page": 25, "total": 42, "last_page": 2 }

GET /api/partner/organizations/{id} — карточка организации

Получить карточку конкретной организации. → { "success": true, "organization": <card> }

DELETE /api/partner/organizations/{id} — отвязать организацию

Деактивирует все API-ключи org и делает soft-delete. → { "success": true }

POST /api/partner/organizations/{id}/api-key — выдать X-API-Key мерчанту

Создать/перегенерировать ключ мерчанта + webhook. webhook_url проходит SSRF-валидацию (приватные IP → 422). Идемпотентно (повтор = перегенерация). Дальше мерчант работает этим ключом по документации для мерчантов (/docs).

curl -X POST https://api.apipay.kz/api/partner/organizations/501/api-key \
  -H 'X-Partner-Key: <X-Partner-Key>' -H 'Content-Type: application/json' \
  -d '{"name":"CRM key","webhook_url":"https://crm.example.kz/sub/501/webhook"}'

{ "success": true, "key": "<X-API-Key, один раз>", "key_id": 900,
  "webhook_url": "https://crm.example.kz/sub/501/webhook",
  "webhook_secret": "whsec_yyyy", "is_org_default": true, "regenerated": false }

POST .../kaspi-auth/init — Шаг 1

Инициировать авторизацию кассира Kaspi. Body {} (опц. { "force": true }). force: true — переавторизация поверх активной сессии (смена кассира). Без force по уже подключённой org → 409 already_connected.

{ "success": true, "process_id": "SANDBOX-<uuid>", "process_status": "phone_required" }

POST .../kaspi-auth/send-phone — Шаг 2

Body { "cashier_phone": "7XXXXXXXXXX" }. Kaspi отправляет SMS на номер кассира. Успех → { "success": true, "process_status": "otp_required" }.

Ошибки: invalid_phone (422 — неверный формат), not_cashier (422 — номер не «чистый кассир»), not_registered (422 — не зарегистрирован кассиром в Kaspi), no_process (409 — нет активного процесса: вызовите init / он истёк), context_expired (409 — Kaspi-контекст протух, ~10 мин: init заново + повтор send-phone), org_claim_conflict (409 — касса уже привязана к другому владельцу), sms_failed (502), kaspi_busy (503 — Kaspi недоступен; заголовок Retry-After: 60). В sandbox not_cashier / sms_failed / not_registered / context_expired / kaspi_busy эмулируются магическими номерами (см. раздел Sandbox).

POST .../kaspi-auth/verify-otp — Шаг 3

Body { "otp": "0000" } (4–6 цифр). Подтвердить код из SMS.

• Успех 200: { "success": true, "mode": "self", "organization": <card>, "process_status": "active" } — org → status: verified.
• Неверный код 200: { "success": false, "error": "invalid_otp", "process_status": "otp_required" } — повторяемо, сессия жива.
• org_claim_conflict (409): Kaspi-кассир/организация уже привязаны к другой организации в ApiPay.
• В sandbox код 0000 = успех, любой другой = invalid_otp.

GET .../kaspi-auth/status — статус

Текущий статус авторизации кассира. status: none | pending | active | expired. process_status: idle | phone_required | otp_required | active | failed (выводится из persisted-сессии).

{ "success": true, "status": "active", "process_status": "active",
  "kaspi_connected": true, "expires_at": "2026-06-16T00:00:00+05:00" }

GET /api/partner/tariff-plans — каталог тарифов

Общий каталог (без привязки к орг): 3 тарифа + 12 планов (3 × 1/3/6/12 мес). → { "success": true, "tiers": [...], "plans": [...] }

GET /api/partner/organizations/{id}/tariff — статус подписки мерчанта

Снимок подписки. Нет тарифа → status: "none" (не 404). next_payment.amount — всегда.

{ "success": true, "tariff": {
  "status": "none|trial|active|expired", "tier": "business", "is_trial": false,
  "started_at": "2026-06-20T10:00:00+05:00", "expires_at": "2026-09-20T10:00:00+05:00",
  "days_remaining": 92, "auto_renew": false,
  "last_payment": { "amount": 71250, "paid_at": "...", "period_months": 3, "tier": "business", "status": "completed" },
  "next_payment": { "due_at": "2026-09-20T10:00:00+05:00", "amount": 71250, "tier": "business" } } }

POST /api/partner/organizations/{id}/tariff/pay — оплатить тариф

Body: { "tier_id": "business", "period_months": 3, "phone": "8XXXXXXXXXX", "set_billing_phone": false } (phone — плательщик, формат 8XXXXXXXXXX; НЕ кассир). Боевая org — только production-партнёру (иначе 403 production_access_required); тестовая → мгновенная мок-активация (201, status:"completed", self_api_invoice_id:null).

{ "success": true, "payment": {
  "id": 42, "amount": 71250, "status": "pending", "tier": "business", "period_months": 3,
  "self_api_invoice_id": 778899, "external_id": "partner-tariff-501-1716900000",
  "paid_at": null, "expires_at": null, "created_at": "2026-06-20T10:00:00+05:00", "failure_reason": null } }

Ошибки: 403 production_access_required, 404 organization_not_found, 409 tariff_payment_pending (в теле — существующий payment), 422 invalid_tariff_plan, 429 tariff_payment_cooldown (+Retry-After, retry_after_seconds:1800), 503 tariff_payment_unavailable (+Retry-After, retry_after_seconds:30).

GET /api/partner/organizations/{id}/tariff/payments и /{paymentId}

Список: { "success": true, "data": [ <payment> ] } (по убыванию даты, триальные amount=0 исключены). Один: { "success": true, "payment": <payment> }; неизвестный paymentId → 404 tariff_payment_not_found. <payment>: { id, amount, status, tier, period_months, self_api_invoice_id, external_id, paid_at, expires_at, created_at, failure_reason }.

GET /api/partner/health — health аккаунта партнёра

Агрегат по всем орг (без proxy-деталей), кэш ~30с.

{ "success": true, "api": {"status":"ok"},
  "organizations": {"total":12,"kaspi_connected":9,"needs_reauth":1,"tariff_active":7,"tariff_expired":2,"on_trial":3},
  "webhooks": {"delivered_24h":340,"failed_24h":5,"success_rate":98.6},
  "rate_limits": {"partner_api_per_min":120} }