Li-Zo - Plateforme de Livraison

Introduction

L'API Lizo Delivery vous permet d'intégrer nos services de livraison dans vos applications. Cette documentation vous guide à travers l'authentification, les endpoints disponibles et des exemples d'utilisation.

🚀 Démarrage Rapide

1. Authentification - Obtenez votre token d'accès
2. Simulation - Estimez le prix et la durée de livraison
3. Création - Créez une course de livraison
4. Suivi - Suivez la livraison en temps réel

Authentification

URLs de Base

URL API Development: https://hub.lizoworld.com

URL API Production: Non disponible pour le moment

Headers Requis

Accept: application/json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Important: Contactez notre équipe technique pour obtenir vos identifiants d'accès. Votre token doit être inclus dans toutes les requêtes API et expire après 24 heures.

Endpoints API

1 Mise à jour du délai de validation (Profil partenaire)

PUT /api/partner-profile/validation-delay

Description: Met à jour le délai de validation (en heures) au niveau du profil partenaire. La valeur par défaut est 24 heures lors de la création du partenaire. Cette valeur s'applique aux simulations/commandes.
Définition: validation_delay_hours est le temps que prendra la validation de la commande ou vente depuis la plateforme du partenaire.

💡 Utilisation: Appelez cet endpoint pour modifier le délai de validation global de votre compte partenaire. Exemple: le passer de 24h à 48h.

Paramètres

Structure du payload

{
  "validation_delay_hours": 48
}

Champ	Type	Obligatoire	Description
validation_delay_hours	Integer	Oui	Nouveau délai de validation en heures (minimum: 24)

Exemple cURL

curl --location --request PUT 'https://hub.lizoworld.com/api/partner-profile/validation-delay' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SANCTUM_TOKEN' \
--data '{
  "validation_delay_hours": 48
}'

2 Simulation de Course

POST /api/simulations

Description: Cet endpoint permet d'obtenir une vue sur les créneaux de disponibilité et le prix de la livraison. Il retourne une liste de créneaux disponibles avec leurs prix respectifs. Le créneau choisi par le client sera utilisé dans le second endpoint (création de course) au niveau du champ scheduled_at.

💡 Utilisation: Utilisez cet endpoint pour afficher les créneaux disponibles et leurs prix à vos clients. Le client choisit un créneau, et vous utilisez sa date/heure dans le champ scheduled_at lors de la création de la course.

⏰ Délai de validation: Ce délai est désormais géré au niveau du profil partenaire (valeur par défaut: 24 heures).
Il s'agit du temps que prendra la validation de la commande/vente depuis votre plateforme.

Paramètres

Structure du payload

{
  "pickup": {
    "latitude": 5.359951,
    "longitude": -4.008256,
    "address": "Plateau, Abidjan"
  },
  "delivery": {
    "latitude": 5.330046,
    "longitude": -4.027864,
    "address": "Marcory, Abidjan"
  },
  "vehicle_type": "moto",
  "photo_url": "https://example.com/photo.jpg"
}

Description des champs

Champ	Type	Obligatoire	Description
pickup	Object	Oui	Point de collecte du colis
pickup.latitude	Float	Oui	Latitude du point de collecte (ex: 5.359951)
pickup.longitude	Float	Oui	Longitude du point de collecte (ex: -4.008256)
pickup.address	String	Oui	Adresse textuelle du point de collecte
delivery	Object	Oui	Point de livraison du colis
delivery.latitude	Float	Oui	Latitude du point de livraison
delivery.longitude	Float	Oui	Longitude du point de livraison
delivery.address	String	Oui	Adresse textuelle du point de livraison
vehicle_type	String	Oui	Type de véhicule: "cargo", "moto", "velo"
photo_url	String	Non	URL d'une photo du colis (optionnel)

Exemple cURL

curl --request POST \
  --url https://hub.lizoworld.com/api/simulations \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_SANCTUM_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "pickup": {
      "latitude": 5.359951,
      "longitude": -4.008256,
      "address": "Plateau, Abidjan"
    },
    "delivery": {
      "latitude": 5.330046,
      "longitude": -4.027864,
      "address": "Marcory, Abidjan"
    },
    "vehicle_type": "moto",
    "photo_url": "https://example.com/photo.jpg"
  }'

Exemples de retour

200 - Succès

[
  {
    "date": "2025-08-22",
    "day_label": "Demain",
    "period": "Matin",
    "delivery_price": 1500,
    "code_crenaux": "B1"
  },
  {
    "date": "2025-08-23",
    "day_label": "sam. 23 août",
    "period": "Après‑midi",
    "delivery_price": 1400,
    "code_crenaux": "C2"
  }
]

