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",
      "address": "12 Rue Hassan II",
      "cityId": "e455712f-...",
      "cityName": "Tiznit",
      "gpsLat": "29.6974210",
      "gpsLng": "-9.7359240",
      "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 et les détails d’un colis : statut, destinataire (nom, téléphone), adresse, ville (cityName) et position GPS du client (gpsLat/gpsLng, si partagée).

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",
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "address": "12 Rue Hassan II",
    "cityId": "e455712f-...",
    "cityName": "Tiznit",
    "gpsLat": "29.6974210",
    "gpsLng": "-9.7359240",
    "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" }
  ]
}
GET/api/external/facturesClé client

Lister vos factures (paginé ; filtres type, paid, dateFrom/dateTo). Une clé client voit ses factures FAC. Aucun frais interne ni marge n’est exposé.

Requête
curl "https://api.atlaslivraison.com/api/external/factures?page=1&limit=20&paid=false" \
  -H "x-api-key: atl_VOTRE_CLE"
Réponse
200 OK
{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "code": "FAC-260722-0012",
      "type": "FAC",
      "totalAmount": "349.00",
      "totalFees": "25.00",
      "netAmount": "324.00",
      "paid": false,
      "paidAt": null,
      "createdAt": "2026-07-22T10:00:00.000Z",
      "updatedAt": "2026-07-22T10:00:00.000Z",
      "colisCount": 1
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}
GET/api/external/colis/:code/messagesClé client

Lister les messages du fil de discussion d’un de vos colis (paginé). Les noms d’expéditeur sont masqués et les URL de pièces jointes ne sont pas exposées.

Requête
curl "https://api.atlaslivraison.com/api/external/colis/TR-ATL627313042334/messages?page=1&limit=50" \
  -H "x-api-key: atl_VOTRE_CLE"
Réponse
200 OK
{
  "success": true,
  "data": [
    {
      "id": "6f1e2d3c-4b5a-6978-8b9c-0d1e2f3a4b5c",
      "message": "Colis prêt, en attente de ramassage.",
      "messageType": "text",
      "senderType": "agency",
      "senderName": "Agence Casa",
      "hasAttachment": false,
      "createdAt": "2026-07-22T11:15:00.000Z",
      "deletedAt": null
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}
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). Ils peuvent aussi consulter en lecture leurs factures et messages ; une agence lit en plus ses bons de groupage entrants et ses bons de retour, et peut s’abonner aux webhooks correspondants. 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 les événements colis colis.created, colis.state_changed, colis.location_updated (position GPS partagée par le client, ex. via WhatsApp), colis.message (nouveau message dans le fil), ainsi que facture.created, facture.paid et facture.reversed pour vos factures. Les comptes agence reçoivent en plus, selon leur périmètre, groupage.incoming (bon de groupage entrant), return_bon.assigned (= return_bon.shipped) et return_bon.sealed. 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). Une garde par IP (12000 requêtes / 15 min ≈ 800/min) protège aussi cette API, bien au-dessus des limites par compte — ce sont donc vos limites par compte qui bornent votre débit. 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