AtlasSwift API

v1.0

Intégrez AtlasSwift à vos applications pour automatiser la création de commandes, gérer vos produits et suivre vos livraisons.

API REST

JSONFormat

Pour commencer

Suivez ces 3 étapes pour commencer à utiliser l'API AtlasSwift.

Créez un compte

Inscrivez-vous sur AtlasSwift et accédez à votre compte.

Générez votre clé API

Allez dans Intégrations depuis le menu latéral et cliquez sur Générer pour obtenir votre clé API.

Faites votre premier appel

Utilisez votre clé pour créer votre première commande via l'API.

Base URL

https://api.atlasswift.com

Authentification

Toutes les requêtes API doivent inclure votre clé API dans l'en-tête d'autorisation.

Exception: GET /v1/public/currencies est un endpoint public qui ne nécessite pas d'authentification.

En-tête Authorization

Authorization: Bearer atlas_live_xxxxxxxxxxxxxxxxxxxxxxxx

Important

Gardez votre clé API secrète. Ne la partagez jamais dans du code client ou des dépôts publics.

Commandes

Gérez les commandes de vos clients

POST/v1/public/orders

Créer une nouvelle commande

Paramètres du corps

Nom	Type	Requis	Description
`client_name`	string	Requis	Nom complet du client
`client_phone`	string	Requis	Numéro de téléphone avec indicatif
`client_address`	string	Requis	Adresse de livraison
`arrival_country`	string	Requis	Pays de destination
`products`	array	Requis	Liste des produits commandés
`products[].product_id`	string	Optionnel	ID du produit tel qu'affiché sur votre page Produits AtlasSwift (ex: PRD-001586). Requis si name est absent.
`products[].name`	string	Optionnel	Nom exact du produit sur AtlasSwift. Utilisé pour rechercher le produit si product_id est absent.
`products[].quantity`	integer	Requis	Quantité (> 0)
`products[].price`	number	Requis	Prix unitaire (> 0)
`products[].variant_id`	string	Optionnel	ID de la variante (ex: comb_abc123)
`products[].variant_name`	string	Optionnel	Nom de la variante (ex: "Noir - L")
`total_price`	number	Requis	Prix total de la commande
`currency_code`	string	Requis	Code devise (ex: XOF, EUR)
`delivery_note`	string	Optionnel	Instructions de livraison

Corps de la requête

JSON

{
  "client_name": "Jean Dupont",
  "client_phone": "+2250701020304",
  "client_address": "Cocody Angré, Abidjan",
  "arrival_country": "Côte d'Ivoire",
  "products": [
    {
      "product_id": "PRD-001586",
      "name": "Montre Connectée Prestige X9",
      "quantity": 1,
      "price": 185000,
      "variant_id": "comb_abc123",
      "variant_name": "Noir - L"
    },
    {
      "product_id": "PRD-002345",
      "name": "Sac à Dos Cuir Véritable",
      "quantity": 1,
      "price": 150000
    }
  ],
  "total_price": 335000,
  "currency_code": "XOF",
  "delivery_note": "Appeler avant 16h"
}

Réponse

JSON

{
  "success": true,
  "message": "Commande enregistrée avec succès.",
  "data": {
    "order_id": "ORD-1717778456123"
  }
}

Exemple de code

curl -X POST "https://api.atlasswift.com/v1/public/orders" \
  -H "Authorization: Bearer atlas_live_xxxxxxxx"
  -H "Content-Type: application/json" \
  -d '{
  "client_name": "Jean Dupont",
  "client_phone": "+2250701020304",
  "client_address": "Cocody Angré, Abidjan",
  "arrival_country": "Côte d'Ivoire",
  "products": [
    {
      "product_id": "PRD-001586",
      "name": "Montre Connectée Prestige X9",
      "quantity": 1,
      "price": 185000,
      "variant_id": "comb_abc123",
      "variant_name": "Noir - L"
    },
    {
      "product_id": "PRD-002345",
      "name": "Sac à Dos Cuir Véritable",
      "quantity": 1,
      "price": 150000
    }
  ],
  "total_price": 335000,
  "currency_code": "XOF",
  "delivery_note": "Appeler avant 16h"
}'

Produits

Récupérez la liste de vos produits

GET/v1/public/products

Récupérer la liste des produits

Paramètres de requête

Nom	Type	Requis	Description
`limit`	integer	Optionnel	Nombre par page (défaut: 20)
`offset`	integer	Optionnel	Décalage pour pagination (défaut: 0)
`search`	string	Optionnel	Recherche par nom de produit
`order_by`	string	Optionnel	Champ de tri
`is_active`	boolean	Optionnel	Filtrer par statut actif (true/false)

Réponse

JSON

