API v2

API RESTful
simple et puissante

Connectez votre boutique à 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_… ».

3

Appelez l’API

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

4

Recevez les événements

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

Client

API Marchande

Pour les e-commerçants : l'essentiel pour démarrer — référentiels, création de colis (y compris depuis votre stock chez Atlas) et suivi.

Référentiels

GET/api/external/citiesClé client

Liste 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": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Casablanca" },
    { "id": "9c1b2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f", "name": "Rabat" }
  ]
}
GET/api/external/storesClé client

Liste de VOS boutiques actives (id + nom) pour le champ storeId — l’équivalent de /cities. Appelez-la une fois au démarrage de votre intégration plutôt que de coder l’identifiant en dur : votre code reste juste si vous ouvrez une deuxième boutique.

Requête
curl "https://api.atlaslivraison.com/api/external/stores" \
  -H "x-api-key: atl_VOTRE_CLE"
Réponse
200 OK
{
  "success": true,
  "data": [
    { "id": "uuid-de-la-boutique", "name": "VOTRE_BOUTIQUE" }
  ]
}
GET/api/external/stocksClé client

Catalogue de VOTRE stock chez Atlas : sku, stockId, quantité disponible (available) et gel d’inventaire (frozen). C’est la référence des articles à envoyer dans stockItems.

Requête
curl "https://api.atlaslivraison.com/api/external/stocks" \
  -H "x-api-key: atl_VOTRE_CLE"
Réponse
200 OK
{
  "success": true,
  "data": [
    {
      "stockId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "sku": "TSHIRT-NOIR-M",
      "name": "T-shirt (Noir / M)",
      "product": "T-shirt",
      "color": "Noir",
      "size": "M",
      "available": 42,
      "frozen": false
    }
  ]
}

Créer des colis

POST/api/external/colisClé client

Crée un colis et renvoie son code de suivi. fullname, phone (06/07 + 8 chiffres) et cityId sont requis. Le prix (montant COD) est en dirhams ENTIERS et ne doit pas dépasser le plafond du compte (sinon 400) ; change=true crée un échange facturé plein tarif. Champs optionnels : weight, allowtry, importRef (votre n° de commande — corrélation + recherche via GET /colis?importRef=), storeId (une de VOS boutiques actives). Sans storeId, le colis est rattaché automatiquement à votre boutique ; envoyez-le explicitement si vous en avez plusieurs. 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: cmd-1042" \
  -d '{
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "phone2": "0698765432",
    "address": "12 Rue des Fleurs, Maârif",
    "cityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "price": 150,
    "product": "T-shirt",
    "quantity": 1,
    "openpackage": false,
    "change": false,
    "note": "Appeler avant livraison",
    "storeId": "uuid-de-la-boutique"
  }'
Réponse
201 Created
{
  "success": true,
  "data": {
    "code": "ATL123456",
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "cityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "price": "150.00",
    "stateId": 1,
    "cfees": "35.00",
    "createdAt": "2026-07-22T10:00:00.000Z"
  }
}
POST/api/external/colisClé client

Colis de STOCK : ajoutez stockItems — la liste des articles à prélever dans votre stock chez Atlas, chacun désigné par son sku OU son stockId, avec sa quantité (1 à 50 articles). Le stock est vérifié et réservé à la création. Si product est omis, il est composé à partir des articles. Avec « Préparation automatique » activée dans Paramètres API, le colis part directement en « À préparer » (toPrepare: true dans la réponse).

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: cmd-1043" \
  -d '{
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "address": "12 Rue des Fleurs, Maârif",
    "cityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "price": 250,
    "stockItems": [
      { "sku": "TSHIRT-NOIR-M", "quantity": 2 },
      { "sku": "CASQUETTE-BLEU", "quantity": 1 }
    ]
  }'
Réponse
201 Created
{
  "success": true,
  "data": {
    "code": "STK123457",
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "cityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "price": "250.00",
    "stateId": 1,
    "cfees": "35.00",
    "createdAt": "2026-09-18T10:00:00.000Z",
    "isStock": true,
    "toPrepare": true
  }
}

Suivre vos colis

GET/api/external/colisClé client

Liste vos colis (paginé, limit ≤ 100). Filtres : stateId, stateIds (plusieurs états « 1,17 »), search (code / nom / téléphone), cityId, importRef, from/to (création), updatedFrom/updatedTo (synchro incrémentale sur la date de modification). Chaque colis rend aussi vos champs (product, quantity, weight, note, cfees…) et les dates de livraison.

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": "ATL123456",
      "fullname": "Ahmed Bennani",
      "phone": "0612345678",
      "cityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "address": "12 Rue des Fleurs, Maârif",
      "cityName": "Casablanca",
      "price": "150.00",
      "stateId": 17,
      "stateName": "Livré",
      "gpsLat": "33.5883",
      "gpsLng": "-7.6114",
      "createdAt": "2026-07-22T10:00:00.000Z",
      "updatedAt": "2026-07-23T14:30:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}
GET/api/external/colis/:codeClé client

État et détail d’un colis : destinataire, adresse, ville, position GPS du client (si partagée), montant COD (price), vos champs (product, quantity, weight, note, cfees) et le statut de facturation vis-à-vis de votre compte (billingStatus, factureCode, facturePaidAt).

Requête
curl "https://api.atlaslivraison.com/api/external/colis/ATL123456" \
  -H "x-api-key: atl_VOTRE_CLE"
Réponse
200 OK
{
  "success": true,
  "data": {
    "code": "ATL123456",
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "cityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "address": "12 Rue des Fleurs, Maârif",
    "cityName": "Casablanca",
    "price": "249.00",
    "cfees": "20.00",
    "product": "Sneakers",
    "quantity": 1,
    "stateId": 17,
    "stateName": "Livré",
    "dateDelivered": "2026-07-23T14:30:00.000Z",
    "billingStatus": "paid",
    "factureCode": "FAC-260725-0012",
    "facturePaidAt": "2026-07-26T09:00:00.000Z",
    "gpsLat": "33.5883",
    "gpsLng": "-7.6114",
    "createdAt": "2026-07-22T10:00:00.000Z",
    "updatedAt": "2026-07-23T14:30:00.000Z"
  }
}

Et bien plus, une fois connecté

L'API couvre tout le cycle de vie de vos colis. La référence complète de ces fonctionnalités — endpoints, paramètres et exemples — est disponible dans Paramètres API de votre tableau de bord.

Création en lot

Envoyez plusieurs colis en un seul appel, ou branchez directement le webhook de commande de votre plateforme e-commerce.

Historique & synchronisation

Timeline complète de chaque colis, état de nombreux colis en un appel et synchronisation incrémentale.

Modifier & annuler

Corrigez ou annulez un colis tant qu’il n’est pas encore collecté.

Actions en cours de livraison

Changement de destinataire, report de livraison, demande de retour.

Remboursements

Remboursez un client sur un colis livré, avec ou sans retour de l’article.

Ramassage

Créez et suivez vos demandes d’enlèvement.

Réclamations & messages

Ouvrez un ticket, suivez la conversation et répondez depuis votre propre outil.

Factures & portefeuille

Consultez vos factures, votre solde, vos transactions et votre résumé de revenus.

Retours

Suivez les bons de retour qui vous sont destinés.

Se connecter pour la documentation complète
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). 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. Chaque envoi est signé en HMAC-SHA256 (en-tête X-Atlas-Signature) — évitez le polling.

Limites de débit

Des limites de débit s'appliquent par compte, en lecture comme en écriture (relevables pour les gros comptes) ; vos quotas sont indiqués dans Paramètres API. 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