# API: saldo, licencje, wypłaty i faktury

_API · 7 min czytania · Zaktualizowano 2026-10-22 · https://lanachat.ai/guides/pl/api-billing/_

LanaChat jest opłacany z jednego przedpłaconego **salda** w dolarach amerykańskich: pobierane są z niego **licencje** (po jednej na konto Telegram, 30 dni) oraz **prowizja** od sprzedaży netto. Doładowujesz je depozytami w kryptowalutach. Zarobki afiliacyjne można **wypłacić**. Każdy endpoint rozliczeniowy wymaga tokena **owner**: w przykładach jest nim `$LANACHAT_TOKEN`.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/billing/balance` | Saldo, sprzedaż netto w tym miesiącu i poziom prowizji | `owner` | Planned |
| GET | `/billing/ledger` | Każdy ruch: depozyty, licencje, prowizja, zwroty | `owner` | Planned |
| GET | `/billing/ledger.csv` | Ten sam dziennik w formacie CSV (`from=`, `to=`) | `owner` | Planned |
| GET | `/billing/deposit-addresses` | Jeden adres depozytowy na łańcuch (z memo na Solanie) | `owner` | Planned |
| GET | `/billing/deposits` | Depozyty i ich potwierdzenia | `owner` | Planned |
| GET | `/billing/licences` | Licencje na stanie i przypisane, z pozostałymi dniami | `owner` | Planned |
| POST | `/billing/licences/buy` | Kup licencje: pojedynczą lub pakiet 10, 25 lub 50 | `owner` | Planned |
| POST | `/billing/licences/assign` | Przypisz licencję ze stanu do konta | `owner` | Planned |
| POST | `/billing/licences/unassign` | Zabierz ją z powrotem na stan z pozostałymi dniami | `owner` | Planned |
| PATCH | `/billing/licences/auto-renew` | Włącz lub wyłącz automatyczne odnawianie dla konta | `owner` | Planned |
| GET | `/billing/withdrawals` | Wypłaty afiliacyjne i ich status | `owner` | Planned |
| POST | `/billing/withdrawals` | Poproś o wypłatę zarobków afiliacyjnych (od $500) | `owner` | Planned |
| GET | `/billing/invoices` | Miesięczne zestawienia (`year=`) | `owner` | Planned |
| GET | `/billing/invoices/{id}.pdf` | Jedno zestawienie w PDF | `owner` | Planned |
| PUT | `/billing/details` | Nazwa firmy, adres i NIP na zestawieniach | `owner` | Planned |

## Cennik w jednej tabeli

| Co | Cena |
|---|---|
| Jedna licencja (jedno konto Telegram, 30 dni) | $19 |
| Pakiet 10 licencji | $170 |
| Pakiet 25 licencji | $375 |
| Pakiet 50 licencji | $650 |
| Prowizja do $30k sprzedaży netto w miesiącu | 12% od sprzedaży AI, 4% od sprzedaży manualnej |
| Prowizja od $30k do $100k | 10% i 3% |
| Prowizja powyżej $100k | 8% i 2% |

Licznik to sprzedaż netto całego workspace w miesiącu kalendarzowym; zeruje się 1. dnia miesiąca. Telegram Stars liczone są po $0.013 za sztukę w sprzedaży netto.

## Obiekt salda

```json
{
  "balance_cents": 48210,
  "month": "2026-10",
  "net_sales_cents": 1870400,
  "tier": { "up_to_cents": 3000000, "ai_rate_bp": 1200, "manual_rate_bp": 300 },
  "licences": { "in_stock": 4, "assigned": 11, "expiring_7d": 2 },
  "low_balance": false
}
```

| Pole | Typ | Opis |
|---|---|---|
| `balance_cents` | integer | Przedpłacone saldo, w centach USD |
| `month` | string | Liczony miesiąc kalendarzowy, `YYYY-MM` |
| `net_sales_cents` | integer | Sprzedaż netto workspace w tym miesiącu |
| `tier` | object | Aktualny poziom: jego limit `up_to_cents`, stawka AI i stawka manualna w punktach bazowych |
| `licences` | object | Licencje `in_stock`, `assigned` oraz przypisane kończące się w ciągu 7 dni (`expiring_7d`) |
| `low_balance` | boolean | `true`, gdy saldo nie pokrywa kolejnych 7 dni licencji |

Stawki są w punktach bazowych: `1200` to 12%.

## Obiekt wpisu w dzienniku

Każda linia z **Billing › Activity** w Konsoli.

```json
{
  "id": "led_90211",
  "at": "2026-10-06T14:40:00Z",
  "kind": "licences",
  "label": "Licences · pack of 10",
  "amount_cents": -17000,
  "balance_after_cents": 31210
}
```

| Pole | Typ | Opis |
|---|---|---|
| `id` | string | Linia |
| `at` | string | ISO 8601, UTC |
| `kind` | string | `deposit`, `licences`, `commission`, `refund`, `affiliate` lub `other` |
| `label` | string | Tekst linii, jak w Konsoli |
| `amount_cents` | integer | Dodatnia, gdy wpływa pieniądz, ujemna, gdy wychodzi |
| `balance_after_cents` | integer | Saldo po tej linii |

Linia `commission` dotyczy jednej sprzedaży: Konsola pokazuje fana, poziom, kto wysłał ofertę (AI lub manualnie), jak liczono netto ("12,500 ★ × $0.013") i stawkę.

## Obiekt depozytu

```json
{
  "id": "dep_4",
  "at": "2026-10-06T13:52:00Z",
  "chain": "usdt-tron",
  "sent_cents": 100000,
  "fee_cents": 1000,
  "credited_cents": 99000,
  "status": "pending",
  "confirmations": "12/19"
}
```

| Pole | Typ | Opis |
|---|---|---|
| `id` | string | Depozyt |
| `at` | string | Kiedy zauważono, ISO 8601 |
| `chain` | string | `usdc-eth`, `usdc-sol`, `usdt-sol`, `usdt-tron` lub `usdt-eth` |
| `sent_cents`, `fee_cents`, `credited_cents` | integer | Co wysłano, opłata, co trafia na saldo |
| `status` | string | `pending` potem `confirmed` |
| `confirmations` | string | Liczba potwierdzeń sieciowych, gdy w trakcie oczekiwania |

USDC na Ethereum jest księgowane 1:1 bez opłaty. Każdy inny łańcuch ma 1% opłaty: depozyt jest konwertowany na USDC (ERC20) po przybyciu. Minimalna kwota doładowania to $25.

## Obiekt licencji

```json
{
  "account_id": "acc_1001",
  "creator_id": "cr_lea",
  "days_left": 18,
  "expires_at": "2026-10-24T09:00:00Z",
  "auto_renew": true
}
```

| Pole | Typ | Opis |
|---|---|---|
| `account_id` | string | Konto Telegram, na którym działa licencja |
| `creator_id` | string | Jej twórczyni |
| `days_left` | integer | Dni do końca, z 30 |
| `expires_at` | string | Kiedy kończy się licencja |
| `auto_renew` | boolean | Odnawiaj ze stanu (lub kup pojedynczą), gdy się kończy |

Licencje na stanie są liczone, nie wymieniane pojedynczo: każda ma własne pozostałe dni (30 dla nowej).

## Obiekt wypłaty

```json
{ "id": "wd_118", "status": "pending_review", "amount_cents": 50000, "requested_at": "2026-10-06T15:00:00Z", "tx_hash": null }
```

| Pole | Typ | Opis |
|---|---|---|
| `id` | string | Wypłata |
| `status` | string | `pending_review`, `sent` (z `tx_hash`) lub `rejected` z powodem |
| `amount_cents` | integer | Kwota żądana, co najmniej 50000 ($500) |
| `requested_at` | string | ISO 8601, UTC |
| `tx_hash` | string lub null | Transakcja, gdy wysłana |

## Obiekt faktury

```json
{
  "id": "LC-2026-09",
  "month": "2026-09",
  "licences_cents": 22800,
  "commission_cents": 930000,
  "total_cents": 952800,
  "status": "paid",
  "pdf_url": "https://api.lanachat.ai/v1/billing/invoices/LC-2026-09.pdf"
}
```

| Pole | Typ | Opis |
|---|---|---|
| `id` | string | Numer zestawienia, `LC-YYYY-MM` |
| `month` | string | Miesiąc, którego dotyczy |
| `licences_cents`, `commission_cents`, `total_cents` | integer | Licencje, prowizja i suma za miesiąc |
| `status` | string | Opłacona, w trakcie (bieżący miesiąc) lub nieudana |
| `pdf_url` | string | PDF zestawienia |

## Saldo i dziennik

### Pobierz saldo

`GET /billing/balance` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/balance \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Odpowiedź to obiekt salda.

### Wyświetl dziennik

`GET /billing/ledger` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `from`, `to` | string | Nie | Dni `YYYY-MM-DD`, UTC, oba włącznie |
| `limit`, `cursor` | number, string | Nie | [Paginacja](https://lanachat.ai/guides/pl/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/billing/ledger?from=2026-10-01&to=2026-10-06" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "led_90211", "at": "2026-10-06T14:40:00Z", "kind": "licences", "label": "Licences · pack of 10", "amount_cents": -17000, "balance_after_cents": 31210 },
    { "id": "led_90207", "at": "2026-10-06T13:20:00Z", "kind": "commission", "label": "Lea · Marco", "amount_cents": -468, "balance_after_cents": 48210 },
    { "id": "led_90150", "at": "2026-10-05T09:02:00Z", "kind": "deposit", "label": "Deposit · USDC on Ethereum", "amount_cents": 300000, "balance_after_cents": 48678 }
  ],
  "next_cursor": "eyJpZCI6ImxlZF85MDE0OSJ9"
}
```

