📚 Documentation Postman - Nelsius Pay API
🌐 Configuration de base
Variables d'environnement Postman
Crée un environnement nommé "Nelsius Pay - Local" avec :

text
base_url: http://localhost:8000
token: (laissé vide, sera automatiquement rempli)
user_email: votre@email.com
user_password: VotreMotDePasse
🔐 ENDPOINTS D'AUTHENTIFICATION
1. Inscription
Méthode : POST

URL : {{base_url}}/api/auth/register

Headers :

text
Content-Type: application/json
Body (JSON) :

json
{
    "nom": "Kamga",
    "prenom": "Jean",
    "email": "jean.kamga@test.com",
    "phone": "+237699887766",
    "password": "Test@1234",
    "password_confirmation": "Test@1234",
    "role": "user"
}
Réponse attendue (201 Created) :

json
{
    "success": true,
    "message": "Inscription réussie. Veuillez vérifier votre email.",
    "data": {
        "user": {
            "id": 2,
            "nom": "Kamga",
            "prenom": "Jean",
            "email": "jean.kamga@test.com",
            "phone": "+237699887766",
            "role": "user",
            "email_verified": false,
            "kyc_status": "pending",
            "is_active": true,
            "two_factor_enabled": false,
            "last_login": null,
            "created_at": "2025-12-05T10:00:00.000000Z",
            "updated_at": "2025-12-05T10:00:00.000000Z"
        }
    }
}
Test Postman (à ajouter dans Tests) :

javascript
// Sauvegarder l'email pour les tests suivants
pm.environment.set("user_email", pm.response.json().data.user.email);
pm.environment.set("user_id", pm.response.json().data.user.id);
console.log("Utilisateur créé avec ID: " + pm.response.json().data.user.id);
2. Connexion
Méthode : POST

URL : {{base_url}}/api/auth/login

Headers :

text
Content-Type: application/json
Body (JSON) :

json
{
    "email": "{{user_email}}",
    "password": "Test@1234",
    "device_name": "Postman Desktop"
}
Réponse attendue (200 OK) :

json
{
    "success": true,
    "message": "Connexion réussie.",
    "data": {
        "user": { ... },
        "tokens": {
            "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
            "refresh_token": "abc123def456ghi789...",
            "token_type": "bearer",
            "expires_in": 3600,
            "refresh_expires_in": 86400
        }
    }
}
Test Postman (à ajouter dans Tests) :

javascript
// Sauvegarder le token pour les requêtes suivantes
const token = pm.response.json().data.tokens.access_token;
pm.environment.set("token", token);

// Vérifier que le token est présent
pm.test("Token reçu", function() {
    pm.expect(token).to.not.be.empty;
});

// Vérifier la structure de la réponse
pm.test("Structure de réponse correcte", function() {
    pm.expect(pm.response.json().success).to.be.true;
    pm.expect(pm.response.json().data).to.have.property('tokens');
    pm.expect(pm.response.json().data.tokens).to.have.property('access_token');
    pm.expect(pm.response.json().data.tokens).to.have.property('refresh_token');
});
3. Profil utilisateur (protégé)
Méthode : GET

URL : {{base_url}}/api/auth/me

Headers :

text
Authorization: Bearer {{token}}
Content-Type: application/json
Réponse attendue (200 OK) :

json
{
    "success": true,
    "message": "Informations utilisateur récupérées.",
    "data": {
        "user": {
            "id": 2,
            "nom": "Kamga",
            "prenom": "Jean",
            "email": "jean.kamga@test.com",
            "phone": "+237699887766",
            "role": "user",
            "email_verified": false,
            "kyc_status": "pending",
            "is_active": true,
            "two_factor_enabled": false,
            "last_login": "2025-12-05T10:05:00.000000Z",
            "created_at": "2025-12-05T10:00:00.000000Z",
            "updated_at": "2025-12-05T10:05:00.000000Z"
        }
    }
}
Test Postman :