Système de Codes de Créneaux

💡 Comprendre les codes de créneaux: Les codes de créneaux suivent un format spécifique pour identifier le jour et la période de livraison.

Jours de la semaine

ALundi

BMardi

CMercredi

DJeudi

EVendredi

FSamedi

GDimanche

Périodes de la journée

1Matin (8h - 12h)

2Après-midi (14h - 18h)

3Soirée (18h - 22h)

Exemples de codes de créneaux:

A1Lundi matin

B2Mardi après-midi

C3Mercredi soirée

F1Samedi matin

3 Création de Course

POST /api/deliveries

Description: Crée une nouvelle course de livraison avec tous les détails nécessaires. Cette étape lance réellement la livraison et assigne un livreur à la course.

💡 Utilisation: Utilisez cet endpoint après la simulation pour créer la course réelle une fois que le client a confirmé sa commande.

📋 NB: Les champs scheduled_at et code_crenaux proviennent de la réponse de l'endpoint de simulation. Le client choisit un créneau dans la simulation, et vous utilisez sa date/heure et son code dans cet endpoint.

Paramètres

Structure du payload

{
  "pickup": {
    "latitude": 5.2941,
    "longitude": -3.9986,
    "address": "123 Rue du Commerce, Abidjan"
  },
  "delivery": {
    "latitude": 5.3097,
    "longitude": -4.0127,
    "address": "456 Avenue des Cocotiers, Abidjan"
  },
  "special_instructions": "Sonner deux fois à l'arrivée",
  "vehicle_type": "moto",
  "scheduled_at": "2025-06-20",
  "code_crenaux": "A1",
  "should_collect_amount": true,
  "amount_to_collect": 150000.50,
  "metadata": [
    {
      "key": "client_id",
      "value": "CLIENT_12345"
    },
    {
      "key": "client_name",
      "value": "Jean Dupont"
    },
    {
      "key": "client_phone",
      "value": "+22501234567"
    },
    {
      "key": "order_reference",
      "value": "CMD-2024-001"
    }
  ],
  "items": [
    {
      "name": "Colis fragile",
      "description": "Vase en verre",
      "quantity": 1,
      "weight": 2.5,
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 15
      },
      "is_fragile": true,
      "is_liquid": false
    }
  ]
}

Description des champs

Champ	Type	Obligatoire	Description
pickup	Object	Oui	Point de collecte du colis (même structure que simulation)
delivery	Object	Oui	Point de livraison du colis (même structure que simulation)
vehicle_type	String	Oui	Type de véhicule: "cargo", "moto", "velo"
photo_url	String	Non	URL de la photo du colis
code_crenaux	String	Oui	Code du créneau de livraison (ex: "A1", "B2")
should_collect_amount	Boolean	Non	Si le livreur doit collecter un montant
amount_to_collect	Float	Non	Montant à collecter en FCFA
metadata	Array	Non	Tableau d'informations supplémentaires (clé-valeur)
metadata[].key	String	Oui	Clé de l'information (ex: client_id, order_reference)
metadata[].value	String	Oui	Valeur de l'information
items	Array	Oui	Liste des articles à livrer
items[].name	String	Oui	Nom de l'article
items[].description	String	Non	Description détaillée de l'article
items[].quantity	Integer	Oui	Quantité de l'article
items[].weight	Float	Oui	Poids en kilogrammes
items[].dimensions	Object	Non	Dimensions en centimètres (length, width, height)
items[].is_fragile	Boolean	Non	Si l'article est fragile (défaut: false)
items[].is_liquid	Boolean	Non	Si l'article contient du liquide (défaut: false)

Exemple cURL