### Eksportuj dziennik jako CSV

`GET /billing/ledger.csv` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `from`, `to` | string | Nie | Dni `YYYY-MM-DD`, UTC |

```bash
curl "https://api.lanachat.ai/v1/billing/ledger.csv?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $LANACHAT_TOKEN" -o ledger-2026-09.csv
```

Te same linie co **Export CSV** w **Billing › Activity**, gotowe dla księgowej.

## Depozyty

### Pobierz adresy depozytowe

`GET /billing/deposit-addresses` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/deposit-addresses \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Odpowiedź zawiera jeden adres na łańcuch (Ethereum, Solana, Tron) oraz memo dla Solany.

> Warning: Na Solanie depozyt wysłany bez memo nie może zostać przypisany do Twojego workspace. Zawsze wysyłaj zarówno adres, jak i memo.

Możesz wysyłać USDC na Ethereum (ERC20), USDC na Solanie, USDT na Solanie, USDT na Tron (TRC20) lub USDT na Ethereum (ERC20). Opłata sieciowa za transfer jest pobierana z Twojego portfela.

### Wyświetl depozyty

`GET /billing/deposits` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/deposits \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "dep_4", "at": "2026-10-06T13:52:00Z", "chain": "usdt-tron", "sent_cents": 100000, "fee_cents": 1000, "credited_cents": 99000, "status": "pending", "confirmations": "12/19" },
    { "id": "dep_3", "at": "2026-10-05T09:02:00Z", "chain": "usdc-eth", "sent_cents": 300000, "fee_cents": 0, "credited_cents": 300000, "status": "confirmed", "confirmations": null }
  ],
  "next_cursor": null
}
```

Saldo jest księgowane automatycznie, gdy depozyt jest `confirmed`; wtedy pojawia się też linia `deposit` w dzienniku.

## Licencje

### Wyświetl licencje

`GET /billing/licences` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/licences \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Odpowiedź zawiera licencje na stanie oraz jeden obiekt licencji na przypisane konto, z pozostałymi dniami.

### Kup licencje

`POST /billing/licences/buy` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `pack` | integer | Tak | `1` (pojedyncza, $19), `10` ($170), `25` ($375) lub `50` ($650) |
| `qty` | integer | Tak | Ile pakietów |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/buy \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"pack": 10, "qty": 1}'
```

