API v2

API RESTful
simple et puissante

Connectez votre boutique ou votre agence à Atlas Livraison. Endpoints REST, réponses JSON, webhooks signés et clés API sécurisées.

URL de base

https://api.atlaslivraison.com

Authentification

Chaque appel authentifié requiert l'en-tête x-api-key. Générez votre clé depuis le tableau de bord.

x-api-key: atl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Comment ça marche

1

Créez votre compte

Inscrivez-vous et demandez l’activation de l’API depuis votre tableau de bord.

2

Générez une clé

Dans Paramètres API, générez une clé « atl_… » (client ou agence).

3

Appelez l’API

Envoyez vos requêtes avec l’en-tête x-api-key. Récupérez les cityId via /cities.

4

Recevez les événements

Abonnez un webhook signé pour être notifié à chaque changement d’état.

Client

API Marchande

Pour les e-commerçants : créez des colis, listez-les, suivez leur état.

POST/api/external/colisClé client

Créer un colis. fullname, phone (06/07 + 8 chiffres) et cityId sont requis. Le prix (montant COD) ne doit pas dépasser le plafond configuré du compte (sinon 400). change=true crée un échange facturé plein tarif (pas de plafond réduit via l’API). Ajoutez l’en-tête Idempotency-Key pour sécuriser les reprises.

Requête
curl -X POST https://api.atlaslivraison.com/api/external/colis \
  -H "x-api-key: atl_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-10432" \
  -d '{
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "cityId": "e455712f-bcf0-4827-b579-b34b52026b0f",
    "address": "12 Rue Hassan II",
    "price": 349.00,
    "product": "Montre connectée",
    "quantity": 1,
    "note": "Appeler avant livraison"
  }'
Réponse
201 Created
{
  "success": true,
  "data": {
    "code": "TR-ATL627313042334",
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "cityId": "e455712f-bcf0-4827-b579-b34b52026b0f",
    "price": "349.00",
    "stateId": 1,
    "cfees": "25.00",
    "createdAt": "2026-07-25T20:14:00.000Z"
  }
}
GET/api/external/colisClé client

Lister vos colis (page, limit ≤ 100, stateId, from, to).

Requête
curl "https://api.atlaslivraison.com/api/external/colis?page=1&limit=20&stateId=17" \
  -H "x-api-key: atl_VOTRE_CLE"
Réponse
200 OK
{
  "success": true,
  "data": [
    {
      "code": "TR-ATL627313042334",
      "fullname": "Ahmed Bennani",
      "phone": "0612345678",
      "cityId": "e455712f-...",
      "price": "349.00",
      "stateId": 17,
      "stateName": "Livré",
      "createdAt": "2026-07-20T09:00:00.000Z",
      "updatedAt": "2026-07-22T16:30:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}
GET/api/external/colis/:codeClé client

Obtenir l’état d’un colis (projection statut, sans données sensibles).

Requête
curl https://api.atlaslivraison.com/api/external/colis/TR-ATL627313042334 \
  -H "x-api-key: atl_VOTRE_CLE"
Réponse
200 OK
{
  "success": true,
  "data": {
    "code": "TR-ATL627313042334",
    "stateId": 17,
    "stateName": "Livré",
    "createdAt": "2026-07-20T09:00:00.000Z",
    "updatedAt": "2026-07-22T16:30:00.000Z"
  }
}
GET/api/external/citiesClé client

Référentiel des villes (id / nom). Le cityId est requis pour créer un colis.

Requête
curl https://api.atlaslivraison.com/api/external/cities \
  -H "x-api-key: atl_VOTRE_CLE"
Réponse
200 OK
{
  "success": true,
  "data": [
    { "id": "e455712f-bcf0-4827-b579-b34b52026b0f", "name": "Casablanca" }
  ]
}
Agence & Livreur

API opérationnelle

Les comptes agence et livreur disposent d’une API opérationnelle : lister les colis qui leur sont assignés et faire évoluer leur état (la création de colis n’est pas dans leur périmètre). Sa documentation complète — endpoints, statuts autorisés et exemples — s’affiche dans Paramètres API une fois connecté, adaptée au type de votre compte.

Se connecter
Public

Endpoints publics

Sans clé API — suivi, simulateur de frais et avis client.

GET/api/external/track/:codeAucune

Suivi public d’un colis. Le nom du destinataire est masqué.

Requête
curl https://api.atlaslivraison.com/api/external/track/TR-ATL627313042334
Réponse
200 OK
{ "success": true, "data": { "code": "TR-ATL...", "fullname": "Ah**", "stateId": 17, "createdAt": "...", "timeline": [ /* historique */ ] } }
GET/api/external/public-feesAucune

Simulateur de frais public (sourceCityId optionnel).

Requête
curl "https://api.atlaslivraison.com/api/external/public-fees?sourceCityId=e455712f-..."
Réponse
200 OK
{ "success": true, "data": { /* barème de frais */ } }
POST/api/external/feedbackAucune

Soumettre un avis client (code, rating 1–5, comment). Réponse générique (ne révèle pas si le code existe) ; un seul avis par colis.

Requête
curl -X POST https://api.atlaslivraison.com/api/external/feedback \
  -H "Content-Type: application/json" \
  -d '{ "code": "TR-ATL627313042334", "rating": 5, "comment": "Livraison rapide" }'
Réponse
201 Created
{ "success": true, "data": { "received": true } }

Webhooks & limites

Webhooks signés

Abonnez une URL depuis Paramètres API pour recevoir colis.created et colis.state_changed. Chaque envoi est signé en HMAC-SHA256 (en-tête X-Atlas-Signature) — évitez le polling.

Limites de débit

Par compte : 300 lectures/min et 60 écritures/min (relevables pour les gros comptes). Respectez les en-têtes RateLimit-*; un HTTP 429 signifie qu'il faut ralentir.

Prêt à intégrer ?

Créez votre compte et générez votre première clé API en moins de 5 minutes.

Créer un compte gratuit