# API : solde, licences, retraits et factures

_API · Lecture de 7 min · Mis à jour 2026-10-22 · https://lanachat.ai/guides/fr/api-billing/_

LanaChat est payé à partir d’un **solde** prépayé en dollars US : les **licences** (une par compte Telegram, 30 jours) et une **commission** sur les ventes nettes sont déduites de ce solde. Vous le rechargez avec des dépôts en crypto. Les gains d’affiliation peuvent être **retirés**. Chaque point de terminaison de facturation nécessite un token **owner** : dans les exemples, `$LANACHAT_TOKEN` en contient un.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/billing/balance` | Le solde, les ventes nettes du mois et le palier de commission | `owner` | Planned |
| GET | `/billing/ledger` | Tous les mouvements : dépôts, licences, commission, remboursements | `owner` | Planned |
| GET | `/billing/ledger.csv` | Le même grand livre au format CSV (`from=`, `to=`) | `owner` | Planned |
| GET | `/billing/deposit-addresses` | Une adresse de dépôt par blockchain (avec un mémo sur Solana) | `owner` | Planned |
| GET | `/billing/deposits` | Dépôts et leurs confirmations | `owner` | Planned |
| GET | `/billing/licences` | Licences en stock et assignées, avec jours restants | `owner` | Planned |
| POST | `/billing/licences/buy` | Acheter des licences : une seule ou un pack de 10, 25 ou 50 | `owner` | Planned |
| POST | `/billing/licences/assign` | Attribuer une licence du stock à un compte | `owner` | Planned |
| POST | `/billing/licences/unassign` | Reprendre une licence en stock avec ses jours restants | `owner` | Planned |
| PATCH | `/billing/licences/auto-renew` | Activer ou désactiver le renouvellement automatique pour un compte | `owner` | Planned |
| GET | `/billing/withdrawals` | Retraits d’affiliés et leur statut | `owner` | Planned |
| POST | `/billing/withdrawals` | Demander un retrait des gains d’affiliation (à partir de $500) | `owner` | Planned |
| GET | `/billing/invoices` | Relevés mensuels (`year=`) | `owner` | Planned |
| GET | `/billing/invoices/{id}.pdf` | Un relevé au format PDF | `owner` | Planned |
| PUT | `/billing/details` | Nom de l’entreprise, adresse et numéro de TVA sur les relevés | `owner` | Planned |

## Prix en un tableau

| Quoi | Prix |
|---|---|
| Une licence (un compte Telegram, 30 jours) | $19 |
| Pack de 10 licences | $170 |
| Pack de 25 licences | $375 |
| Pack de 50 licences | $650 |
| Commission jusqu’à $30k de ventes nettes dans le mois | 12% des ventes AI, 4% des ventes manuelles |
| Commission de $30k à $100k | 10% et 3% |
| Commission au-delà de $100k | 8% et 2% |

Le compteur correspond aux ventes nettes de tout l’espace de travail dans le mois calendaire ; il se réinitialise le 1er. Les Telegram Stars comptent pour $0.013 chacun dans les ventes nettes.

## L’objet solde

```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
}
```

| Champ | Type | Description |
|---|---|---|
| `balance_cents` | entier | Solde prépayé, en cents US |
| `month` | chaîne | Mois calendaire comptabilisé, `YYYY-MM` |
| `net_sales_cents` | entier | Ventes nettes de l’espace de travail ce mois |
| `tier` | objet | Palier actuel : plafond `up_to_cents`, taux AI et taux manuel en points de base |
| `licences` | objet | Licences `in_stock`, `assigned`, et celles finissant dans 7 jours (`expiring_7d`) |
| `low_balance` | booléen | `true` quand le solde ne couvre pas les 7 prochains jours de licences |

Les taux sont en points de base : `1200` correspond à 12%.

## L’objet ligne du grand livre

Chaque ligne de **Billing › Activity** dans la Console.

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

| Champ | Type | Description |
|---|---|---|
| `id` | chaîne | La ligne |
| `at` | chaîne | ISO 8601, UTC |
| `kind` | chaîne | `deposit`, `licences`, `commission`, `refund`, `affiliate` ou `other` |
| `label` | chaîne | Texte de la ligne, comme dans la Console |
| `amount_cents` | entier | Positif quand de l’argent entre, négatif quand il sort |
| `balance_after_cents` | entier | Solde après cette ligne |

Une ligne `commission` correspond à une vente : la Console affiche le fan, le palier, qui a envoyé l’offre (AI ou manuel), comment le net a été calculé ("12,500 ★ × $0.013") et le taux.

## L’objet dépôt

```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"
}
```

| Champ | Type | Description |
|---|---|---|
| `id` | chaîne | Le dépôt |
| `at` | chaîne | Date de réception, ISO 8601 |
| `chain` | chaîne | `usdc-eth`, `usdc-sol`, `usdt-sol`, `usdt-tron` ou `usdt-eth` |
| `sent_cents`, `fee_cents`, `credited_cents` | entier | Montant envoyé, frais, montant crédité au solde |
| `status` | chaîne | `pending` puis `confirmed` |
| `confirmations` | chaîne | Confirmations réseau comptées, pendant le statut pending |

USDC sur Ethereum est crédité 1:1 sans frais. Chaque autre blockchain applique 1% de frais : le dépôt est converti en USDC (ERC20) à l’arrivée. Le minimum est $25 par recharge.

## L’objet licence

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

| Champ | Type | Description |
|---|---|---|
| `account_id` | chaîne | Le compte Telegram sur lequel la licence est active |
| `creator_id` | chaîne | Sa créatrice |
| `days_left` | entier | Jours restants avant expiration, sur 30 |
| `expires_at` | chaîne | Date d’expiration |
| `auto_renew` | booléen | Renouvellement automatique depuis le stock (ou achat d’une licence simple) à l’expiration |

Les licences en stock sont comptées, non listées individuellement : chacune garde ses jours restants (30 pour une neuve).

## L’objet retrait

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

| Champ | Type | Description |
|---|---|---|
| `id` | chaîne | Le retrait |
| `status` | chaîne | `pending_review`, `sent` (avec `tx_hash`) ou `rejected` avec une raison |
| `amount_cents` | entier | Montant demandé, au moins 50000 ($500) |
| `requested_at` | chaîne | ISO 8601, UTC |
| `tx_hash` | chaîne ou null | La transaction, une fois envoyée |

## L’objet facture

```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"
}
```

| Champ | Type | Description |
|---|---|---|
| `id` | chaîne | Numéro du relevé, `LC-YYYY-MM` |
| `month` | chaîne | Mois couvert |
| `licences_cents`, `commission_cents`, `total_cents` | entier | Licences, commission et total du mois |
| `status` | chaîne | Payé, en cours (mois actuel) ou échoué |
| `pdf_url` | chaîne | PDF du relevé |

## Solde et grand livre

### Obtenir le solde

`GET /billing/balance` · `owner`

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

La réponse est l’objet solde.

### Lister le grand livre

`GET /billing/ledger` · `owner`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `from`, `to` | chaîne | Non | Jours `YYYY-MM-DD`, UTC, inclus |
| `limit`, `cursor` | nombre, chaîne | Non | [Pagination](https://lanachat.ai/guides/fr/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"
}
```

