مصادقة API بتوقيع HMAC-SHA256
طلبات TravelDistro موقّعة لا مرمّزة. تحمل ترويسة Authorization معرّف مفتاحك وتوقيعًا على الطلب؛ وتحمل ترويستان الطابع الزمني وقيمة nonce. لا يُدعم Bearer token.
ما الذي يُوقَّع
التوقيع هو HMAC-SHA256 بمفتاح سرّ API الخاص بك على ستة أسطر مفصولة بسطر جديد:
- 01طريقة HTTP بأحرف كبيرة
- 02مسار الطلب
- 03سلسلة الاستعلام مرتبة، أو فارغة
- 04الطابع الزمني Unix بالثواني
- 05قيمة nonce فريدة لكل طلب
- 06SHA-256 hex لمحتوى الطلب، وللسلسلة الفارغة في GET
الترويسات
- Authorization
- TD-HMAC-SHA256 KeyId=<key_id>, Signature=<hex>
- X-TD-Timestamp
- ثوانٍ Unix؛ يجب أن تكون ضمن 300 ثانية من وقت الخادم
- X-TD-Nonce
- فريدة لكل طلب؛ تُرفض القيمة المكررة
مثال Node.js
import crypto from "node:crypto";
const keyId = process.env.TD_KEY_ID!;
const secret = process.env.TD_SECRET!;
const method = "GET";
const path = "/v1/account"; // request path as sent to the server
const query = ""; // sorted query string, empty if none
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();
const body = "";
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const stringToSign = [method, path, query, timestamp, nonce, bodyHash].join("\n");
const signature = crypto.createHmac("sha256", secret).update(stringToSign).digest("hex");
const res = await fetch("https://api.traveldistro.com" + path, {
headers: {
Authorization: `TD-HMAC-SHA256 KeyId=${keyId}, Signature=${signature}`,
"X-TD-Timestamp": timestamp,
"X-TD-Nonce": nonce,
},
});تحقق من صيغة المسار الدقيقة (مع بادئة /v1 أو دونها) من المرجع ومفتاح اختبار قبل الإطلاق؛ المرجع هو الحجة.
القواعد
- يجب أن يكون الطابع الزمني ضمن ±300 ثانية من وقت الخادم.
- تُستخدم قيمة nonce مرة واحدة فقط؛ وتُرفض الإعادة.
- لا يُقبل Bearer token في أي مكان من واجهة API للوكالات.
- احتفظ بالسر على خادمك؛ ولا ترسله أبدًا إلى متصفح أو تطبيق جوال.
أخطاء المصادقة
- 401
- مفتاح مفقود أو غير صالح أو ملغى
- 403
- IP ليس في قائمة المفتاح المسموح بها، أو الوكالة موقوفة، أو MODULE_NOT_ENABLED
- 429
- RATE_LIMITED؛ انتظر Retry-After ثانية وأعد إرسال الطلب نفسه
وكالة سفر مرخّصة؟ قدّم طلب الوصول إلى API.
احصل على وصول API