API Mobile POS - Spécification détaillée
Ce document décrit l'API REST utilisée par l'application mobile POS (terminal Android).
Authentification
- Sanctum : token Bearer
- L'app envoie le token dans l'en-tête :
Authorization: Bearer {token}
Base URL
https://votredomaine.com/api/mobile
Endpoints
1. Login
POST /api/mobile/auth/login
Connexion avec code boutique, email et mot de passe.
Request (JSON):
{
"shop_code": "B0001",
"email": "caissier@example.com",
"password": "secret"
}
| Champ | Type | Requis | Description |
|---|---|---|---|
| shop_code | string | oui | Code boutique (ex: B0001) |
| string | oui | Email de l'utilisateur | |
| password | string | oui | Mot de passe |
Réponse 200:
{
"token": "1|xxxxxxxxxxxxxxxxxxxx",
"token_type": "Bearer",
"user": {
"id": 1,
"name": "Jean Dupont",
"email": "caissier@example.com"
},
"shop": {
"id": 1,
"name": "Ma Boutique",
"code": "B0001"
}
}
Erreurs:
422: Validation (shop_code invalide, champs manquants)401: Identifiants incorrects403: Utilisateur n'a pas accès à cette boutique / compte désactivé
2. Logout
POST /api/mobile/auth/logout
Révoque le token courant. Requiert authentification.
Réponse 200:
{
"message": "Déconnecté avec succès"
}
3. Statut caisse
GET /api/mobile/cash/status
Retourne l'état de la session de caisse pour la boutique de l'utilisateur.
Session partagée : La session de caisse est stockée en base par boutique. Une session ouverte par un POS mobile ou par l'interface web est visible et utilisable par tous les terminaux (mobiles et web) de la même boutique.
Réponse 200 (session ouverte):
{
"has_open_session": true,
"session": {
"id": 5,
"opening_balance": 50000,
"opened_at": "2026-02-02T08:00:00.000000Z",
"opened_by": "Jean Dupont",
"sales_total": 125000,
"movements_income": 0,
"movements_expense": 5000,
"expected_balance": 170000
}
}
Réponse 200 (aucune session):
{
"has_open_session": false,
"session": null
}
Permissions: cash.view ou cash.open
4. Ouvrir une session de caisse
POST /api/mobile/cash/open
Request (JSON):
{
"opening_balance": 50000
}
| Champ | Type | Requis | Description |
|---|---|---|---|
| opening_balance | number | oui | Montant d'ouverture |
Réponse 200:
{
"message": "Session de caisse ouverte avec succès",
"session": {
"id": 6,
"opening_balance": 50000,
"opened_at": "2026-02-02T10:30:00.000000Z",
"status": "open"
}
}
Erreurs:
400: Une session est déjà ouverte422: Validation (opening_balance requis, min 0)
Permissions: cash.open
5. Fermer une session de caisse
POST /api/mobile/cash/{sessionId}/close
Request (JSON):
{
"closing_balance": 175000,
"notes": "Optionnel"
}
| Champ | Type | Requis | Description |
|---|---|---|---|
| closing_balance | number | oui | Montant de clôture |
| notes | string | non | Notes de fermeture |
Réponse 200:
{
"message": "Session de caisse fermée avec succès",
"session": {
"id": 6,
"closing_balance": 175000,
"expected_balance": 170000,
"difference": 5000,
"closed_at": "2026-02-02T18:00:00.000000Z",
"status": "closed"
}
}
Erreurs:
403: Session n'appartient pas à la boutique400: Session déjà fermée
Permissions: cash.close
6. Produits et catégories (pour le POS)
GET /api/mobile/pos/products
Retourne les produits actifs avec stock > 0, groupés par catégorie.
Query params:
search(optionnel) : recherche par nom ou code
Réponse 200:
{
"categories": [
{
"id": 1,
"name": "Boissons"
}
],
"products": [
{
"id": 10,
"name": "Coca-Cola 33cl",
"code": "COCA33",
"sale_price": 1500,
"stock_quantity": 50,
"category_id": 1,
"category_name": "Boissons",
"variations": []
}
]
}
Permissions: pos.access
7. Finaliser une vente
POST /api/mobile/pos/sales
Request (JSON):
{
"discount": 0,
"payment_method": "cash",
"payment_status": "paid",
"distribution_channel": "boutique",
"paid_amount": 5500,
"customer_id": null,
"items": [
{
"product_id": 10,
"quantity": 2,
"unit_price": 1500,
"total_price": 3000,
"is_half_plate": false,
"product_variation_id": null
}
]
}
| Champ | Type | Requis | Description |
|---|---|---|---|
| discount | number | non | Remise globale (défaut 0) |
| payment_method | string | oui | cash, card, mobile, mixed, debt |
| payment_status | string | oui | paid, partial, unpaid |
| distribution_channel | string | oui | boutique, depot, autres |
| paid_amount | number | oui* | Montant payé (* si payment_status=paid) |
| customer_id | int | non* | Client (* requis si dette) |
| items | array | oui | Lignes du panier |
| items[].product_id | int | oui | ID produit |
| items[].quantity | int | oui | Quantité |
| items[].unit_price | number | oui | Prix unitaire |
| items[].total_price | number | oui | Total de la ligne |
| items[].is_half_plate | bool | non | Demi-plaque (pharmacie) |
| items[].product_variation_id | int | non | ID variation si applicable |
Réponse 200:
{
"message": "Vente enregistrée avec succès",
"sale": {
"id": 42,
"reference": "SAL-ABCD1234",
"total": 5500,
"change_amount": 500,
"items": [...]
}
}
Erreurs:
400: Aucune session de caisse ouverte422: Validation, stock insuffisant, client requis pour dette
Permissions: sales.create (ou pos.access selon config)
8. Historique des ventes récentes
GET /api/mobile/pos/sales/recent
Query params:
limit(optionnel) : nombre max de ventes (défaut 50, max 100)
Réponse 200:
{
"sales": [
{
"id": 42,
"reference": "SAL-ABCD1234",
"total": 5500,
"created_at": "2026-02-06T14:30:00.000000Z",
"user_name": "Jean Dupont",
"items_count": 3
}
],
"currency_symbol": "FC"
}
Permissions: sales.view
9. Données reçu (pour impression)
GET /api/mobile/pos/sales/{id}/receipt
Retourne les données du reçu en JSON (l'app formate pour l'imprimante thermique).
Réponse 200 (format DGI):
{
"sale": {
"id": 42,
"reference": "SAL-ABCD1234",
"created_at": "2026-02-02T14:30:00.000000Z",
"items": [...],
"subtotal": 5000,
"discount": 0,
"tax": 0,
"total": 5000,
"subtotal_ht": 5000,
"tax_rate": 0,
"total_ttc": 5000,
"payment_method": "cash",
"paid_amount": 5500,
"change_amount": 500
},
"shop": {
"name": "Ma Boutique",
"address": "123 Rue Principale, Kinshasa",
"rccm": "CD/KIN/123-A-12345",
"nif": "CD/KIN/RCC/123-A-12345",
"phone": "+243...",
"email": "boutique@..."
},
"currency_symbol": "FC",
"dgi_format": true
}
Facture normalisée DGI : Configurez RCCM et NIF dans Paramètres > Général pour que les reçus incluent les mentions obligatoires.
Permissions: sales.view
10. Ticket général (données pour impression)
GET /api/mobile/reports/general-ticket
Query params:
date_from(optionnel) : YYYY-MM-DD (défaut : début du mois)date_to(optionnel) : YYYY-MM-DD (défaut : aujourd'hui)user_id(optionnel) : filtrer par caissiergroup_by(optionnel) : category, user, payment_method, distribution_channel, day
Réponse 200:
{
"date_from": "2026-02-01",
"date_to": "2026-02-02",
"total_sales": 250000,
"total_items": 150,
"total_tickets": 45,
"grouped_data": [...],
"shop": {
"name": "Ma Boutique"
},
"currency_symbol": "FC"
}
Permissions: reports.general-ticket
Paramètres boutique (settings)
GET /api/mobile/settings
Retourne les paramètres utiles pour le POS (devise, méthodes de paiement, etc.).
Réponse 200:
{
"currency": "CDF",
"currency_symbol": "FC",
"tax_rate": 0,
"enable_cash": true,
"enable_card": true,
"enable_mobile_money": false
}
Permissions: pos.access
Codes d'erreur HTTP
| Code | Signification |
|---|---|
| 200 | Succès |
| 400 | Requête invalide |
| 401 | Non authentifié (token manquant/invalide) |
| 403 | Accès interdit (permission) |
| 404 | Ressource non trouvée |
| 422 | Erreur de validation |
| 500 | Erreur serveur |
Exemple de flux complet
- Login :
POST /api/mobile/auth/login→ récupérer le token - Stockage : sauvegarder le token (SecureStorage)
- Caisse :
GET /api/mobile/cash/status→ si pas de session,POST /api/mobile/cash/open - POS :
GET /api/mobile/pos/products→ afficher le catalogue - Vente :
POST /api/mobile/pos/sales→ récupérer sale.id - Impression :
GET /api/mobile/pos/sales/{id}/receipt→ imprimer le reçu - Fin de journée :
POST /api/mobile/cash/{sessionId}/close - Ticket général :
GET /api/mobile/reports/general-ticket→ imprimer le rapport