البداية السريعة
من صفر إلى أول استدعاء في 10 دقائق
تعلم كيف تصدر مفتاحاً، تستعلم عن استخدامك، وتسجّل ويب هوك موقّع لتستقبل أحداث ڤايا. كل مثال يعمل كما هو.
أنشئ حساباً
سجّل حسابك من بوابة المطورين خلال دقيقتين — تأكيد البريد الإلكتروني فوري ولا حاجة لمراجعة يدوية.
إنشاء حساب مطوّر — مجاناًاحصل على مفتاح اختبار
من لوحة تحكم المطور (Developers → API Keys) أنشئ مفتاحاً جديداً. يأتي المفتاح افتراضياً بنطاق "tenants:read" الذي يتيح قراءة الاستخدام؛ فعّل "webhooks:manage" إذا كنت ستدير الويب هوكس. سيظهر المفتاح الكامل مرة واحدة فقط — انسخه على الفور.
sk_test_ وهي معزولة عن حركة مرورك المباشرة وفوترتك.أرسل أول استدعاء
صدّر مفتاحك ثم استعلم عن استخدامك للشهر الحالي — أبسط نقطة نهاية مصادَقة بمفتاح API.
export VIA_API_KEY="sk_test_…" curl https://sandbox.api.via-basket.com/v1/usage/current-month \ -H "Authorization: Bearer $VIA_API_KEY"
افهم الاستجابة
تُغلّف نقاط النهاية نتائجها داخل حقل data. استجابة الاستخدام تلخّص عدد الاستدعاءات والحصة المشمولة وزمن الاستجابة.
{
"data": {
"calls": 1284,
"included": 100000,
"p50_latency_ms": 42,
"p99_latency_ms": 180
}
}استكشف أنواع الأحداث
قبل تسجيل ويب هوك، اطّلع على أنواع الأحداث التي يمكنك الاشتراك بها. هذه النقطة لا تتطلب أي نطاق.
curl https://sandbox.api.via-basket.com/v1/webhooks/events \ -H "Authorization: Bearer $VIA_API_KEY"
أعدّ نقطة ويب هوك
سجل نقطة https:// خاصة بك واشترك في أحداث order.*. ستخزن ڤايا السر الموقع للمفتاح.
curl -X POST https://sandbox.api.via-basket.com/v1/webhooks \
-H "Authorization: Bearer $VIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/via",
"events": ["order.created", "order.status_changed", "order.delivered"],
"description": "Production dispatch integration"
}'تحقق من توقيعات HMAC
كل حمولة تأتي مع ترويسة X-VIA-Signature من الشكل t=<ts>,v1=<hex>. تحقق بالسر قبل الثقة بالمحتوى.
import express from 'express';
import { verifySignature } from '@via/sdk';
const app = express();
app.post(
'/hooks/via',
express.raw({ type: 'application/json' }), // raw body is load-bearing
(req, res) => {
const sig = req.header('X-VIA-Signature') ?? '';
if (!verifySignature(req.body, sig, process.env.VIA_WEBHOOK_SECRET!)) {
return res.status(400).end();
}
const event = JSON.parse(req.body.toString());
// …fulfil event…
res.status(204).end();
},
);انتقل إلى الإنتاج
من نفس اللوحة، اسحب مفتاح sk_live_. بدّل متغيرات البيئة فقط — لا تغيير في الكود. تكتشف مكتبات ڤايا المضيف تلقائياً من بادئة المفتاح.
راقب الاستخدام
راقب الحصة اليومية وحدود المعدل من لوحة Developers → Usage. نُرسل تنبيهاً عبر البريد عند 80% من الحد الشهري.
فتح لوحة الاستخدامرقّي خطتك
إذا اقتربت من حدك، رقّي خطتك مباشرة من إعدادات البوابة (زر Manage billing).
ما التالي؟
اغرق في المرجع الكامل أو استكشف كل الأحداث.