AtlasSwift API

v1.0

ادمج AtlasSwift في تطبيقاتك لأتمتة إنشاء الطلبات وإدارة منتجاتك وتتبع عمليات التسليم.

REST API

JSONالصيغة

البدء

اتبع هذه الخطوات الثلاث لبدء استخدام API AtlasSwift.

إنشاء حساب

سجل في AtlasSwift وادخل إلى حسابك.

إنشاء مفتاح API

اذهب إلى التكاملات من القائمة الجانبية وانقر على إنشاء للحصول على مفتاح API الخاص بك.

أجرِ أول طلب

استخدم مفتاحك لإنشاء أول طلب عبر API.

عنوان URL الأساسي

https://api.atlasswift.com

المصادقة

يجب أن تتضمن جميع طلبات API مفتاح API الخاص بك في ترويسة التفويض.

استثناء: GET /v1/public/currencies هو نقطة وصول عامة لا تتطلب مصادقة.

ترويسة Authorization

Authorization: Bearer atlas_live_xxxxxxxxxxxxxxxxxxxxxxxx

مهم

حافظ على سرية مفتاح API الخاص بك. لا تشاركه أبداً في كود العميل أو المستودعات العامة.

الطلبات

إدارة طلبات عملائك

POST/v1/public/orders

إنشاء طلب جديد

معلمات الجسم

الاسم	النوع	مطلوب	الوصف
`client_name`	string	مطلوب	الاسم الكامل للعميل
`client_phone`	string	مطلوب	رقم الهاتف مع رمز البلد
`client_address`	string	مطلوب	عنوان التسليم
`arrival_country`	string	مطلوب	بلد الوجهة
`products`	array	مطلوب	قائمة المنتجات المطلوبة
`products[].product_id`	string	اختياري	معرّف المنتج كما يظهر في صفحة المنتجات على AtlasSwift (مثال: PRD-001586). مطلوب إذا لم يتم تقديم الاسم.
`products[].name`	string	اختياري	الاسم الدقيق للمنتج على AtlasSwift. يُستخدم للبحث عن المنتج إذا لم يتم تقديم product_id.
`products[].quantity`	integer	مطلوب	الكمية (> 0)
`products[].price`	number	مطلوب	سعر الوحدة (> 0)
`products[].variant_id`	string	اختياري	معرّف المتغير (مثال: comb_abc123)
`products[].variant_name`	string	اختياري	اسم المتغير (مثال: "أسود - L")
`total_price`	number	مطلوب	السعر الإجمالي للطلب
`currency_code`	string	مطلوب	رمز العملة (مثال: XOF, EUR)
`delivery_note`	string	اختياري	تعليمات التسليم

جسم الطلب

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"
}

الاستجابة

JSON

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

مثال الكود

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"
}'

المنتجات

استرجاع قائمة منتجاتك

GET/v1/public/products

استرجاع قائمة المنتجات

معلمات الاستعلام

الاسم	النوع	مطلوب	الوصف
`limit`	integer	اختياري	العدد في الصفحة (الافتراضي: 20)
`offset`	integer	اختياري	الإزاحة للتصفح (الافتراضي: 0)
`search`	string	اختياري	البحث بالاسم
`order_by`	string	اختياري	حقل الترتيب
`is_active`	boolean	اختياري	تصفية حسب الحالة النشطة (true/false)

الاستجابة

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
  }
}

مثال الكود

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

العملات

استرجاع قائمة العملات المدعومة

GET/v1/public/currencies

استرجاع قائمة العملات المدعومة

الاستجابة

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
}

مثال الكود

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

Webhooks

اضبط نقطة أو أكثر من نقاط HTTPS لاستقبال إشعارات فورية عند تغيّر حالة الطلبات التي أُنشئت بمفتاح API الخاص بك. لكل نقطة endpoint سر توقيع خاص.

الأحداث المتاحة

الحدث	الوصف
order.created	تم إنشاء الطلب عبر POST /v1/public/orders
order.confirmed	تم تأكيد الطلب من مركز الاتصال
order.callback_requested	تم جدولة اتصال بالعميل
order.unreachable	تعذر الوصول إلى العميل
order.scheduled	تم جدولة التسليم
order.duplicate	تم وسم الطلب كمكرر
order.out_of_stock	نفاد المخزون لبلد الوجهة
order.arrived	وصل الطلب إلى مستودع الوجهة
order.delivered	تم تسليم الطلب للعميل
order.paid	تم صرف المبلغ للبائع
order.completed	اكتمل الطلب بالكامل
order.cancelled	تم إلغاء الطلب
order.returned	أعاد العميل الطلب
order.failed	فشلت محاولة التسليم

صيغة الحمولة

POST <عنوان نقطة النهاية>

{
  "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"
    }
  }
}

توقيع HMAC

تتضمن كل طلب ترويسة Atlasswift-Signature. تحقق من الصحة بإعادة حساب HMAC-SHA256 على "<timestamp>.<الجسم الخام>" باستخدام سرّك.

الترويسات

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

التحقق بـ 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'),
  );
}

سياسة إعادة المحاولة

أجب برمز 2xx خلال 10 ثوانٍ لتأكيد الاستلام.
عند الفشل، يعيد AtlasSwift المحاولة حتى 8 مرات بتأخير أسي (~17 دقيقة إجمالاً).
بعد 20 فشلاً متتالياً على نقطة endpoint، يتم تعطيلها تلقائياً.
استخدم Atlasswift-Event-Id لجعل المعالجة قابلة للتكرار بأمان.

إدارة الأخطاء

تستخدم واجهة API رموز HTTP القياسية للإشارة إلى نجاح أو فشل الطلب.

الرمز	الوصف
`400`	بيانات مفقودة أو غير صالحة
`401`	مفتاح API مفقود أو غير صحيح
`403`	مفتاح API غير صالح أو معطل
`404`	المورد غير موجود
`429`	طلبات كثيرة جداً (تحديد المعدل)
`500`	خطأ داخلي في الخادم

صيغة الخطأ

JSON

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

حدود المعدل

تطبق واجهة API حدود الطلبات لضمان استقرار الخدمة. يتم تطبيق الحدود لكل مفتاح API.

قياسي

60 طلب في الدقيقة لكل مفتاح API.

تجاوز الحد

استجابة 429 طلبات كثيرة. انتظر قبل إعادة المحاولة.