```json
{ "licences_added": 10, "amount_cents": 17000, "balance_cents": 31210, "ledger_id": "led_90211" }
```

Licencje trafiają od razu na Twój stan. Za niskie saldo zwraca `402` (`insufficient_balance`). Licencje na stanie nigdy nie wygasają, a zakupionych nie można zwrócić.

### Przypisz licencję

`POST /billing/licences/assign` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `account_id` | string | Tak | Konto Telegram, które dostaje licencję |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/assign \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001"}'
```

Odpowiedź to obiekt licencji konta. Najpierw używana jest licencja ze stanu z najmniejszą liczbą dni pozostałych: jej pozostałe dni lub 30, jeśli jest nowa. Auto-renew jest domyślnie włączone.

### Zabierz licencję z konta

`POST /billing/licences/unassign` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `account_id` | string | Tak | Konto, które oddaje licencję |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/unassign \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001"}'
```

Licencja wraca na Twój stan z pozostałymi dniami. AI przestaje odpowiadać na tym koncie natychmiast. Aby przenieść licencję na inne konto, najpierw ją zabierz, potem przypisz: zachowa swoje dni, bezpłatnie.

### Włącz lub wyłącz auto-renew

`PATCH /billing/licences/auto-renew` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `account_id` | string | Tak | Konto |
| `auto_renew` | boolean | Tak | `true`, aby odnawiać, gdy dni się skończą |

