Documentation API KOPA

Vérifie l'état du serveur et de la base de données.

Réponse 200

{
    "status": "ok",
    "database": "connected",
    "timestamp": "2026-01-15T10:30:00Z"
}

Inscription d'un nouvel utilisateur. Envoie un OTP par SMS pour vérification du téléphone.

Request Body

{
    "phone": "+2250708091011",
    "nom": "Kouassi",
    "prenom": "Jean",
    "email": "jean@example.com",
    "password": "secret123",
    "role": "client"
}

Champs requis : phone (format +242…), password (min 8), nom. role optionnel : client (défaut) ou consommateur uniquement.

Réponse 201

{
    "message": "Inscription réussie. Un code de vérification a été envoyé par SMS.",
    "user": { "id": "uuid", "phone": "+24206123456", "role": "client", "verified": false }
}

Vérifie le code OTP reçu par SMS et active le compte.

Request Body

{
    "phone": "+2250708091011",
    "code": "123456"
}

Réponse 200

{
    "message": "Téléphone vérifié",
    "token": "1|abcDEFghiJKLmnoPQRstuvwxyz..."
}

Renvoie un nouveau code OTP par SMS.

Request Body

{
    "phone": "+2250708091011"
}

Réponse 200

{
    "message": "OTP renvoyé"
}

Connexion. Retourne un token Sanctum si les identifiants sont valides et le téléphone vérifié.

Request Body

{
    "phone": "+2250708091011",
    "password": "secret123"
}

Réponse 200

{
    "message": "Connexion réussie",
    "token": "1|abcDEFghiJKLmnoPQRstuvwxyz...",
    "user": { "id": 1, "nom": "Kouassi", "prenom": "Jean", "role": "client" }
}

Révoque le token d'authentification actuel.

Réponse 200

{
    "message": "Déconnecté"
}

Achat express — permet au consommateur final de commander directement via QR code produit.

Request Body

{
    "qr_code": "KOPA-PRD-ABC123",
    "quantite": 5,
    "mode_paiement": "mobile_money"
}

Réponse 201

{
    "message": "Commande créée",
    "commande": { "id": 42, "montant_total": 7500, "statut": "en_attente" }
}

Webhook de callback pour les fournisseurs de paiement (Orange Money, MTN MoMo, Wave, etc.). Le provider est validé via une signature HMAC.

Paramètres

Request Body (exemple Orange Money)

{
    "status": "SUCCESS",
    "transaction_id": "OM-20260115-001",
    "amount": 15000,
    "external_id": "CMD-42"
}

Réponse 200

{
    "received": true
}

Tableau de bord admin avec KPIs globaux.

Réponse 200

{
    "total_users": 1247,
    "total_producteurs": 89,
    "total_microcentres": 156,
    "total_commandes": 3420,
    "chiffre_affaires": 45600000,
    "commandes_en_cours": 47,
    "nouveaux_utilisateurs_ce_mois": 34
}

Crée un compte producteur.

Request Body

{
    "nom": "Aka",
    "prenom": "Moussa",
    "phone": "+2250708091012",
    "email": "moussa@farm.ci",
    "password": "secure456",
    "localisation": "Yamoussoukro",
    "description": "Producteur de manioc"
}

Réponse 201

{
    "message": "Producteur créé",
    "user": { "id": 101, "nom": "Aka", "prenom": "Moussa", "role": "producteur" }
}

Crée un compte micro-centre.

Request Body

{
    "nom": "Boutique Aya",
    "prenom": "Fatou",
    "phone": "+2250506070809",
    "email": "aya@boutique.ci",
    "password": "secure789",
    "localisation": "Abobo, Abidjan",
    "description": "Micro-centre alimentaire"
}

Liste paginée de tous les utilisateurs. Filtres optionnels : role, search, active.

Query Parameters

?role=producteur&search=Kouassi&active=1&page=1&per_page=20

Réponse 200

{
    "data": [
        { "id": "uuid", "nom": "Kouassi", "prenom": "Jean", "phone": "+24206123456", "role": "client", "active": true, "verified": true }
    ],
    "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
    "meta": { "current_page": 1, "last_page": 62, "per_page": 20, "total": 1247 }
}

Modifie un utilisateur. Champs acceptés : nom, active, verified, role. Le changement de rôle n'est pas possible sur son propre compte, et le passage hors de client_secondaire supprime le lien employé et ses permissions.

Request Body

{
    "nom": "Kouassi",
    "active": false,
    "role": "producteur"
}

Supprime un utilisateur.

Réponse 200

{
    "message": "Utilisateur supprimé"
}

