# Référence des crédits

> Écrans, champs, types de transactions, packs, erreurs de solde insuffisant et endpoints de l'API publique pour les crédits.

Cette page rassemble les écrans de la console, les objets et les endpoints liés aux crédits. L'achat de packs est la seule opération de crédits exposée par l'API publique, `https://api.wakastart.app/api`.

## Accès

| Élément | Condition |
|---|---|
| Entrées **Tableau de Bord** et **Consommation** du groupe **Modules** | Droit **Facturation**, porté par le profil **Financier** |
| Badge **N crédits** de l'en-tête | Droit **Facturation** |
| Onglet **Crédits** du paramétrage d'une application | Accès au **Paramétrage** de l'application |
| Page **Tarification Générale** | Niveau Propriétaire |
| `GET /api/pay/packs` | Tout appelant authentifié |
| `POST /api/pay/packs/{packCode}/checkout-sessions` | Niveau Administrateur client, ou clé API d'un client |

## Écran Crédits (Tableau de Bord)

| Élément | Contenu |
|---|---|
| **Solde actuel** | Crédits disponibles du client |
| **Total consommé** | Cumul des débits |
| **Total rechargé** | Cumul des crédits ajoutés |
| **Consommation** | Graphique des crédits consommés ; onglets **Jour**, **Semaine**, **Mois** |
| **Top opérations** | Les cinq codes d'opération les plus consommateurs |
| **Dernières transactions** | Les cinq derniers mouvements ; lien **Voir tout** |

## Écran Consommation détaillée

| Colonne | Contenu |
|---|---|
| **Date** | Date et heure du mouvement |
| **Opération** | Code de l'opération facturée |
| **Type** | **Débit**, **Crédit**, **Ajustement** ou **Remboursement** |
| **Montant** | Nombre de crédits du mouvement |
| **Solde après** | Solde juste après le mouvement |
| **Utilisateur** | Identifiant de l'utilisateur à l'origine de l'opération, s'il est connu |

L'écran affiche les 20 mouvements les plus récents du filtre choisi. Messages d'état : **Aucune transaction**, **Aucun résultat pour ces filtres**.

## L'objet Solde

| Champ | Type | Description |
|---|---|---|
| `ownerType` | `CUSTOMER` ou `NETWORK` | Type de titulaire |
| `ownerWid` | chaîne (6) | Identifiant du client ou du réseau |
| `balance` | entier | Crédits disponibles |
| `totalBought` | entier | Cumul des crédits ajoutés |
| `totalSpent` | entier | Cumul des crédits débités |

## L'objet Transaction

| Champ | Type | Description |
|---|---|---|
| `type` | énumération | `DEBIT`, `CREDIT`, `ADJUSTMENT`, `REFUND`, `TRANSFER_IN`, `TRANSFER_OUT` |
| `amount` | entier | Nombre de crédits du mouvement |
| `balanceAfter` | entier | Solde après le mouvement |
| `operationCode` | chaîne | Code de l'opération facturée, pour un débit |
| `reason` | chaîne | Motif, pour un crédit ou un ajustement |
| `createdAt` | date ISO 8601 | Horodatage |

## Packs de crédits

| Code | Libellé | Crédits | Prix |
|---|---|---|---|
| `STARTER` | Pack Starter | 100 | 9 € |
| `PRO` | Pack Pro | 500 | 39 € |
| `BUSINESS` | Pack Business | 2 000 | 139 € |
| `ENTERPRISE` | Pack Enterprise | 10 000 | 599 € |

## Limites et valeurs

| Élément | Valeur |
|---|---|
| Coût minimal d'une opération | 1 crédit |
| Surcharge | 0 crédit ou plus ; 0 rend l'opération gratuite |
| Historique visible dans la console | 30 jours |
| Archivage des transactions | 7 ans, stockage non modifiable |
| Rafraîchissement du badge de l'en-tête | 60 secondes |
| `idempotencyKey` d'un achat de pack | 180 caractères, obligatoire |

## Solde insuffisant

Quand une opération facturée dépasse le solde, le service appelé répond `402 Payment Required` et rien n'est débité. Le module Antivirus, par exemple, renvoie le nombre de crédits nécessaires et disponibles :

```json
{
  "statusCode": 402,
  "message": "Insufficient credits",
  "operation": "SCAN_DOCUMENT",
  "available": 0,
  "required": 1
}
```

Si votre client n'a encore jamais eu de solde, le message est « No credit account found for customer … », avec le même code `402`. Achetez un pack pour ouvrir le solde.

## Lister les packs

::endpoint{method="GET" path="/api/pay/packs"}

Renvoie les packs en vente : `name`, `creditRatio` (crédits par pack), `stripeProductId` et `prices` (`stripePriceId`, `unitAmountCents`, `currency`).

```bash
curl -s https://api.wakastart.app/api/pay/packs -H "x-api-key: sk_test_exemple"
```

## Acheter un pack

::endpoint{method="POST" path="/api/pay/packs/{packCode}/checkout-sessions"}

| Paramètre | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `packCode` | chemin | oui | `STARTER`, `PRO`, `BUSINESS` ou `ENTERPRISE` |
| `successUrl` | corps | oui | Retour après paiement, sur `https://app.wakastart.app` |
| `cancelUrl` | corps | oui | Retour après abandon, même contrainte |
| `idempotencyKey` | corps | oui | Identifiant stable de l'achat |
| `customerEmail` | corps | non | Prérempli sur la page Stripe |

```bash
curl -s -X POST https://api.wakastart.app/api/pay/packs/STARTER/checkout-sessions \
  -H "x-api-key: sk_test_exemple" -H "Content-Type: application/json" \
  -d '{"successUrl":"https://app.wakastart.app/credits","cancelUrl":"https://app.wakastart.app/credits","idempotencyKey":"recharge-0001"}'
```

Réponse `201` :

```json
{ "id": "cs_live_Exemple4", "url": "https://checkout.stripe.com/c/pay/cs_live_Exemple4" }
```

| Code | Cause |
|---|---|
| `400` | Pack inconnu, URL de retour hors de la console, champ invalide, ou champ `ownerType` / `ownerWid` envoyé dans le corps |
| `403` | Niveau insuffisant, ou aucun client ni réseau rattaché à l'appelant |
| `404` | Pack momentanément indisponible à la vente |

## Voir aussi

- [Soldes et transactions](/v1.0/credits/soldes-et-transactions)
- [Référence API : crédits](/v1.0/reference-api/credits)
