توثيق API
أنشئ روابطك وأدرها واسحب إحصاءاتها برمجيًا عبر REST API من Quik.mn.
كل الخدمات
كل منتجات منصّة Quik.mn — عبر REST API وعلى الويب.
العنوان الأساسي
تبدأ كل نقاط النهاية من العنوان الأساسي الآتي:
المصادقة
أرفق مع كل طلب مفتاح API الذي حصلت عليه من لوحة التحكّم في ترويسة Authorization كما يلي:
لا تشارك مفتاحك مع أحد. وإن تسرّب، أعد إنشاءه من لوحة التحكّم.
نقاط النهاية
المعاملات
POST /api/v1/links — حقول جسم الطلب:
GET /api/v1/links — معاملات الاستعلام:
صيغة الخطأ
يعود كل خطأ برمز حالة HTTP (401 أو 404 أو 409 أو 422 أو 429) وببنية JSON موحّدة:
{ "error": "alias_taken", "message": "هذا الاسم المستعار محجوز أو مستخدم بالفعل." }
الرموز الشائعة: unauthorized (401), not_found (404), alias_taken (409), invalid_url / invalid_alias / invalid_expires_at / invalid_starts_at (422), rate_limited (429).
حدود الاستخدام
مثال على الطلب
مثال cURL لإنشاء رابط قصير:
curl -X POST https://quik.mn/api/v1/links \
-H "Authorization: Bearer qk_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/مسار/طويل/جدا",
"alias": "promo",
"title": "حملة الربيع",
"expires_at": "2026-12-31 23:59:59"
}'
Webhook
سجّل endpoint في قسم Webhook داخل لوحة التحكّم، وسنرسل طلب POST بصيغة JSON إلى عنوان URL الخاص بك فور وقوع أي حدث تختاره. الاستجابة 2xx تعني النجاح، وإلا أعدنا المحاولة حتى ثلاث مرات بفاصل يتدرّج من دقيقة واحدة إلى عشر دقائق. وبعد عشرة إخفاقات متتالية يُعطَّل webhook تلقائيًا.
بنية كل عملية إرسال (مثال):
{
"event": "link.created",
"created_at": "2026-07-18T09:30:00+00:00",
"data": {
"link": {
"id": 42, "slug": "promo", "short_url": "https://quik.mn/promo",
"long_url": "https://example.com/مسار/طويل/جدا", "title": "حملة الربيع",
"clicks": 0, "active": true, "state": "ok",
"created_at": "2026-07-18 09:30:00", "expires_at": "2027-07-18 09:30:00"
}
}
}
التحقّق من التوقيع
يصل كل إرسال مصحوبًا بالترويسات الآتية: X-Quik-Event (اسم الحدث), X-Quik-Signature — sha256=HMAC_SHA256(body, secret). يظهر المفتاح السري مرة واحدة فقط عند إنشاء الخطاف. وتحقّق من التوقيع دائمًا على جسم الطلب الخام وبمقارنة ثابتة الزمن:
<?php
// PHP — تحقق من التوقيع على جسم الطلب الخام (raw)
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_QUIK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('invalid signature');
}
$event = json_decode($payload, true);
// $event['event'], $event['data'] ...
http_response_code(200);
// Node.js (Express) — تحقق من التوقيع على جسم الطلب الخام (raw)
const crypto = require('crypto');
app.post('/quik-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.get('X-Quik-Signature') || '';
const expected = 'sha256=' +
crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const a = Buffer.from(expected), b = Buffer.from(signature);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).send('invalid signature');
}
const event = JSON.parse(req.body); // event.event, event.data ...
res.sendStatus(200);
});
الحدود: باقة Free خطاف واحد، وباقة Pro ثلاثة، وباقة Business عشرة. ويجب أن تكون نقطة النهاية عنوانًا عامًّا متاحًا على الإنترنت (عناوين الشبكات الداخلية محظورة).
