Partners (B2B)

Эта секция актуальна для agency API-ключей (sk_live_…, client_type=agency). Каждый ключ привязан к одному partner_id — все endpoints оперируют над своим партнёром ({self}), путь указывается явно.

Базовый префикс: /api/v1/partners/

Кошелёк (wallet)

Авансовый счёт партнёра в одной или нескольких валютах. С него списываются оплаты броней через POST /bookings/{id}/pay-with-balance.

Top-up: пополнение баланса инициируется авиакомпанией, у агентства нет endpoint'а для самостоятельного top-up. Если нужно пополнить — свяжитесь с вашим менеджером в авиакомпании.

GET /{partner_id}/wallet

Один кошелёк (валюта по умолчанию).

curl -H "X-API-Key: $AGENCY_KEY" \
  "https://api.nurcore.kg/api/v1/partners/$PARTNER_ID/wallet"

Response 200:

{
  "id": "wallet-uuid",
  "partner_id": "partner-uuid",
  "currency": "KGS",
  "balance": 125000.00,
  "credit_limit": 0.00,
  "is_active": true,
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-05-28T12:00:00Z",
  "logical_partner_id": null,
  "uses_parent_wallet": false
}

Поле uses_parent_wallet=true означает, что вы — суб-партнёр и оперируете кошельком родительского партнёра (используется в multi-tier агентских сетях).

GET /{partner_id}/wallets

Все кошельки партнёра (для multi-currency agency). Возвращает массив WalletResponse.

curl -H "X-API-Key: $AGENCY_KEY" \
  "https://api.nurcore.kg/api/v1/partners/$PARTNER_ID/wallets"

GET /{partner_id}/wallet/transactions

История операций по кошельку (для сверки балансов и аудита).

Query:

curl -H "X-API-Key: $AGENCY_KEY" \
  "https://api.nurcore.kg/api/v1/partners/$PARTNER_ID/wallet/transactions?\
date_from=2026-05-01&date_to=2026-05-31&currency=KGS"

Response 200:

{
  "data": [
    {
      "id": "tx-uuid",
      "wallet_id": "wallet-uuid",
      "transaction_type": "DEBIT",
      "amount": 4500.00,
      "currency": "KGS",
      "balance_after": 120500.00,
      "related_booking_id": "booking-uuid",
      "description": "Оплата брони ABC123",
      "created_at": "2026-05-28T11:30:00Z"
    }
  ],
  "page": 1,
  "page_size": 50,
  "total": 47
}

Комиссии

Партнёрские комиссии (ставка за бронь / процент от стоимости) настраиваются авиакомпанией. Партнёр может только читать их.

GET /commissions/

Список применимых комиссионных правил.

curl -H "X-API-Key: $AGENCY_KEY" \
  "https://api.nurcore.kg/api/v1/partners/commissions/"

Response 200: массив CommissionResponse — каждый объект содержит commission_name, percentage, fixed_amount, effective_date, expiration_date, applies_to (route/airline/global).

POST /commissions/lookup

Рассчитать комиссию для конкретной брони перед оплатой:

{
  "partner_id": "uuid",
  "route_code": "BSZ-OSS",
  "amount": 4500.00,
  "currency": "KGS"
}

Response 200:

{
  "rule_id": "uuid",
  "rule_name": "Default agency commission",
  "percentage": 10.0,
  "fixed_amount": 0.00,
  "commission_amount": 450.00,
  "currency": "KGS"
}

Это та же сумма, которая будет начислена при pay-with-balance (видна в booking.commission_amount после оплаты).

Партнёрское соглашение

GET /partnerships/

Активные партнёрские соглашения вашего partner_id (agreement_name, effective_date, expiration_date, attached routes, special rates). Read-only.

Sub-partners (если применимо)

Если ваша organization — primary agency, а под вами субподрядчики:

Sub-partners share родительский wallet (uses_parent_wallet=true) или получают свой по запросу.

Ошибки