curl --request POST \
  --url https://hub.lizoworld.com/api/deliveries \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 7|E8ta9bTWEV62sdx366inPqUT9EeHX2VRmgY9Pett1c58b2ee' \
  --header 'Content-Type: application/json' \
  --data '{
    "pickup": {
      "latitude": 5.2941,
      "longitude": -3.9986,
      "address": "Koumassi, Abidjan"
    },
    "delivery": {
      "latitude": 5.3097,
      "longitude": -4.0127,
      "address": "Treichville, Abidjan"
    },
    "vehicle_type": "moto",
    "photo_url": "https://example.com/photo.jpg",
    "code_crenaux": "A1",
    "items": [
      {
        "name": "Colis fragile",
        "description": "Vase en verre pour anniversaire",
        "quantity": 1,
        "weight": 2.5,
        "dimensions": {
          "length": 30,
          "width": 20,
          "height": 15
        },
        "is_fragile": true,
        "is_liquid": false
      },
      {
        "name": "Documents",
        "description": "Contrat important",
        "quantity": 1,
        "weight": 0.5,
        "is_fragile": false,
        "is_liquid": false
      }
    ],
    "metadata": [
      {
        "key": "client_id",
        "value": "CLIENT_12345"
      },
      {
        "key": "client_name",
        "value": "Jean Dupont"
      },
      {
        "key": "client_phone",
        "value": "+22501234567"
      },
      {
        "key": "order_reference",
        "value": "CMD-2024-001"
      }
    ],
    "should_collect_amount": true,
    "amount_to_collect": 150000.50
  }'

Exemples de retour

200 - Succès

{
  "status": 200,
  "message": "Votre livraison a été créée avec succès",
  "data": {
    "id": "del_MqNmdDWyjQk4A",
    "reference": "DEL-250821RND",
    "pickup": {
      "latitude": 5.2941,
      "longitude": -3.9986,
      "address": "Koumassi, Abidjan"
    },
    "pickup_address": null,
    "delivery": {
      "latitude": 5.3097,
      "longitude": -4.0127,
      "address": "Treichville, Abidjan"
    },
    "delivery_address": null,
    "owner": {
      "id": "use_vdNxGj6E7mXQ6",
      "first_name": "DA",
      "last_name": "Alexis",
      "email": "daalexis@gmail.com",
      "phone": "0767476599",
      "avatar": null,
      "type": "partner",
      "created_at": "2025-08-21T08:42:20.000000Z",
      "updated_at": "2025-08-21T08:42:20.000000Z"
    },
    "delivery_person": null,
    "delivery_photo": null,
    "state": "ready_for_pickup",
    "vehicle_type": "moto",
    "items": [
      {
        "id": 5,
        "name": "Colis fragile",
        "description": "Vase en verre pour anniversaire",
        "quantity": 1,
        "weight": "2.50",
        "dimensions": {
          "length": 30,
          "width": 20,
          "height": 15
        },
        "is_fragile": true,
        "is_liquid": false,
        "created_at": "2025-08-21T11:06:24.000000Z",
        "updated_at": "2025-08-21T11:06:24.000000Z"
      },
      {
        "id": 6,
        "name": "Documents",
        "description": "Contrat important",
        "quantity": 1,
        "weight": "0.50",
        "dimensions": null,
        "is_fragile": false,
        "is_liquid": false,
        "created_at": "2025-08-21T11:06:24.000000Z",
        "updated_at": "2025-08-21T11:06:24.000000Z"
      }
    ],
    "is_scheduled": true,
    "delivery_type": "programmée",
    "scheduled_at": "2025-08-25T08:00:00.000000Z",
    "period": "morning",
    "should_collect_amount": true,
    "amount_to_collect": 150000.5,
    "delivery_fee": 1200,
    "metadata": [
      {
        "key": "client_id",
        "value": "CLIENT_12345"
      },
      {
        "key": "client_name",
        "value": "Jean Dupont"
      },
      {
        "key": "client_phone",
        "value": "+22501234567"
      },
      {
        "key": "order_reference",
        "value": "CMD-2024-001"
      }
    ],
    "created_at": "2025-08-21T11:06:24.000000Z",
    "updated_at": "2025-08-21T11:06:24.000000Z"
  }
}

422 - Erreur de validation

{
  "code": 422,
  "message": "Nous vous prions de corriger les erreurs suivantes:",
  "errors": [
    "La latitude du point de récupération est requise.",
    "La longitude du point de récupération est requise.",
    "Le code de créneau est obligatoire."
  ]
}

4 Suivi de Course

GET /api/deliveries/{delivery_id}

Description: Récupère les informations en temps réel sur le statut et la localisation d'une course. Permet de suivre l'avancement de la livraison et d'informer vos clients.

💡 Utilisation: Utilisez cet endpoint pour créer un système de suivi en temps réel et informer vos clients de l'état de leur livraison.

Paramètres de requête

Paramètre	Type	Obligatoire	Description
delivery_id	String	Oui	Identifiant unique de la course (ex: del_2vP3pj4K7GWgZ)

Exemple cURL

curl --request GET \
  --url https://hub.lizoworld.com/api/deliveries/del_2vP3pj4K7GWgZ \
  --header 'Authorization: Bearer 2|XGX42lQGV70FEo5GMcVuCsU9PzDDyQgqHPP1Fq8h08451aff'