Liste paginée de toutes les commandes. Filtres : statut, date_debut, date_fin.

Réponse 200

{
    "data": [
        {
            "id": 42,
            "client": { "id": 1, "nom": "Kouassi", "prenom": "Jean" },
            "micro_centre": { "id": 5, "nom": "Boutique Aya" },
            "montant_total": 15000,
            "statut": "en_attente",
            "paiement_statut": "en_attente",
            "created_at": "2026-01-15T10:30:00Z"
        }
    ],
    "meta": { "current_page": 1, "last_page": 171, "per_page": 20, "total": 3420 }
}

Détail complet d'une commande.

Réponse 200

{
    "id": 42,
    "client": { "id": 1, "nom": "Kouassi", "prenom": "Jean", "phone": "+2250708091011" },
    "micro_centre": { "id": 5, "nom": "Boutique Aya" },
    "items": [
        { "produit": { "nom": "Manioc", "unite": "kg" }, "quantite": 10, "prix_unitaire": 1500 }
    ],
    "montant_total": 15000,
    "statut": "en_attente",
    "pin": "1234",
    "paiement": { "statut": "en_attente", "provider": "orange_money" },
    "livraison": null,
    "created_at": "2026-01-15T10:30:00Z"
}

Force le statut d'une commande (admin override).

Request Body

{
    "statut": "livree",
    "motif": "Confirmation téléphonique du client"
}

Débloque le PIN de réception d'une commande (en cas de oubli/erreur).

Réponse 200

{
    "message": "PIN débloqué",
    "pin": "1234"
}

Génère un rapport. Types : ventes, performances, stocks, satisfaction, delais.

Query Parameters

?periode_debut=2026-01-01&periode_fin=2026-01-31

Réponse 200

{
    "type": "ventes",
    "periode": { "debut": "2026-01-01", "fin": "2026-01-31" },
    "total_ventes": 342,
    "chiffre_affaires": 45600000,
    "top_produits": [ ... ],
    "evolution_quotidienne": [ ... ]
}

Réponse 200

{
    "total_commandes": 24,
    "commandes_en_cours": 3,
    "montant_total_depense": 360000,
    "points_fidelite": 1200,
    "derniere_commande": { "id": 42, "statut": "en_transit", "montant_total": 15000 }
}

Catalogue des produits disponibles. Filtres : categorie, search, microcentre_id.

Réponse 200

{
    "data": [
        {
            "id": 10,
            "nom": "Manioc premium",
            "categorie": "tubercules",
            "prix_unitaire": 1500,
            "unite": "kg",
            "stock_disponible": 250,
            "producteur": { "id": 101, "nom": "Aka Moussa" },
            "micro_centre": { "id": 5, "nom": "Boutique Aya" },
            "promotion": { "remise_pct": 10, "prix_remise": 1350 }
        }
    ],
    "meta": { "current_page": 1, "last_page": 5, "total": 98 }
}

Crée une nouvelle commande.

Request Body

{
    "micro_centre_id": 5,
    "items": [
        { "produit_id": 10, "quantite": 10 },
        { "produit_id": 12, "quantite": 5 }
    ],
    "mode_paiement": "mobile_money",
    "adresse_livraison": "Abobo PK18, Abidjan",
    "utiliser_points_fidelite": false
}

Réponse 201

{
    "message": "Commande créée",
    "commande": { "id": 43, "montant_total": 22500, "pin": "5678", "statut": "en_attente_paiement" }
}

Historique des commandes du client. Filtre : statut.

Réponse 200

{
    "data": [
        { "id": 42, "montant_total": 15000, "statut": "livree", "created_at": "2026-01-10T08:00:00Z" },
        { "id": 43, "montant_total": 22500, "statut": "en_transit", "created_at": "2026-01-15T10:30:00Z" }
    ],
    "meta": { "current_page": 1, "last_page": 2, "total": 24 }
}

Détail d'une commande client.

Suivi en temps réel d'une commande.

Réponse 200

{
    "commande_id": 42,
    "statut": "en_transit",
    "livreur": { "nom": "Bamba", "phone": "+2250102030405" },
    "position_actuelle": { "lat": 5.3600, "lng": -4.0083 },
    "etapes": [
        { "statut": "commande_recue", "date": "2026-01-15T10:30:00Z" },
        { "statut": "paiement_confirmé", "date": "2026-01-15T10:31:00Z" },
        { "statut": "en_preparation", "date": "2026-01-15T10:35:00Z" },
        { "statut": "en_transit", "date": "2026-01-15T11:00:00Z" }
    ]
}

Confirme la réception de la commande en entrant le PIN.