### Exporter le grand livre en CSV

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

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `from`, `to` | chaîne | Non | Jours `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
```

Les mêmes lignes que **Export CSV** dans **Billing › Activity**, prêtes pour votre comptable.

## Dépôts

### Obtenir les adresses de dépôt

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

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

La réponse donne une adresse par blockchain (Ethereum, Solana, Tron) et, pour Solana, le mémo.

> Warning: Sur Solana, un dépôt envoyé sans mémo ne peut pas être rattaché à votre espace de travail. Envoyez toujours l’adresse et le mémo.

Vous pouvez envoyer des USDC sur Ethereum (ERC20), USDC sur Solana, USDT sur Solana, USDT sur Tron (TRC20) ou USDT sur Ethereum (ERC20). Les frais réseau de votre transfert sont à votre charge.

### Lister les dépôts

`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
}
```

Le solde est crédité automatiquement quand un dépôt est `confirmed` ; il apparaît alors aussi comme une ligne `deposit` dans le grand livre.

## Licences

### Lister les licences

`GET /billing/licences` · `owner`

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

La réponse donne les licences en stock et un objet licence par compte assigné, avec ses jours restants.

### Acheter des licences

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

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `pack` | entier | Oui | `1` (simple, $19), `10` ($170), `25` ($375) ou `50` ($650) |
| `qty` | entier | Oui | Nombre de packs |