```bash
curl -X PATCH https://api.lanachat.ai/v1/billing/licences/auto-renew \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001", "auto_renew": false}'
```

Gdy dni się skończą, auto-renew najpierw pobiera licencję ze stanu lub kupuje pojedynczą ($19), jeśli stan jest pusty. Nie może kupić bez salda: obserwuj `low_balance` lub webhook `billing.low_balance` [webhook](https://lanachat.ai/guides/pl/api-webhooks/).

## Wypłaty afiliacyjne

### Wyświetl wypłaty

`GET /billing/withdrawals` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/withdrawals \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Lista obiektów wypłat, od najnowszych.

### Poproś o wypłatę

`POST /billing/withdrawals` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `amount_cents` | integer | Tak | Co najmniej 50000 ($500), maksymalnie dostępne do wypłaty |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/withdrawals \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 50000}'
```

```json
{ "id": "wd_118", "status": "pending_review", "amount_cents": 50000, "requested_at": "2026-10-06T15:00:00Z", "tx_hash": null }
```

Zarobki są wysyłane w USDC na portfel zarejestrowany, 7 dni po zakończeniu miesiąca. Wypłaca się tylko zarobki afiliacyjne, nigdy saldo przedpłacone. Prośba poniżej $500 jest odrzucana.

## Zestawienia

### Wyświetl zestawienia

`GET /billing/invoices` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `year` | integer | Nie | Na przykład `2026` |

```bash
curl "https://api.lanachat.ai/v1/billing/invoices?year=2026" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Jeden obiekt faktury na miesiąc.

### Pobierz zestawienie

`GET /billing/invoices/{id}.pdf` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/invoices/LC-2026-09.pdf \
  -H "Authorization: Bearer $LANACHAT_TOKEN" -o LC-2026-09.pdf
```

> Warning: Sprawdzaj swoje zestawienia. Błąd rozliczeniowy należy zgłosić w ciągu 60 dni od zestawienia, które go pokazuje; po tym terminie zestawienie jest ostateczne.

### Ustaw dane rozliczeniowe

`PUT /billing/details` · `owner`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `company` | string | Nie | Nazwa firmy |
| `email` | string | Nie | E-mail rozliczeniowy |
| `address`, `city`, `postal`, `country` | string | Nie | Adres pocztowy |
| `vat` | string | Nie | Numer VAT |

```bash
curl -X PUT https://api.lanachat.ai/v1/billing/details \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company": "Mia Agency Ltd", "email": "billing@mia-agency.com", "address": "12 Market Street", "city": "Dublin", "postal": "D02 X285", "country": "IE", "vat": "IE1234567T"}'
```

Te same pola co w **Billing › Billing details**. Zestawienia zawierają te dane. `PUT` zastępuje je wszystkie: pole pominięte zostaje wyczyszczone.

## Powiązane artykuły

- [LanaChat API: szybki start, uwierzytelnianie i błędy](https://lanachat.ai/guides/pl/api-overview/)
- [Rozliczenia: licencje, prowizje i saldo](https://lanachat.ai/guides/pl/billing/)