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

# Créer un compte et obtenir une clé API

> Le mécanisme complet, de zéro jusqu'à votre première clé API — inscription, vérification KYC, création de la clé.

Avant de pouvoir appeler l'API avec une clé (`Authorization: Bearer sk_...`), un compte doit exister, être vérifié (KYC), puis générer sa première clé. **Ces étapes préalables ne peuvent PAS se faire avec une clé API** — pour une raison structurelle simple : la clé n'existe pas encore. Elles utilisent un jeton de session (JWT), obtenu par connexion classique email/mot de passe, exactement comme le tableau de bord [app.saspay.me](https://app.saspay.me) lui-même. Une fois votre première clé générée, vous n'avez plus jamais besoin de JWT pour intégrer l'API.

<Info>
  Tout ce mécanisme est utilisable en API pure (pas seulement depuis le tableau de bord) si vous voulez automatiser votre propre onboarding — les mêmes appels sont ceux que fait l'interface web.
</Info>

## 1. Créer votre compte utilisateur

```bash theme={null}
curl -X POST https://api.saspay.me/api/v1/users/ \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Awa Sossou",
    "email": "awa@example.com",
    "country": "<uuid du pays, cf. GET /countries/>",
    "password": "un-mot-de-passe-solide"
  }'
```

Public — aucune authentification requise. Déclenche automatiquement l'envoi d'un code de vérification par email.

## 2. Vérifier votre email

```bash theme={null}
curl -X POST https://api.saspay.me/api/v1/auth/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"email": "awa@example.com", "code": "123456"}'
```

Tant que l'email n'est pas vérifié, la connexion (étape 3) échoue avec `403 email_not_verified`.

## 3. Vous connecter (obtenir un jeton de session)

```bash theme={null}
curl -X POST https://api.saspay.me/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "awa@example.com", "password": "un-mot-de-passe-solide"}'
```

```json Réponse theme={null}
{ "tokens": { "access": "eyJhbGciOi...", "refresh": "eyJhbGciOi..." } }
```

<Note>
  Si l'authentification à deux facteurs est activée sur le compte, cette réponse contient `pending_2fa_token` au lieu de `tokens` — une étape supplémentaire (`POST /auth/login/verify-2fa/`) est alors nécessaire. Non détaillée ici, hors périmètre de l'intégration API pure.
</Note>

Utilisez `access` dans le header `Authorization: Bearer <access>` pour toutes les requêtes des étapes suivantes — **ce n'est pas une clé API**, c'est un jeton de session classique, à ne jamais confondre avec `sk_live_.../sk_test_...`.

## 4. Créer votre marchand (votre "boutique")

```bash theme={null}
curl -X POST https://api.saspay.me/api/v1/merchants/ \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ma Boutique",
    "website_url": "https://maboutique.com",
    "category": "e-commerce"
  }'
```

Un même compte utilisateur peut posséder plusieurs marchands (plusieurs boutiques indépendantes). Le marchand créé démarre avec `kyc_status: "NONE"` et `is_active: false` — inutilisable tant que le KYC n'est pas validé.

## 5. Soumettre votre dossier KYC

Même endpoint et même flux que documentés dans [KYC](/api-reference/kyc) — la seule différence ici est le header d'authentification (`Authorization: Bearer <jeton de session>` plutôt qu'une clé API, puisqu'aucune clé n'existe encore à ce stade).

```bash theme={null}
curl -X POST https://api.saspay.me/api/v1/merchant-kyc/ \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "<id du marchand créé à l'\''étape 4>",
    "kyc_type": "BUSINESS",
    "first_name": "Awa", "last_name": "Sossou",
    "company_name": "Ma Boutique SARL", "rccm_number": "BJ-COT-2023-B-1234", "ifu_number": "3202312345678"
  }'
```

Puis uploadez et attachez vos pièces justificatives ([voir le détail](/api-reference/kyc)).

## 6. Attendre la validation

Un administrateur SasPay examine le dossier. Vous recevez un email dès qu'une décision est prise. Une fois validé, `merchant.kyc_status` passe à `"VERIFIED"` et `is_active` à `true`.

## 7. Créer votre première clé API

```bash theme={null}
curl -X POST https://api.saspay.me/api/v1/merchant-api-keys/ \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend production",
    "environment": "LIVE",
    "scope": "BOTH"
  }'
```

```json Réponse theme={null}
{
  "id": "d4e5...", "merchant": "8a2f...", "name": "Backend production",
  "key_prefix": "sk_live_AbCdEfGh", "environment": "LIVE", "scope": "BOTH",
  "is_active": true, "expires_at": null, "last_used_at": null,
  "secret": "sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789"
}
```

<Warning>
  Le champ `secret` (la clé complète) n'est renvoyé **qu'une seule fois**, dans cette réponse. Il n'est jamais récupérable après coup, même via le tableau de bord — s'il est perdu, générez-en une nouvelle. Copiez-le immédiatement dans votre gestionnaire de secrets.
</Warning>

* `environment` : `"LIVE"` (préfixe `sk_live_`, argent réel) ou `"SANDBOX"` (préfixe `sk_test_`, tests sans argent réel).
* `scope` : `"PAYIN"`, `"PAYOUT"` ou `"BOTH"` (défaut). Une clé `PAYIN` seule ne peut pas initier de retrait, et inversement — limitez le scope d'une clé exposée côté frontend/serveur web à ce qui est strictement nécessaire.

Vous avez maintenant une clé API utilisable pour tous les endpoints décrits dans le reste de cette documentation. Voir [Démarrage rapide](/quickstart) pour votre premier appel.

## Ce qui reste dashboard/JWT uniquement, même après avoir une clé

Une clé API ne peut **jamais** gérer les clés API elles-mêmes (créer, modifier, révoquer — y compris se révoquer elle-même) — voir [Clés API](/api-reference/api-keys) pour l'explication complète de cette restriction volontaire.