javascript
// Vérifier que l'utilisateur est correct
pm.test("Utilisateur connecté", function() {
    pm.expect(pm.response.json().data.user.email).to.equal(pm.environment.get("user_email"));
    pm.expect(pm.response.json().data.user.id).to.equal(parseInt(pm.environment.get("user_id")));
});
4. Déconnexion (protégé)
Méthode : POST

URL : {{base_url}}/api/auth/logout

Headers :

text
Authorization: Bearer {{token}}
Content-Type: application/json
Réponse attendue (200 OK) :

json
{
    "success": true,
    "message": "Déconnexion réussie."
}
Test Postman :

javascript
// Après déconnexion, supprimer le token
pm.environment.unset("token");
pm.test("Déconnexion réussie", function() {
    pm.expect(pm.response.json().success).to.be.true;
});
5. Rafraîchissement de token
Méthode : POST

URL : {{base_url}}/api/auth/refresh

Headers :

text
Content-Type: application/json
Body (JSON) :

json
{
    "refresh_token": "{{refresh_token}}"
}
Note : Le refresh_token doit être sauvegardé après la connexion

6. Vérification d'email
Méthode : POST

URL : {{base_url}}/api/auth/email/verify

Headers :

text
Content-Type: application/json
Body (JSON) :

json
{
    "code": "ABC123"  // Code reçu par email
}
7. Renvoyer l'email de vérification
Méthode : POST

URL : {{base_url}}/api/auth/email/resend

Headers :

text
Content-Type: application/json
Body (JSON) :

json
{
    "email": "{{user_email}}"
}
8. Réinitialisation de mot de passe - Demande
Méthode : POST

URL : {{base_url}}/api/auth/password/request

Headers :

text
Content-Type: application/json
Body (JSON) :

json
{
    "email": "{{user_email}}"
}
9. Réinitialisation de mot de passe - Confirmation
Méthode : POST

URL : {{base_url}}/api/auth/password/reset

Headers :

text
Content-Type: application/json
Body (JSON) :

json
{
    "token": "token_reçu_par_email",
    "password": "Nouveau@1234",
    "password_confirmation": "Nouveau@1234"
}
10. Connexion Google - Redirection
Méthode : GET

URL : {{base_url}}/api/auth/google/redirect

Réponse attendue :

json
{
    "success": true,
    "message": "Redirection vers Google.",
    "data": {
        "redirect_url": "https://accounts.google.com/o/oauth2/auth?..."
    }
}
11. Connexion Google - Callback
Méthode : GET

URL : {{base_url}}/api/auth/google/callback?code=CODE_GOOGLE

Note : Cette URL est appelée automatiquement par Google après authentification

📁 Collection Postman à importer
JSON de la collection :
json
{
  "info": {
    "_postman_id": "nelsius-pay-auth",
    "name": "Nelsius Pay - Authentication",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Inscription",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n    \"nom\": \"Kamga\",\n    \"prenom\": \"Jean\",\n    \"email\": \"jean.kamga@test.com\",\n    \"phone\": \"+237699887766\",\n    \"password\": \"Test@1234\",\n    \"password_confirmation\": \"Test@1234\",\n    \"role\": \"user\"\n}"
        },
        "url": {
          "raw": "{{base_url}}/api/auth/register",
          "host": ["{{base_url}}"],
          "path": ["api", "auth", "register"]
        }
      },
      "response": []
    },
    {
      "name": "Connexion",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n    \"email\": \"{{user_email}}\",\n    \"password\": \"Test@1234\",\n    \"device_name\": \"Postman Desktop\"\n}"
        },
        "url": {
          "raw": "{{base_url}}/api/auth/login",
          "host": ["{{base_url}}"],
          "path": ["api", "auth", "login"]
        }
      },
      "response": []
    },
    {
      "name": "Profil utilisateur",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{token}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}/api/auth/me",
          "host": ["{{base_url}}"],
          "path": ["api", "auth", "me"]
        }
      },
      "response": []
    },
    {
      "name": "Déconnexion",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{token}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}/api/auth/logout",
          "host": ["{{base_url}}"],
          "path": ["api", "auth", "logout"]
        }
      },
      "response": []
    }
  ],
  "variable": [
    {
      "key": "base_url",
      "value": "http://localhost:8000"
    },
    {
      "key": "token",
      "value": ""
    },
    {
      "key": "user_email",
      "value": "jean.kamga@test.com"
    }
  ]
}
🎯 Flux de test recommandé
Test 1 : Flux complet utilisateur
Inscription → Vérifie que l'utilisateur est créé

