# 🤖 API Reference & Guide : KYC & Marchands (Frontend Integration)

Ce document fournit les détails techniques exacts (Routes, Paramètres, Réponses) pour l'intégration complète du flux marchand et KYC.

---

## 🛠️ 1. GESTION DU PROFIL MARCHAND

Définit l'identité de la boutique. Accessible dès l'inscription.

### Mettre à jour le profil

- **URL** : `PUT /api/merchants/profile`
- **Body (JSON)** :

```json
{
  "business_name": "Ma Super Boutique",
  "business_description": "Vente de vêtements",
  "business_website": "https://monsite.com",
  "business_address": "RUE 123, Douala",
  "business_city": "Douala",
  "facebook_url": "https://facebook.com/mapage",
  "instagram_url": "https://instagram.com/moninsta",
  "twitter_url": "https://x.com/moncompte",
  "linkedin_url": "https://linkedin.com/in/monprofil",
  "other_links": {
    "tiktok": "https://tiktok.com/@moncompte"
  }
}
```

- **Réponse (200)** : `{"success": true, "data": { "merchant": { ...user_object } }}`

---

## 👤 2. KYC IDENTITÉ (UTILISATEUR)

Pour débloquer les retraits (Limite de base: 50 000 XAF pour les non-vérifiés).

### Vérifier par CNI (ID Card)

- **URL** : `POST /api/kyc/verify/id-card`
- **Format** : `multipart/form-data`
- **Champs** :
  - `front_image` (File) : Recto.
  - `back_image` (File) : Verso.
  - `selfie_image` (File) : Selfie avec la carte.
  - `document_number` (String) : Numéro de la pièce.

### Vérifier par Passeport

- **URL** : `POST /api/kyc/verify/passport`
- **Format** : `multipart/form-data`
- **Champs** :
  - `front_image` (File) : Page photo.
  - `selfie_image` (File) : Selfie avec le passeport.

---

## 🏢 3. CERTIFICATION BUSINESS (MARCHAND)

Pour passer de "Marchand" à "Marchand Certifié" (Unlimited).

### Soumettre le RCCM

- **URL** : `POST /api/kyc/merchant/business-registration`
- **Format** : `multipart/form-data`
- **Champs** :
  - `registration_number` (String) : N° Registre.
  - `business_name` (String) : Nom légal.
  - `document_image` (File) : Scan du certificat.

### Soumettre le NIU (Fiscalité)

- **URL** : `POST /api/kyc/merchant/tax-certificate`
- **Format** : `multipart/form-data`
- **Champs** :
  - `tax_number` (String) : Numéro Identifiant Unique.
  - `document_image` (File) : Attestation.
  - `expiry_date` (Date, format YYYY-MM-DD).

---

## 🔍 4. VÉRIFICATION DES STATUTS & LIMITES

### Statut KYC Global (L'indicateur principal)

- **URL** : `GET /api/kyc/status`
- **Réponse (200)** :

```json
{
  "success": true,
  "data": {
    "kyc_status": "pending", // not_submitted, pending, verified, rejected
    "verification_level": "pending_verification",
    "can_withdraw": true, // Utilisable pour RR/OM/MTN
    "max_withdrawal": 50000.0, // Limite calculée selon KYC
    "max_transfer": 50000.0,
    "requirements": {
        "id_document_verified": false,
        "selfie_verified": false,
        "next_step": "wait_for_verification"
    }
  }
}
```

---

## 🔑 5. GESTION DES CLÉS API

Accessible pour `user.role === 'merchant'` (pas besoin de certification RCCM).

### Créer une nouvelle clé

- **URL** : `POST /api/integrations/keys`
- **Réponse (201)** :

```json
{
  "success": true,
  "data": {
    "api_key": "pk_...",
    "api_secret": "sk_...", // AFFICHER UNE SEULE FOIS !
  }
}
```

---

## 💰 6. RETRAITS (WITHDRAWALS)

### Calculer les frais avant envoi

- **URL** : `GET /api/withdrawals/fees-calculator?amount=1000&operator=mtn_money`

### Initier une demande

- **URL** : `POST /api/withdrawals/request`
- **Body (JSON)** : `{"amount": 1000, "phone_number": "6...", "operator": "mtn_money"}`
- **Réponse** : Retourne un `withdrawal_id`. Un code SMS est envoyé.

### Valider la demande (OTP SMS)

- **URL** : `POST /api/withdrawals/{id}/validate`
- **Body (JSON)** : `{"code": "123456"}`

---

## 🔗 7. LIENS DE PAIEMENT

Accessibles à TOUT utilisateur authentifié.

### Créer un lien

- **URL** : `POST /api/merchant/payment-links`
- **Body (JSON)** : `{"title": "...", "amount": 500, "currency": "XAF"}`