1. Présentation de Tidco Express
Tidco Express est une plateforme professionnelle de gestion logistique permettant de gérer les colis, les clients, les livreurs, les franchises, les lots de livraison, les retours, les tentatives échouées et l’intégration API avec les partenaires comme Zimou.
Client
Création de livraison, suivi colis, historique et notifications.
Livreur
Acceptation des lots, scan QR, preuves, statut en ligne et retours.
Admin
Gestion globale, utilisateurs, commandes, Zimou et statistiques.
API Partner
Connexion partenaire pour import colis et suivi des statuts.
2. Architecture générale
Zimou │ │ API sécurisée par Wilaya ▼ Tidco Express API │ ▼ Supabase / PostgreSQL │ ├── Application Client ├── Application Livreur ├── Dashboard Admin ├── Dashboard Franchise ├── Tidco Retour └── Historique & Logs
3. Présentation de l’APK Tidco Express
Espace Client
- Créer une nouvelle livraison.
- Choisir les adresses de collecte et livraison.
- Ajouter les informations du destinataire et le COD.
- Suivre le statut de la commande.
- Consulter l’historique des colis.
Espace Livreur
- Se mettre en ligne ou hors ligne.
- Recevoir les lots et commandes disponibles.
- Scanner les QR codes.
- Ajouter des photos justificatives.
- Déclarer les échecs avec motif, note et GPS.
Espace Admin
- Suivi des commandes et utilisateurs.
- Gestion des livreurs et franchises.
- Gestion des API par Wilaya.
- Gestion des retours Tidco.
- Statistiques et logs API.
4. Workflow de livraison
1. Colis importé depuis Zimou ou créé dans Tidco.
2. Regroupement automatique par Wilaya et Commune.
3. Création des lots avec maximum 20 colis.
4. Affectation ou acceptation par un livreur.
5. Livraison, échec ou retour.
6. Synchronisation du statut vers Zimou.
5. Intégration API Zimou
Base URL :
https://qndsgrxmgckjtnukrcby.supabase.co/functions/v1/zimou-api
Authentification
X-Tidco-Api-Key: tidco_alger_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Chaque Wilaya possède une clé API indépendante. Une clé Alger ne peut pas accéder à Oran.
Endpoints disponibles
| Méthode | Endpoint | Utilisation |
|---|---|---|
| GET | /health | Vérifier que l’API fonctionne |
| POST | /{wilaya}/parcels/import | Importer des colis depuis Zimou |
| GET | /{wilaya}/parcels/{tracking}/status | Consulter un statut colis |
| POST | /{wilaya}/parcels/status/bulk | Consulter plusieurs statuts en une requête |
| GET | /{wilaya}/attempts | Récupérer les tentatives échouées |
| GET | /{wilaya}/returns | Récupérer les retours |
| GET | /{wilaya}/status | Statistiques de la Wilaya |
Exemple import colis
{
"parcels": [
{
"tracking_number": "ZIM-ALG-001",
"zimou_order_id": "123456",
"recipient_name": "Ahmed Benali",
"recipient_phone": "0555123456",
"delivery_address": "Bab El Oued, Alger",
"wilaya": "Alger",
"commune": "Bab El Oued",
"quartier": "Centre",
"cod_amount_dzd": 2500,
"notes": "Appeler avant livraison"
}
]
}
6. Création automatique des lots
Les colis sont regroupés automatiquement par Wilaya puis Commune.
Règle importante : un lot ne peut jamais dépasser 20 colis.
| Nombre de colis | Résultat |
|---|---|
| 20 colis | 1 lot |
| 45 colis | Lot 1 = 20, Lot 2 = 20, Lot 3 = 5 |
| 100 colis | 5 lots de 20 colis |
7. Workflow Tidco Retour
Un colis échoué ne retourne pas directement à Zimou. Il passe d’abord par Tidco Retour.
1. Le livreur échoue la livraison.
2. Il ajoute motif, note, photo et GPS.
3. Le colis passe en retour_tidco_en_cours.
4. Le livreur ramène physiquement le colis chez Tidco.
5. L’admin confirme avec photo.
6. Le colis devient retour_tidco_recu et repart dans un nouveau lot.
7. Après 3 tentatives, le colis est retourné définitivement à Zimou.
8. Liste globale des statuts
| Code | Description |
|---|---|
| imported | Colis reçu depuis Zimou API |
| grouped | Colis ajouté à un lot |
| assigned | Assigné à un livreur |
| picked_up | Pris en charge |
| in_delivery | En cours de livraison |
| delivered | Livré avec succès |
| failed | Tentative échouée |
| retour_tidco_en_cours | Retour physique vers Tidco en cours |
| retour_tidco_recu | Colis reçu chez Tidco, prêt pour relivraison |
| retour_zimou_pending_sync | Retour final vers Zimou en attente |
| retour_zimou_synced | Retour synchronisé avec Zimou |
| retour_zimou_sync_failed | Erreur de synchronisation retour |
| cancelled | Colis annulé |
| not_found | Tracking introuvable |
Motifs d’échec
client_absent phone_unreachable wrong_address refused refused_payment other
9. Sécurité
- Clé API obligatoire pour tous les endpoints privés.
- Clé séparée par Wilaya.
- Logs complets dans zimou_wilaya_api_logs.
- Aucun accès admin pour les partenaires API.
- Les clés brutes sont affichées une seule fois.
- Authentification Supabase et rôles utilisateurs.