{
  "success": true,
  "message": "Produits récupérés avec succès",
  "data": {
    "data": [
      {
        "id": "PRD-001586",
        "seller_id": "seller_abc123",
        "name": "Montre Connectée Prestige X9",
        "description": "Montre connectée avec suivi de santé",
        "price": 185000,
        "currency_code": "XOF",
        "image_url": "https://example.com/image.jpg",
        "image_urls": [
          "https://example.com/image.jpg"
        ],
        "is_active": true,
        "category": "Électronique",
        "slug": "montre-connectee-prestige-x9",
        "variants": {
          "types": [
            {
              "id": "type_1",
              "name": "Couleur",
              "values": [
                {
                  "id": "opt_1",
                  "name": "Noir"
                }
              ]
            }
          ],
          "combinations": [
            {
              "id": "comb_abc123",
              "name": "Noir - L",
              "options": {
                "Couleur": "Noir"
              },
              "price": 185000,
              "is_active": true
            }
          ]
        },
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-06-01T14:00:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 20,
    "offset": 0,
    "total_pages": 3
  }
}

Exemple de code

curl -X GET "https://api.atlasswift.com/v1/public/products" \
  -H "Authorization: Bearer atlas_live_xxxxxxxx"
  -H "Content-Type: application/json"

Devises

Récupérez la liste des devises supportées

GET/v1/public/currencies

Récupérer la liste des devises supportées

Réponse

JSON

{
  "success": true,
  "data": [
    {
      "currency_code": "XOF",
      "currency_name": "West African CFA franc",
      "rate_to_usd": 0.0016,
      "updated_at": "2024-06-01T12:00:00Z"
    },
    {
      "currency_code": "EUR",
      "currency_name": "Euro",
      "rate_to_usd": 1.08,
      "updated_at": "2024-06-01T12:00:00Z"
    }
  ],
  "count": 2
}

Exemple de code

curl -X GET "https://api.atlasswift.com/v1/public/currencies" \
  -H "Content-Type: application/json"

Webhooks

Configurez un ou plusieurs endpoints HTTPS pour être notifié en temps réel des changements de statut des commandes créées via votre clé API. Chaque endpoint dispose d'un secret de signature unique.

Événements disponibles

Événement	Description
order.created	Commande créée via POST /v1/public/orders
order.confirmed	Commande confirmée par le centre d'appels
order.callback_requested	Rappel téléphonique au client planifié
order.unreachable	Client injoignable
order.scheduled	Livraison planifiée
order.duplicate	Commande marquée comme doublon
order.out_of_stock	Rupture de stock pour le pays de destination
order.arrived	Commande arrivée à l'entrepôt de destination
order.delivered	Commande livrée au client
order.paid	Commande soldée au vendeur
order.completed	Commande entièrement terminée
order.cancelled	Commande annulée
order.returned	Commande retournée par le client
order.failed	Échec de la tentative de livraison

Format du payload

POST <URL de votre endpoint>

{
  "id": "evt_8f1d3a8c-...",
  "type": "order.delivered",
  "created_at": "2026-05-04T14:25:00Z",
  "data": {
    "order": {
      "id": "ORDP12345...",
      "status": "Livrée",
      "client": {
        "name": "Jane Doe",
        "phone": "+22997000000",
        "address": "123 Rue de la Paix"
      },
      "products": [
        {
          "product_id": "PRD-...",
          "product_name": "T-shirt L",
          "quantity": 1,
          "unit_price": 5000,
          "total_price": 5000
        }
      ],
      "total_price": 5500,
      "currency_code": "XOF",
      "arrival_country": "BJ",
      "delivery_note": "Sonner deux fois",
      "created_at": "2026-05-04T13:55:00Z",
      "delivered_at": "2026-05-04T14:25:00Z"
    },
    "transition": {
      "from": "Programmée",
      "to": "Livrée",
      "comment": "Client présent",
      "occurred_at": "2026-05-04T14:25:00Z"
    }
  }
}

Signature HMAC

Chaque requête inclut un en-tête Atlasswift-Signature. Vérifiez l'authenticité en recalculant un HMAC-SHA256 sur "<timestamp>.<corps brut>" avec votre secret.

En-têtes

Atlasswift-Signature: t=1714834800,v1=8b9c4...
Atlasswift-Event-Id: 8f1d3a8c-...
Atlasswift-Event-Type: order.delivered
Content-Type: application/json
User-Agent: AtlasSwift-Webhook/1.0

Vérification Node.js

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=')),
  );
  const expected = crypto
    .createHmac('sha256', secret)
    .update(parts.t + '.' + rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(parts.v1, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

Politique de réessais

Répondez 2xx dans les 10 secondes pour acquitter une livraison.
En cas d'échec, AtlasSwift réessaie jusqu'à 8 fois avec un backoff exponentiel (~17 minutes au total).
Après 20 échecs consécutifs sur un endpoint, celui-ci est automatiquement désactivé.
Utilisez Atlasswift-Event-Id pour rendre votre traitement idempotent.

Gestion des erreurs

L'API utilise les codes HTTP standards pour indiquer le succès ou l'échec d'une requête.

Code	Description
`400`	Données manquantes ou invalides
`401`	Clé API absente ou mal formée
`403`	Clé API invalide ou désactivée
`404`	Ressource non trouvée
`429`	Trop de requêtes (rate limiting)
`500`	Erreur serveur interne

Format d'erreur

JSON

{
  "success": false,
  "message": "Données invalides",
  "errors": [
    {
      "field": "client_phone",
      "message": "Format de téléphone invalide"
    }
  ]
}

Limites de débit

L'API applique des limites de requêtes pour garantir la stabilité du service. Les limites sont appliquées par clé API.

Standard

60 requêtes par minute par clé API.

Limite dépassée

Réponse 429 Too Many Requests. Attendez avant de réessayer.