API - الاتصال والتفويض

المصادقة وعنوان URL الأساسي

https://alterproduct.com/public-api/v1

أنشئ بيانات اعتماد API في لوحة إعدادات التجارة الإلكترونية. يُعرض Access Token مرة واحدة، لذا احفظه فورًا في مخزن الأسرار لخلفيتك البرمجية.

احتفظ بـ Access Key وAccess Token على خادمك. ترفض نقاط النهاية التي تتطلب مصادقة الاستدعاءات القادمة من المتصفح التي تتضمن ترويسات Origin أو Referer.

يمكن تحديد نطاقات صلاحيات بيانات الاعتماد. استخدم GET /auth/check للتحقق من واجهة المتجر النشطة وإمكانات الخطة ونطاقات الصلاحيات المعادة لبيانات الاعتماد.

x-alter-access-key: YOUR_API_KEY
x-alter-access-token: YOUR_API_TOKEN

اختبار الاتصال

استخدم نقطة نهاية فحص المصادقة قبل تفعيل المزامنة أو ميزات التضمين في تكامل قيد التشغيل الفعلي.

GET https://alterproduct.com/public-api/v1/auth/check

مثال طلب (fetch)

const response = await fetch('https://alterproduct.com/public-api/v1/auth/check', {
  method: 'GET',
  headers: {
    'x-alter-access-key': process.env.ALTER_ACCESS_KEY,
    'x-alter-access-token': process.env.ALTER_ACCESS_TOKEN
  }
});

const payload = await response.json();

if (!response.ok) {
  throw new Error(payload?.code || payload?.error || `Alter API ${response.status}`);
}

console.log(payload);

مثال رد

{
  "ok": true,
  "message": "success",
  "storefrontId": 12,
  "userOwnerId": 34,
  "credentialId": 56,
  "scopes": ["orders:read", "orders:write", "products:read"],
  "plan": {
    "requiredPlan": "Business",
    "currentPlanName": "Business",
    "eligible": true,
    "runtimeFlags": {
      "viewer": true,
      "configurator": true,
      "customizer": true
    },
    "limits": {
      "activeRuntimeBindingsLimit": 100,
      "monthlyReassignmentLimit": 1000,
      "monthlyEmbedTokenLimit": 50000
    }
  }
}

تستخدم الأمثلة التالية الدالة المساعدة أدناه. وهي تعتمد على fetch مباشرة وتعمل في Node.js 18+ أو أي بيئة تشغيل خادم توفر fetch.

const ALTER_API_BASE = 'https://alterproduct.com/public-api/v1';

const authHeaders = {
  'x-alter-access-key': process.env.ALTER_ACCESS_KEY,
  'x-alter-access-token': process.env.ALTER_ACCESS_TOKEN
};

async function alterFetch(path, options = {}) {
  const response = await fetch(`${ALTER_API_BASE}${path}`, {
    ...options,
    headers: {
      ...authHeaders,
      ...(options.body ? { 'Content-Type': 'application/json' } : {}),
      ...options.headers
    }
  });

  const payload = await response.json().catch(() => null);

  if (!response.ok) {
    throw new Error(payload?.code || payload?.error || `Alter API ${response.status}`);
  }

  return payload;
}

الأخطاء وحدود الطلبات

تُوحّد معظم أخطاء وحدات التحكم في رد يحتوي على code. وقد تعيد برمجيات المصادقة الوسيطة ومحددات المعدل ردًا يحتوي على error بدلًا منه.

// Controller error
{
  "code": "assetCatalog.invalidType"
}

// Auth middleware or rate limit
{
  "error": "Unauthorized"
}

{
  "error": "Too Many Requests"
}