المطورون
واجهة API للتاجر
واجهة REST للقراءة فقط لمتجرك على VeeBoost: عقد منشور واحد، ومصادقة بالمفتاح، وترقيم صفحات متوقع — مصممة لتكاملات تبقى متزامنة.
عقد واحد، منشور بوصفه المصدر الوحيد للحقيقة
ينشر متجرك العقد الكامل القابل للقراءة آليا (OpenAPI 3.1): كل نقطة نهاية ومعامل واستجابة ورمز خطأ في واجهة التاجر. تشير هذه الصفحة إليه ولا تعيد أبدا نسخ جداول نقاط النهاية — لا يمكن للعقد أن ينحرف، ولا لتكاملك أيضا.
GET /openapi/v1.jsonالبداية السريعة
ثلاث خطوات لقراءتك الأولى للكتالوج:
- أنشئ مفتاح API في لوحة الإدارة (قسم المطورين) مع نطاقات القراءة التي تحتاجها. يبدأ بـ vbk_ ويُعرض مرة واحدة فقط.
- أرسله في ترويسة X-Api-Key مع كل طلب — يُستخرج متجرك من المفتاح، لا من المضيف أبدا.
- استدعِ نقطة النهاية الأولى، مثلا GET /products، ثم اتبع العقد في كل ما تبقى.
المصادقة
كل طلب يحمل مفتاحك في ترويسة X-Api-Key. توفر v1 أربعة نطاقات قراءة بالضبط — المنتجات والطلبات والعملاء وتسليمات الويب هوك. النطاق الناقص يرد بـ 403، والمفتاح الملغى يرفض فورا. احتفظ بالمفاتيح على الخادم: لا مكان لها في متصفح أو مستودع عام.
products:readorders:readcustomers:readwebhooks:readترقيم الصفحات
نقاط نهاية القوائم مرقمة: تنقلها بمعامل page واقرأ الغلاف المرجع مع كل مجموعة — يحدد أين أنت لتعيد مزامنة تكاملك دون تخمين. المعاملات الدقيقة لكل نقطة نهاية موثقة في العقد.
الأخطاء وحدود المعدل
الأخطاء تعيد نص JSON منظما يمكنك تحليله، لا فقرة تكشطها أبدا. الاستجابة 429 عقد مستقر: نفس شكل النص كل مرة، مع ترويسات X-RateLimit-* وRetry-After يقول بالضبط متى تعود. الإلحاح لا يفتح البيانات — تراجع.
مفاتيح sandbox
خلال مرحلة ما قبل الإطلاق، تصدر مفاتيح sandbox بعد تحقق فريقنا وتعمل بحد معدل مخصص، منفصل عن مفاتيح الإنتاج — استكشف الواجهة على متجرك دون المساس بالحركة الحية أو الحصص.
أمثلة حسب اللغة
مقتطف واحد لكل منصة، نطاقات قراءة فقط: كل منها يجلب كتالوج منتجاتك. استبدل <api-base> بمضيف API لمتجرك من لوحة الإدارة ← قسم المطورين.
curl
curl -H "X-Api-Key: vbk_your_key" \
"https://<api-base>/products?page=1"JavaScript
async function listProducts(page = 1) {
const res = await fetch("https://<api-base>/products?page=" + page, {
headers: { "X-Api-Key": "vbk_your_key" },
});
if (res.status === 429) {
// Structured contract: honor Retry-After, never screen-scrape.
const wait = Number(res.headers.get("Retry-After")) * 1000;
await new Promise((done) => setTimeout(done, wait));
return listProducts(page);
}
if (!res.ok) throw new Error("products:read failed with " + res.status);
return res.json();
}Python
import requests
def list_products(page=1):
res = requests.get(
"https://<api-base>/products",
params={"page": page},
headers={"X-Api-Key": "vbk_your_key"},
timeout=10,
)
res.raise_for_status()
return res.json()v1 للقراءة فقط بالتصميم: products:read وorders:read وcustomers:read وwebhooks:read هي النطاقات الوحيدة الموجودة. نطاقات الكتابة ستكون قرار v1.x موثقا صراحة — لا شيء يخطط له بصمت.