الانتقال إلى المحتوى
Rate Extra

مصادقة API بتوقيع HMAC-SHA256

طلبات TravelDistro موقّعة لا مرمّزة. تحمل ترويسة Authorization معرّف مفتاحك وتوقيعًا على الطلب؛ وتحمل ترويستان الطابع الزمني وقيمة nonce. لا يُدعم Bearer token.

ما الذي يُوقَّع

التوقيع هو HMAC-SHA256 بمفتاح سرّ API الخاص بك على ستة أسطر مفصولة بسطر جديد:

  1. 01طريقة HTTP بأحرف كبيرة
  2. 02مسار الطلب
  3. 03سلسلة الاستعلام مرتبة، أو فارغة
  4. 04الطابع الزمني Unix بالثواني
  5. 05قيمة nonce فريدة لكل طلب
  6. 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