API externe

L'API externe de Swaloo permet à vos systèmes (back-office, boutique en ligne, ERP) de créer des expéditions et d'en suivre le statut de serveur à serveur. Elle est exposée sous le préfixe /api/v1/external/ et s'authentifie exclusivement par clé API.

Authentification

Transmettez la clé API de votre organisation dans le header X-API-KEY :

curl -H "X-API-KEY: votre_cle_api" \
  https://api.swaloo.com/api/v1/external/shipments/{id}

La clé API attribue le rôle ROLE_EXTERNAL_API, requis sur toutes les routes externes. Voir Authentification et Clés API.

Endpoints

Créer une expédition

La requête est validée de façon synchrone. Si elle est valide, l'expédition est mise en file d'attente pour création asynchrone, et l'API répond immédiatement en 202 Accepted avec l'UUID pré-généré de l'expédition.

curl -X POST https://api.swaloo.com/api/v1/external/shipments \
  -H "X-API-KEY: votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "...": "..." },
    "deliveryAddress": { "street": "...", "city": "..." },
    "priority": "normal",
    "packageSize": "medium",
    "weight": 1.0,
    "externalReference": "CMD-1234"
  }'

Réponse (202) :

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Shipment accepted and queued for creation."
}

Modes de retrait (pickup)

• Sans retrait — omettez le champ pickup. L'expédition démarre directement par une tâche de livraison.
• Entrepôt existant — renseignez pickup.pickupPointId avec l'UUID d'un point de retrait connu.
• Retrait manuel — fournissez pickup.address avec au minimum street et city.

Planification

• Au plus tôt (ASAP) — omettez scheduledAfter. La date limite de livraison est calculée automatiquement selon la priorité.
• Planifié — renseignez scheduledAfter (et éventuellement scheduledBefore) au format ISO 8601.

Consulter une expédition

curl -H "X-API-KEY: votre_cle_api" \
  https://api.swaloo.com/api/v1/external/shipments/{id}

La réponse comprend le numéro de suivi, la référence externe, le statut, les informations du chauffeur (nom, téléphone) et la timeline des événements. Une expédition n'appartenant pas à votre organisation renvoie 403.

Limites de débit

L'API externe est limitée à 100 requêtes par minute et par organisation (fenêtre glissante). Voir Limites de débit.

Codes de réponse

Voir aussi : Authentification | Webhooks | Erreurs