API mobile POS

Lien isolé Accueil docs Formation
Mobile POS

Endpoints API mobile : auth, sync, ventes, caisse, catalogue.

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)
email 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 incorrects
  • 403 : 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à ouverte
  • 422 : 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 boutique
  • 400 : 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 ouverte
  • 422 : 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 caissier
  • group_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

  1. Login : POST /api/mobile/auth/login → récupérer le token
  2. Stockage : sauvegarder le token (SecureStorage)
  3. Caisse : GET /api/mobile/cash/status → si pas de session, POST /api/mobile/cash/open
  4. POS : GET /api/mobile/pos/products → afficher le catalogue
  5. Vente : POST /api/mobile/pos/sales → récupérer sale.id
  6. Impression : GET /api/mobile/pos/sales/{id}/receipt → imprimer le reçu
  7. Fin de journée : POST /api/mobile/cash/{sessionId}/close
  8. Ticket général : GET /api/mobile/reports/general-ticket → imprimer le rapport