# Portfel, Płatności i Sklep (Billing & Shop API)

Interfejs programistyczny do zarządzania wirtualnym portfelem wPLN, generowania intencji doładowań płatniczych (Stripe, krypto LTC), przelewów P2P między użytkownikami oraz pobierania aktualnego katalogu produktów ze sklepu.

---

## 1. Saldo portfela i historia transakcji (`/v1/wallet`)

Zwraca bieżące saldo wPLN konta, status użytkownika oraz stronicowaną historię transakcji (doładowania, zakupy, odnowienia, przelewy).

* **Metoda:** `GET`
* **Ścieżka:** `/v1/wallet`
* **Wymagany scope:** `account:read` lub `account:billing`
* **Parametry query (opcjonalne):**
  * `cursor` — ID transakcji jako kursor do paginacji (np. `?cursor=120`)

### Przykład zapytania cURL
```bash
curl -X GET "https://api.blackhost.pl/v1/wallet" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
```

### Przykład odpowiedzi (200 OK)
```json
{
  "success": true,
  "wpln": 150.00,
  "status": "active",
  "transactions": [
    {
      "id": 142,
      "user_id": 12,
      "amount": 50.00,
      "type": "deposit",
      "description": "Doładowanie portfela Stripe",
      "stripe_session_id": "cs_live_a1b2c3...",
      "created_at": "2026-10-30T14:20:00.000Z"
    },
    {
      "id": 141,
      "user_id": 12,
      "amount": -29.00,
      "type": "service_renewal",
      "description": "Odnowienie serwera VPS vps-8f92a1",
      "stripe_session_id": null,
      "created_at": "2026-10-28T10:15:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null,
    "pageSize": 20
  }
}
```

---

## 2. Rozpoczęcie doładowania portfela (`/v1/wallet/topup`)

Inicjalizuje proces doładowania salda konta i zwraca adres przekierowania do płatności lub dane transakcji.

* **Metoda:** `POST`
* **Ścieżka:** `/v1/wallet/topup`
* **Wymagany scope:** `account:billing`
* **Nagłówek:** `Content-Type: application/json`

### Parametry w ciele zapytania:
| Pole | Typ | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `amount` | Liczba | **Tak** | Kwota doładowania w PLN (np. `50.00`, maks. 2 miejsca po przecinku) |
| `provider` | String | Nie | Identyfikator bramki płatności: `stripe` (domyślnie) lub `crypto_ltc` |
| `code` | String | Nie | Opcjonalny kod rabatowy / promocyjny / kod polecającego |

### Przykład zapytania cURL
```bash
curl -X POST "https://api.blackhost.pl/v1/wallet/topup" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "provider": "stripe"
  }'
```

---

## 3. Przelew wewnętrzny P2P (`/v1/wallet/transfer`)

Umożliwia błyskawiczne przekazanie środków wPLN innemu zarejestrowanemu użytkownikowi platformy BlackHost bez prowizji.

* **Metoda:** `POST`
* **Ścieżka:** `/v1/wallet/transfer`
* **Wymagany scope:** `account:billing`
* **Nagłówek:** `Content-Type: application/json`

### Parametry w ciele zapytania:
| Pole | Typ | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `amount` | Liczba | **Tak** | Kwota przelewu w wPLN (min. 1.00 wPLN) |
| `recipientEmail` | String | Opcjonalnie* | Adres e-mail odbiorcy w platformie BlackHost |
| `recipientId` | Liczba | Opcjonalnie* | ID numeryczne konta odbiorcy (*wymagany co najmniej jeden z identyfikatorów) |

### Przykład zapytania cURL
```bash
curl -X POST "https://api.blackhost.pl/v1/wallet/transfer" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "znajomy@example.com",
    "amount": 25.00
  }'
```

### Przykład odpowiedzi (200 OK)
```json
{
  "success": true,
  "message": "Przelew w kwocie 25.00 wPLN został pomyślnie zrealizowany.",
  "newBalance": 125.00
}
```

---

## 4. Dostępne bramki i metody płatności (`/v1/payments/providers`)

Pobiera listę aktualnie włączonych bramek płatniczych wraz z limitami minimalnych i maksymalnych kwot.

* **Metoda:** `GET`
* **Ścieżka:** `/v1/payments/providers`
* **Wymagany scope:** `account:read` lub `account:billing`

### Przykład zapytania cURL
```bash
curl -X GET "https://api.blackhost.pl/v1/payments/providers" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

### Przykład odpowiedzi (200 OK)
```json
{
  "success": true,
  "providers": [
    {
      "id": "stripe",
      "name": "Karty płatnicze, BLIK i Przelewy24 (Stripe)",
      "type": "fiat",
      "currency": "PLN",
      "minAmount": 5.00,
      "maxAmount": 2000.00,
      "available": true
    },
    {
      "id": "crypto_ltc",
      "name": "Litecoin (LTC)",
      "type": "crypto",
      "currency": "LTC",
      "minAmount": 10.00,
      "maxAmount": 5000.00,
      "available": true
    }
  ]
}
```

---

## 5. Katalog pakietów i sklep (`/v1/shop/packets`)

Zwraca kompletną ofertę sklepu: dostępne plany serwerów gier oraz maszyn VPS, specyfikacje sprzętowe, przydziały CPU/RAM/NVMe, lokalizacje serwerów oraz aktywne zniżki i promocje (w tym najniższą cenę z ostatnich 30 dni – Omnibus).

* **Metoda:** `GET`
* **Ścieżka:** `/v1/shop/packets`
* **Wymagany scope:** `account:read`

### Przykład zapytania cURL
```bash
curl -X GET "https://api.blackhost.pl/v1/shop/packets" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

### Struktura odpowiedzi:
* `categories` — grupy ofertowe (`vps`, `minecraft`, `bot`, itp.)
* `locations` — dostępne centra danych (np. Polska Warszawa WAW-1, Frankfurt FRA)
* `packets` — lista pakietów zawierająca:
  * `id` — unikalny identyfikator pakietu (niezbędny przy składaniu zamówień i uaktualnieniach)
  * `name` — nazwa pakietu (np. `VPS NVMe #2`, `Minecraft Dirt`)
  * `ram_mb`, `cpu`, `disk_gb` — zasoby sprzętowe
  * `price` — cena bazowa w wPLN
  * `promotionalPrice` — obniżona cena przy aktywnych akcjach promocyjnych
  * `omnibusLowestPrice30d` — najniższa cena w ostatnich 30 dniach