Request Body

{
    "pin": "5678"
}

Liste des employés du client.

Réponse 200

{
    "data": [
        { "id": 201, "nom": "Traore", "prenom": "Aminata", "phone": "+2250707060504", "permissions": ["view_catalogue", "create_commande"], "active": true }
    ]
}

Ajoute un employé au compte client.

Request Body

{
    "nom": "Traore",
    "prenom": "Aminata",
    "phone": "+2250707060504",
    "email": "aminata@boutique.ci",
    "password": "emp123456",
    "permissions": ["view_catalogue", "create_commande"]
}

Request Body

{
    "permissions": ["view_catalogue", "create_commande", "view_commandes", "view_historique"]
}

Désactive le compte d'un employé.

Réactive le compte d'un employé.

Historique complet des transactions et interactions.

Réponse 200

{
    "points_disponibles": 1200,
    "points_utilises": 800,
    "historique": [
        { "type": "gain", "points": 150, "description": "Commande #42", "date": "2026-01-10T08:00:00Z" },
        { "type": "utilisation", "points": -200, "description": "Réduction appliquée", "date": "2026-01-12T14:00:00Z" }
    ]
}

Utilise des points de fidélité sur une commande.

Request Body

{
    "commande_id": 43,
    "points": 500
}

Réponse 200

{
    "total_produits": 12,
    "total_ventes_mois": 245,
    "chiffre_affaires_mois": 6780000,
    "produits_alerte_stock": 3,
    "derniere_commande": { "id": 42, "produit": "Manioc", "quantite": 100 }
}

Réponse 200

{
    "data": [
        { "id": 10, "nom": "Manioc premium", "categorie": "tubercules", "prix_unitaire": 1500, "unite": "kg", "stock": 250, "is_disponible": true, "qr_code": "KOPA-PRD-ABC123" }
    ]
}

Request Body

{
    "nom": "Manioc premium",
    "description": "Manioc de qualité supérieure, récolte fraîche",
    "categorie": "tubercules",
    "prix_unitaire": 1500,
    "unite": "kg",
    "stock": 250,
    "seuil_alerte": 20
}

Modifie un produit existant.

Request Body

{
    "prix_unitaire": 1800,
    "is_disponible": false
}

Supprime un produit.

Statistiques détaillées du producteur.

Réponse 200

{
    "ventes_par_mois": [ { "mois": "2026-01", "total": 245, "chiffre_affaires": 6780000 } ],
    "produits_plus_vendus": [ { "nom": "Manioc", "vendus": 120 } ],
    "taux_rupture_stock": 8.5,
    "nombre_microcentres_partenaires": 12
}

Retourne la chaîne de traçabilité complète d'un produit via son QR code.

Réponse 200

{
    "qr_code": "KOPA-PRD-ABC123",
    "produit": { "nom": "Manioc premium", "categorie": "tubercules" },
    "producteur": { "nom": "Aka Moussa", "localisation": "Yamoussoukro" },
    "date_recolte": "2026-01-10",
    "micro_centres": [
        { "nom": "Boutique Aya", "date_reception": "2026-01-11", "quantite": 100 }
    ],
    "derniere_mise_a_jour": "2026-01-15T10:30:00Z"
}

Alertes de stock bas et commandes en attente.

Réponse 200

{
    "stock_bas": [
        { "produit_id": 10, "nom": "Manioc", "stock_actuel": 15, "seuil": 20 }
    ],
    "commandes_en_attente": 3
}

Réponse 200

{
    "data": [
        { "id": 1, "produit": { "nom": "Manioc" }, "remise_pct": 10, "date_debut": "2026-01-15", "date_fin": "2026-01-31", "active": true }
    ]
}

Request Body

{
    "produit_id": 10,
    "remise_pct": 10,
    "date_debut": "2026-01-15",
    "date_fin": "2026-01-31"
}

Supprime une promotion.

Réponse 200

{
    "data": [
        { "id": 5, "produit": { "id": 10, "nom": "Manioc" }, "quantite": 200, "seuil_alerte": 20, "statut": "ok" }
    ],
    "alertes_stock": 2
}

Ajuste le stock d'un produit (+entrée ou -sortie).

Request Body

{
    "produit_id": 10,
    "quantite": 50,
    "type": "entree",
    "motif": "Réception depuis producteur"
}

Modifie le seuil d'alerte d'un stock.

Request Body

{
    "seuil_alerte": 30
}

Historique des mouvements de stock.

Réponse 200

