API Partenaires Transporteurs v1

Recevez, livrez, mettez à jour.

Cette API est destinée aux sociétés de livraison partenaires de Havana Express. Elle vous permet de récupérer les colis que nous vous confions, mettre à jour leur statut et remonter les preuves de livraison.

Devenir partenaire

1. Clé API

Havana Express vous remet une clé privée sk_partner_….

2. Récupérer les colis

Interrogez régulièrement GET /orders.

3. Mettre à jour

Postez le statut + preuve à chaque étape clé.

URL de base

https://havanaexpress.ma/api/public/partners

JSON UTF-8. Codes : 200/201 succès, 400 validation, 401 clé invalide, 403 compte désactivé, 404 colis non assigné, 500 erreur serveur.

Authentification

Ajoutez votre clé partenaire à chaque requête :

x-api-key: sk_partner_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

Lister les colis assignés

Renvoie uniquement les colis que Havana Express vous a confiés. Filtres : status, limit (1-200), offset.

GET/api/public/partners/orders?status=picked_up&limit=50

Réponse

{
  "ok": true,
  "count": 12,
  "limit": 50,
  "offset": 0,
  "orders": [
    {
      "tracking_number": "FX-2026-00123",
      "status": "in_transit",
      "recipient_name": "Ali Bennani",
      "recipient_phone": "0612345678",
      "delivery_city": "Casablanca",
      "delivery_address": "Rue Mohammed V, 12",
      "cod_amount": 250,
      "weight_kg": 1.2
    }
  ]
}

Détails d'un colis

Informations complètes + historique (events).

GET/api/public/partners/orders/{tracking_number}

Réponse

{
  "ok": true,
  "order": {
    "tracking_number": "FX-2026-00123",
    "status": "in_transit",
    "sender_name": "Boutique Atlas",
    "recipient_name": "Ali Bennani",
    "recipient_phone": "0612345678",
    "delivery_city": "Casablanca",
    "delivery_address": "Rue Mohammed V, 12",
    "cod_amount": 250
  },
  "events": [ { "status": "in_transit", "message": "...", "created_at": "..." } ]
}

Mettre à jour le statut

Statuts autorisés : pending, picked_up, received_origin_hub, in_transit, received_destination_hub, assigned_driver, out_for_delivery, delivered, postponed, failed, returned, cancelled.

POST/api/public/partners/orders/{tracking_number}/status

Requête

curl -X POST https://havanaexpress.ma/api/public/partners/orders/FX-2026-00123/status \
  -H "x-api-key: sk_partner_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "delivered",
    "received_by": "Ali Bennani",
    "signature_url": "https://cdn.example.com/sign/abc.png",
    "pod_photo_url": "https://cdn.example.com/pod/abc.jpg",
    "delivery_lat": 33.5731,
    "delivery_lng": -7.5898
  }'

Réponse

{ "ok": true, "tracking_number": "FX-2026-00123", "status": "delivered" }

Signaler un échec / report

Indiquez la raison dans le champ reason. Le client en sera notifié automatiquement.

POST/api/public/partners/orders/{tracking_number}/status

Requête

{
  "status": "failed",
  "reason": "Destinataire injoignable, 3 tentatives"
}

Réponse

{ "ok": true, "tracking_number": "FX-2026-00123", "status": "failed" }

Cycle de vie d'un colis

pendingCréé, en attente de ramassage

picked_upRamassé chez l'expéditeur

received_origin_hubReçu au Hub d'origine

in_transitEn transit

received_destination_hubArrivé au Hub de destination

assigned_driverAffecté à un livreur

out_for_deliveryEn cours de livraison

deliveredLivré ✅ (joindre POD)

postponedReporté

failedÉchec (joindre raison)

returnedRetourné expéditeur

cancelledAnnulé

Sécurité & bonnes pratiques

Ne partagez jamais votre clé sk_partner_…. Conservez-la côté serveur uniquement.
En cas de fuite, contactez Havana Express immédiatement — nous révoquons la clé et en émettons une nouvelle.
Polling recommandé : 1 requête / minute maximum sur GET /orders.
Pour la livraison, joignez systématiquement signature_url ou pod_photo_url.
Les coordonnées GPS (delivery_lat, delivery_lng) renforcent la preuve de livraison.

Support intégration

Notre équipe technique vous accompagne pour brancher votre TMS ou app mobile.

Contacter l'équipe