```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" }
```

Les licences vont immédiatement dans votre stock. Un solde insuffisant répond `402` (`insufficient_balance`). Les licences en stock n’expirent jamais, et les licences achetées ne sont pas remboursables.

### Assigner une licence

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

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `account_id` | chaîne | Oui | Le compte Telegram qui reçoit une licence |

```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"}'
```

La réponse est l’objet licence du compte. La licence du stock avec le moins de jours restants est utilisée en premier : ses jours restants, ou 30 jours si elle est neuve. Le renouvellement automatique est activé par défaut.

### Reprendre une licence

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

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `account_id` | chaîne | Oui | Le compte qui rend sa licence |

```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"}'
```

La licence retourne dans votre stock avec ses jours restants. L’IA cesse de répondre sur ce compte immédiatement. Pour déplacer une licence vers un autre compte, reprenez-la puis assignez-la : elle conserve ses jours, gratuitement.

### Activer ou désactiver le renouvellement automatique

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

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `account_id` | chaîne | Oui | Le compte |
| `auto_renew` | booléen | Oui | `true` pour renouveler à l’expiration |

```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}'
```

À l’expiration, le renouvellement automatique prend d’abord une licence dans votre stock, ou achète une licence simple ($19) si le stock est vide. Il ne peut pas acheter sans solde : surveillez `low_balance` ou le webhook `billing.low_balance` [webhook](https://lanachat.ai/guides/fr/api-webhooks/).

## Retraits d’affiliés

### Lister les retraits

`GET /billing/withdrawals` · `owner`

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

Une liste d’objets retrait, du plus récent au plus ancien.

### Demander un retrait

`POST /billing/withdrawals` · `owner`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `amount_cents` | entier | Oui | Au moins 50000 ($500), au maximum disponible à retirer |

```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 }
```

Les gains sont envoyés en USDC au portefeuille enregistré, 7 jours après la fin du mois. Seuls les gains d’affiliation peuvent être retirés, jamais le solde prépayé. Une demande inférieure à $500 est refusée.

## Relevés

### Lister les relevés

`GET /billing/invoices` · `owner`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `year` | entier | Non | Par exemple `2026` |

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

Un objet facture par mois.

### Télécharger un relevé

`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: Vérifiez vos relevés. Une erreur de facturation doit être signalée dans les 60 jours suivant le relevé qui la montre ; passé ce délai, le relevé est définitif.

### Définir les détails de facturation

`PUT /billing/details` · `owner`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `company` | chaîne | Non | Nom de l’entreprise |
| `email` | chaîne | Non | E-mail de facturation |
| `address`, `city`, `postal`, `country` | chaîne | Non | Adresse postale |
| `vat` | chaîne | Non | Numéro de TVA |

```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"}'
```

Les mêmes champs que dans **Billing › Billing details**. Les relevés portent ces informations. Le `PUT` remplace tout : un champ omis est vidé.

## Articles liés

- [API LanaChat : démarrage rapide, authentification et erreurs](https://lanachat.ai/guides/fr/api-overview/)
- [Facturation : licences, commission et solde](https://lanachat.ai/guides/fr/billing/)