Exemples de retour

200 - Succès

{
  "status": 200,
  "message": "Livraison",
  "data": {
    "id": "del_eLgoNjw3jE0MB",
    "reference": "DEL-250825IID",
    "pickup": {
      "address": "Koumassi, Abidjan",
      "latitude": 5.2941,
      "longitude": -3.9986
    },
    "delivery": {
      "address": "Treichville, Abidjan",
      "latitude": 5.3097,
      "longitude": -4.0127
    },
    "delivery_photo": null,
    "state": "ready_for_pickup",
    "state_label": "En attente de retrait par le livreur",
    "vehicle_type": "moto",
    "is_scheduled": true,
    "delivery_type": "programmée",
    "scheduled_at": "2025-08-29T13:00:00.000000Z",
    "period": "afternoon",
    "should_collect_amount": 1,
    "amount_to_collect": "15000.50",
    "metadata": null,
    "delivery_fee": "1200.00",
    "created_at": "2025-08-25T19:01:54.000000Z",
    "updated_at": "2025-08-25T19:01:54.000000Z"
  }
}

Description des champs de réponse

Champ	Type	Description
id	String	Identifiant unique de la course
reference	String	Référence lisible de la course
pickup	Object	Point de collecte (address, latitude, longitude)
delivery	Object	Point de livraison (address, latitude, longitude)
delivery_photo	String\|null	URL de la photo de livraison (le cas échéant)
state	String	Code du statut (ex: ready_for_pickup)
state_label	String	Libellé du statut
vehicle_type	String	Type de véhicule (moto, cargo, etc.)
is_scheduled	Boolean	Indique si la livraison est programmée
delivery_type	String	Type de livraison (immédiate/programmée)
scheduled_at	Datetime (ISO 8601)	Date et heure prévues
period	String	Période (morning/afternoon/evening)
should_collect_amount	Boolean\|Integer	Collecte d'un montant à la livraison
amount_to_collect	String\|Number	Montant à collecter
metadata	Object\|null	Métadonnées additionnelles
delivery_fee	String\|Number	Frais de livraison
created_at	Datetime	Date de création
updated_at	Datetime	Date de mise à jour

Codes de Statut

💡 Note : Les statuts suivent un ordre logique de progression. Chaque statut indique une étape précise du processus de livraison.

Statut	Code API	Description	Phase	Actions possibles
Prêt pour la collecte	`ready_for_pickup`	La course est créée et prête pour l'assignation d'un livreur	Préparation	Assignation livreur
Livreur assigné	`assigned`	Un livreur a été assigné à la course et se dirige vers le point de collecte	Collecte	Arrivée chez expéditeur
Arrivé chez l'expéditeur	`arrived_at_sender`	Le livreur est arrivé au point de collecte et attend le colis	Collecte	Collecte du colis
Colis collecté	`picked_up`	Le colis a été collecté par le livreur et est en route	Transit	En route vers destinataire
En livraison	`out_for_delivery`	Le livreur est en route pour la livraison finale	Livraison	Livraison finale
Livraison terminée	`delivered`	La livraison a été effectuée avec succès	Terminé	Aucune action
Course annulée	`cancelled`	La course a été annulée	Annulé	Aucune action

API Lizo Delivery

Introduction #

🚀 Démarrage Rapide

Authentification #

URLs de Base

Headers Requis

Endpoints API #

1 Mise à jour du délai de validation (Profil partenaire) #

Paramètres

Structure du payload

Exemple cURL

2 Simulation de Course #

Paramètres

Structure du payload

Description des champs

Exemple cURL

Exemples de retour

200 - Succès

401 - Authentification requise

403 - Accès interdit

422 - Erreur de validation

500 - Erreur interne du serveur

Système de Codes de Créneaux

Jours de la semaine

Périodes de la journée

Exemples de codes de créneaux:

3 Création de Course #

Paramètres

Structure du payload

Description des champs

Exemple cURL

Exemples de retour

200 - Succès

401 - Authentification requise

403 - Accès interdit

422 - Erreur de validation

500 - Erreur interne du serveur

4 Suivi de Course #

Paramètres de requête

Exemple cURL

Exemples de retour

200 - Succès

401 - Authentification requise

404 - Course non trouvée

500 - Erreur interne du serveur

Description des champs de réponse

Codes de Statut

Introduction

Authentification

Endpoints API

1 Mise à jour du délai de validation (Profil partenaire)

2 Simulation de Course

3 Création de Course

4 Suivi de Course