Vérifier dans Mailtrap → Code de vérification

Connexion → Récupère les tokens

/me → Vérifie que le token fonctionne

Déconnexion → Vérifie que le token est blacklisté

/me après déco → Devrait échouer (401)

Test 2 : Gestion des erreurs
bash
# Tentative avec mauvais mot de passe
POST /api/auth/login
{"email": "test@test.com", "password": "wrong"}

# Tentative avec email non vérifié
POST /api/auth/login 
{"email": "nonverifie@test.com", "password": "..."}

# Tentative avec token expiré
GET /api/auth/me
Authorization: Bearer expired_token
Test 3 : Tests de sécurité
bash
# Tentatives multiples de connexion (rate limiting)
# Connexion depuis différentes IP
# Token blacklisté après déconnexion
# Refresh token révoqué après changement de mot de passe
📊 Scripts Postman utiles
Pré-request Script (pour automatiser) :
javascript
// Générer un email unique pour chaque test
const timestamp = new Date().getTime();
const uniqueEmail = `test${timestamp}@nelsiuspay.com`;
pm.environment.set("unique_email", uniqueEmail);
Test Script (pour valider) :
javascript
// Valider la structure de réponse JWT
pm.test("Response is JSON", function () {
    pm.response.to.have.header("Content-Type");
    pm.response.to.be.json;
});

pm.test("Response has success status", function () {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property("success");
    pm.expect(jsonData).to.have.property("message");
    pm.expect(jsonData).to.have.property("data");
});

// Vérifier les codes HTTP
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});
🔍 Vérification des logs pendant les tests
Pendant que tu testes avec Postman, ouvre un terminal pour voir les logs :

bash
# Terminal 1 : Voir les logs Laravel
tail -f storage/logs/laravel.log

# Terminal 2 : Voir les requêtes SQL
php artisan tinker
>>> DB::listen(function($sql) { echo $sql->sql . "\n"; });
📱 Variables d'environnement Postman
Crée ce fichier JSON et importe-le dans Postman :

nelsius-pay-env.json :

json
{
  "id": "nelsius-pay-env",
  "name": "Nelsius Pay - Local",
  "values": [
    {
      "key": "base_url",
      "value": "http://localhost:8000",
      "type": "default",
      "enabled": true
    },
    {
      "key": "token",
      "value": "",
      "type": "default",
      "enabled": true
    },
    {
      "key": "user_email",
      "value": "test@example.com",
      "type": "default",
      "enabled": true
    },
    {
      "key": "user_password",
      "value": "Test@1234",
      "type": "default",
      "enabled": true
    }
  ],
  "_postman_variable_scope": "environment",
  "_postman_exported_at": "2025-12-05T10:00:00.000Z",
  "_postman_exported_using": "Postman/10.0.0"
}
🚀 Tests rapides via cURL (alternative)
Si tu préfères cURL :

bash
# Inscription
curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"nom":"Test","prenom":"User","email":"test@example.com","password":"Test@1234","password_confirmation":"Test@1234"}'

# Connexion et sauvegarde du token
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"Test@1234"}' \
  | jq -r '.data.tokens.access_token' > token.txt

# Utiliser le token
TOKEN=$(cat token.txt)
curl -X GET http://localhost:8000/api/auth/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
📝 Checklist de test
Inscription : Création utilisateur + portefeuille

Email : Reçu dans Mailtrap

Connexion : Token JWT généré

Middleware : Route /me protégée

Déconnexion : Token blacklisté

Refresh : Nouveau token généré

Vérification email : Statut mis à jour

Réinitialisation MDP : Email envoyé + MDP changé

Sécurité : Logs dans security_events