> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caurisflux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Référence complète de l API CaurisFlux

## URL de base

<CodeGroup>
  ```bash Sandbox theme={null}
  https://sandbox-api.caurisflux.com/api/v1
  ```

  ```bash Production theme={null}
  https://prod-api.caurisflux.com/api/v1
  ```
</CodeGroup>

| Environnement  | URL                                         | Préfixe clés            |
| -------------- | ------------------------------------------- | ----------------------- |
| **Sandbox**    | `https://sandbox-api.caurisflux.com/api/v1` | `pk_test_` / `sk_test_` |
| **Production** | `https://prod-api.caurisflux.com/api/v1`    | `pk_live_` / `sk_live_` |

<Tip>
  En mode sandbox, utilisez les clés `pk_test_*` / `sk_test_*` et les numéros de test pour simuler des transactions sans argent réel.
</Tip>

## Authentification

Toutes les requêtes API doivent inclure vos clés API. Vous avez deux options :

### Option 1 : Header X-API-Key (recommandé)

```bash theme={null}
X-API-Key: pk_test_xxx:sk_test_xxx
```

### Option 2 : Bearer Token

```bash theme={null}
Authorization: Bearer pk_test_xxx:sk_test_xxx
```

<Warning>
  Le format est `clé_publique:clé_secrète`. Les deux clés sont nécessaires pour l'authentification.
</Warning>

### Exemple de requête authentifiée

```bash theme={null}
curl https://sandbox-api.caurisflux.com/api/v1/payments/balance \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json"
```

<Info>
  Certains endpoints publics (comme `/payments/providers` ou `/countries/active`) ne nécessitent pas d'authentification.
</Info>

## Format des requêtes

* **Content-Type** : `application/json`
* **Encodage** : UTF-8
* **Méthodes** : GET, POST, PUT, DELETE

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payments/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "direct",
    "provider": "wave",
    "amount": 5000,
    "currency": "XOF",
    "country": "SN",
    "customerPhone": "+221771234567",
    "externalReference": "ORDER-001"
  }'
```

## Format des réponses

Toutes les réponses sont en JSON avec une structure cohérente :

### Réponse réussie

```json theme={null}
{
  "success": true,
  "data": {
    "transactionId": "TX000007272",
    "status": "pending",
    "amount": 5000,
    "currency": "XOF",
    "redirectUrl": "https://pay.wave.com/c/sn/~abc123",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

### Réponse d'erreur

```json theme={null}
{
  "statusCode": 400,
  "message": "Le montant doit être supérieur à 100 XOF",
  "error": "Bad Request"
}
```

## Pagination

Les endpoints qui retournent des listes supportent la pagination :

| Paramètre | Description                | Défaut | Max |
| --------- | -------------------------- | ------ | --- |
| `page`    | Numéro de page             | 1      | -   |
| `limit`   | Nombre d'éléments par page | 20     | 100 |

```json theme={null}
{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}
```

## Codes de statut HTTP

| Code  | Signification         |
| ----- | --------------------- |
| `200` | Succès                |
| `201` | Ressource créée       |
| `400` | Requête invalide      |
| `401` | Non authentifié       |
| `403` | Non autorisé          |
| `404` | Ressource non trouvée |
| `422` | Erreur de validation  |
| `429` | Trop de requêtes      |
| `500` | Erreur serveur        |

## Gestion des erreurs

Les erreurs retournent un objet JSON avec les détails :

```json theme={null}
{
  "statusCode": 400,
  "message": "Le montant doit être supérieur à 100 XOF",
  "error": "Bad Request"
}
```

### Codes d'erreur courants

| Code                 | Description                  |
| -------------------- | ---------------------------- |
| `insufficient_funds` | Solde insuffisant            |
| `invalid_phone`      | Numéro de téléphone invalide |
| `invalid_amount`     | Montant invalide             |
| `provider_error`     | Erreur du fournisseur        |
| `limit_exceeded`     | Limite dépassée              |

## Rate limiting

| Plan       | Limite               |
| ---------- | -------------------- |
| Standard   | 100 requêtes/minute  |
| Business   | 1000 requêtes/minute |
| Enterprise | Illimité             |

Les en-têtes de réponse incluent :

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800
```

## Idempotence

Pour éviter les paiements en double, incluez l'en-tête `X-Idempotency-Key` avec une valeur unique (par exemple, votre ID de commande) :

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payments/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "X-Idempotency-Key: ORDER-12345" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "type": "direct", ...}'
```

<Note>
  Les clés d'idempotence expirent après 24h. Utilisez votre ID de commande comme clé pour garantir l'unicité.
</Note>

## Flux de paiement (Collect)

1. **Récupérer les méthodes** → `GET /payments/providers`
2. **Initier le paiement** → `POST /payments/initiate`
3. **Rediriger le client** vers `redirectUrl` retourné
4. **Recevoir le webhook** de confirmation
5. **Vérifier le statut** → `GET /payments/status/:transactionId`

## Flux de payout (Décaissement)

1. **Obtenir un devis** → `POST /payouts/quote`
2. **Confirmer le payout** → `POST /payouts/initiate` (avec `quoteId`)
3. **Recevoir le webhook** de confirmation
4. **Vérifier le statut** → `GET /payouts/status/:payoutId`

<Tip>
  Le flux quote-based garantit que le marchand connaît le montant exact débité avant de confirmer. Le devis est valide 5 minutes.
</Tip>

## Support

* **Email** : [integration@caurisflux.com](mailto:integration@caurisflux.com)
* **Documentation** : [https://docs.caurisflux.com](https://docs.caurisflux.com)