API Partenaires v1

Intégrez Swiftly en quelques minutes.

Notre API REST permet à votre boutique, ERP ou marketplace de créer des envois, suivre les colis et gérer les annulations en temps réel.

Obtenir une clé API Support intégration

1. Clé API

Générez une clé sk_live_… depuis votre espace client.

2. Authentification

Envoyez l'en-tête x-api-key à chaque requête.

3. Premier envoi

POST /api/public/orders avec les infos du destinataire.

URL de base

https://swiftly.ink/api/public

Toutes les réponses sont en JSON UTF-8. Codes HTTP standards : 200/201 succès, 400 validation, 401 clé invalide, 404 ressource introuvable, 409 conflit, 500 erreur serveur.

Authentification

Chaque requête doit inclure votre clé API privée :

x-api-key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

Créer un envoi

Crée un nouveau colis dans votre compte et retourne le numéro de suivi.

POST/api/public/orders

Requête

curl -X POST https://swiftly.ink/api/public/orders \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Ali Bennani",
    "recipient_phone": "0612345678",
    "delivery_city": "Casablanca",
    "delivery_address": "Rue Mohammed V, 12",
    "pickup_city": "Fes",
    "pickup_address": "Hub Swiftly",
    "cod_amount": 250,
    "weight_kg": 1.2,
    "items_count": 1,
    "notes": "Fragile"
  }'

Réponse

{
  "ok": true,
  "parcel": {
    "id": "uuid",
    "tracking_number": "FX-2026-00123",
    "status": "pending"
  }
}

Lister vos colis

Filtres optionnels : status, from (ISO), to (ISO), limit (1-200), offset.

GET/api/public/parcels?status=delivered&limit=50

Réponse

{
  "ok": true,
  "count": 134,
  "limit": 50,
  "offset": 0,
  "parcels": [
    {
      "id": "uuid",
      "tracking_number": "FX-2026-00123",
      "status": "delivered",
      "recipient_name": "Ali",
      "delivery_city": "Casablanca",
      "cod_amount": 250,
      "delivered_at": "2026-06-05T10:21:00Z"
    }
  ]
}

Suivre un colis

Détails complets + historique des événements (timeline).

GET/api/public/parcels/{tracking_number}

Réponse

{
  "ok": true,
  "parcel": {
    "tracking_number": "FX-2026-00123",
    "status": "out_for_delivery",
    "delivery_city": "Casablanca",
    "cod_amount": 250,
    "current_hub": "Casablanca"
  },
  "events": [
    { "status": "out_for_delivery", "message": "En cours de livraison", "created_at": "..." },
    { "status": "in_transit", "message": "En transit", "created_at": "..." },
    { "status": "pending", "message": "Commande créée", "created_at": "..." }
  ]
}

Annuler un colis

Possible uniquement tant que le colis n'a pas quitté le hub d'origine.

POST/api/public/parcels/{tracking_number}/cancel

Réponse

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

Statuts possibles

pendingNouvelle commande

picked_upRamassé

received_origin_hubAu Hub d'origine

in_transitEn transit

received_destination_hubAu Hub destination

assigned_driverAffecté livreur

out_for_deliveryEn livraison

deliveredLivré

failedÉchec

postponedReporté

returnedRetourné

cancelledAnnulé

Bonnes pratiques

Ne partagez jamais votre clé sk_live_… côté navigateur. Conservez-la sur votre serveur.
En cas de compromission, révoquez immédiatement la clé depuis votre espace client et créez-en une nouvelle.
Implémentez un retry exponentiel (1s, 2s, 4s) sur les erreurs 5xx.
Stockez le tracking_number retourné pour pouvoir suivre vos commandes.

Besoin d'aide ?

Notre équipe technique vous accompagne sur Shopify, WooCommerce ou intégrations sur mesure.

Contacter l'équipe API