{
    "data": [
        { "produit": "Manioc", "type": "entree", "quantite": 50, "date": "2026-01-15T08:00:00Z", "motif": "Réception producteur" },
        { "produit": "Manioc", "type": "sortie", "quantite": 10, "date": "2026-01-15T14:00:00Z", "motif": "Commande #42" }
    ]
}

Commandes associées au micro-centre. Filtre : statut.

Détail d'une commande pour le micro-centre.

Confirme la réception de la commande par le micro-centre.

Passe la commande en statut "en préparation".

Request Body

{
    "livreur_id": 301
}

Request Body

{
    "motif": "Stock insuffisant"
}

Ajoute un livreur au micro-centre.

Request Body

{
    "nom": "Bamba",
    "prenom": "Ibrahim",
    "phone": "+2250102030405",
    "email": "ibrahim@livraison.ci",
    "password": "liv123456"
}

Réponse 200

{
    "data": [
        { "id": "uuid", "nom": "Bamba Ibrahim", "phone": "+24206123456", "active": true, "missions_en_cours": 2 }
    ]
}

Active/Désactive un livreur.

Réponse 200

{
    "missions_en_cours": 2,
    "missions_terminees_jour": 5,
    "missions_totales": 234,
    "taux_reussite": 97.5
}

Réponse 200

{
    "data": [
        {
            "id": 42,
            "client": { "nom": "Kouassi Jean", "phone": "+2250708091011" },
            "adresse": "Abobo PK18, Abidjan",
            "montant_total": 15000,
            "statut": "en_transit",
            "pin": "5678",
            "created_at": "2026-01-15T10:30:00Z"
        }
    ]
}

Marque la livraison comme effectuée. La validation finale nécessite le PIN client.

Réponse 200

{
    "message": "Livraison effectuée, en attente de validation PIN",
    "statut": "livraison_effectuee"
}

Historique des livraisons passées.

Valide la livraison avec le PIN fourni par le client.

Request Body

{
    "pin": "5678"
}

Réponse 200

{
    "message": "Livraison confirmée",
    "statut": "livree"
}

Initie un paiement pour une commande via mobile money.

Request Body

{
    "commande_id": 42,
    "provider": "orange_money",
    "phone": "+2250708091011",
    "montant": 15000
}

Réponse 201

{
    "message": "Paiement initié",
    "transaction_id": "TXN-20260115-001",
    "statut": "en_attente",
    "redirect_url": "https://checkout.orange.com/..."
}

Vérifie le statut d'une transaction.

Réponse 200

{
    "transaction_id": "TXN-20260115-001",
    "statut": "succes",
    "montant": 15000,
    "provider": "orange_money",
    "date_confirmation": "2026-01-15T10:32:00Z"
}

Retourne les informations de paiement d'une commande.

Réponse 200

{
    "commande_id": 42,
    "transaction_id": "TXN-20260115-001",
    "montant": 15000,
    "provider": "orange_money",
    "statut": "succes"
}

Crée un ticket de support.

Request Body

{
    "titre": "Commande non reçue",
    "description": "La commande #42 n'a toujours pas été livrée après 48h.",
    "type": "commande",
    "priorite": "haute",
    "commande_id": 42
}

Réponse 201

{
    "message": "Ticket créé",
    "ticket": { "id": 1, "titre": "Commande non reçue", "statut": "ouvert", "priorite": "haute" }
}

Liste des tickets. Filtres : statut, priorite, type.

Réponse 200

{
    "data": [
        { "id": 1, "titre": "Commande non reçue", "type": "commande", "priorite": "haute", "statut": "ouvert", "created_by": { "nom": "Kouassi Jean" }, "created_at": "2026-01-15T10:30:00Z" }
    ],
    "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Réponse 200

{
    "id": 1,
    "titre": "Commande non reçue",
    "description": "La commande #42 n'a toujours pas été livrée après 48h.",
    "type": "commande",
    "priorite": "haute",
    "statut": "ouvert",
    "created_by": { "id": 1, "nom": "Kouassi Jean" },
    "commentaires": [
        { "id": 1, "auteur": { "nom": "Admin" }, "contenu": "Nous vérifions avec le micro-centre.", "created_at": "2026-01-15T11:00:00Z" }
    ],
    "created_at": "2026-01-15T10:30:00Z"
}

Request Body

{
    "contenu": "Le livreur est en route, arrivée prévue dans 30 minutes."
}

Met à jour le statut ou la priorité d'un ticket.

Request Body

{
    "statut": "resolu",
    "priorite": "normale"
}

Réponse 200

{
    "total_tickets": 45,
    "ouverts": 8,
    "en_cours": 12,
    "resolus": 25,
    "temps_moyen_resolution_h": 4.2
}