المفاتيح والتوقيع

المفاتيح

لكل حساب شريك مفاتيح منفصلة للتجربة والتشغيل. تنشئها وتلغيها من لوحة المطورين على developers.aurages.com قريبا.

• مفتاح التجربة يعمل على عنوان التجربة فقط، ومفتاح التشغيل على عنوان التشغيل فقط.
• مفاتيح التشغيل تصدر بعد الاعتماد.
• السر مكانه خادمك فقط. لا تضعه في تطبيق جوال، ولا في متصفح، ولا في سجلات.

عنوان التجربة يعمل الآن بمفاتيح التجربة. عنوان التشغيل يفتح لكل مطور بعد مراجعة تكامله واعتماده.

الترويسات

كل طلب يحمل هذه الترويسات:

طريقة التوقيع

كون نصا من خمسة أسطر، يفصل بينها \n:

METHOD
PATH
TIMESTAMP
NONCE
hex(SHA256(raw_body))

ثم احسب HMAC-SHA256 لهذا النص بالسر، واكتبه hex.

• METHOD بحروف كبيرة: GET أو POST أو PUT أو PATCH أو DELETE.
• PATH هو كل ما بعد اسم الخادم كما أرسلته تماما، مع /v1 ومع نص الاستعلام. مثال: /v1/orders?status=received&limit=50.
• raw_body هو البايتات نفسها التي ترسلها. وقع النص الذي ترسله، لا كائنا تعيد ترميزه بعد التوقيع.
• طلب بلا جسم يوقع بنص فارغ، وبصمته e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

مثال تتحقق به من شيفرتك

إذا خرج توقيعك مطابقا، فشيفرتك صحيحة.

Node

import crypto from 'node:crypto';

export function sign(secret, method, path, ts, nonce, body) {
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const canonical = [method.toUpperCase(), path, ts, nonce, bodyHash].join('\n');
  return crypto.createHmac('sha256', secret).update(canonical).digest('hex');
}

// المثال أعلاه
console.log(sign(
  'sk_test_example_secret_do_not_use', 'PATCH',
  '/v1/places/plc_9q3w7e/menu/state', '1760443200',
  'n0nce_Example_1234567890', '{"as_of":"2026-10-14T18:00:00Z","sold_out":{"items":["kunafa"],"sizes":[],"options":[]}}'
)); // ec96466e...b3c8

PHP

<?php
function aurmap_sign(string $secret, string $method, string $path, string $ts, string $nonce, string $body): string {
    $canonical = implode("\n", [strtoupper($method), $path, $ts, $nonce, hash('sha256', $body)]);
    return hash_hmac('sha256', $canonical, $secret);
}

echo aurmap_sign(
    'sk_test_example_secret_do_not_use', 'PATCH',
    '/v1/places/plc_9q3w7e/menu/state', '1760443200',
    'n0nce_Example_1234567890', '{"as_of":"2026-10-14T18:00:00Z","sold_out":{"items":["kunafa"],"sizes":[],"options":[]}}'
); // ec96466e...b3c8

curl

BODY='{"as_of":"2026-10-14T18:00:00Z","sold_out":{"items":["kunafa"],"sizes":[],"options":[]}}'
PATH_Q='/v1/places/plc_9q3w7e/menu/state'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIG=$(printf '%s\n%s\n%s\n%s\n%s' PATCH "$PATH_Q" "$TS" "$NONCE" "$BH" \
      | openssl dgst -sha256 -hmac "$AURMAP_KEY_SECRET" -hex | sed 's/^.* //')

curl -sS -X PATCH "$AURMAP_HOST$PATH_Q" \
  -H "Content-Type: application/json" \
  -H "X-AurMap-Key-Id: $AURMAP_KEY_ID" \
  -H "X-AurMap-Timestamp: $TS" \
  -H "X-AurMap-Nonce: $NONCE" \
  -H "X-AurMap-Signature: $SIG" \
  -H "Idempotency-Key: state-kunafa-0001" \
  --data-raw "$BODY"

في البدء السريع دالة aurmap جاهزة تفعل هذا كله، ونستعملها في بقية الصفحات.

فرق الوقت

• نقبل الطلب إذا كان X-AurMap-Timestamp ضمن 300 ثانية من وقتنا، قبله أو بعده.
• خارج ذلك نرد 401 TIMESTAMP_SKEW.
• كل رد يحمل ترويسة Date. قارنها بساعتك إذا تكرر الخطأ، وفعل مزامنة الوقت (NTP) على خوادمك.

الرقم العشوائي (nonce)

• كل رقم يقبل مرة واحدة خلال 10 دقائق لكل مفتاح. التكرار يرد 401 NONCE_REUSED.
• الطلب غير الصحيح التوقيع لا يستهلك الرقم، فلا يستطيع أحد أن يحرق أرقامك.
• إذا رددنا 503 UNAVAILABLE فأعد المحاولة برقم جديد.

إعادة المحاولة

إعادة المحاولة طلب جديد: وقت جديد، ورقم عشوائي جديد، وتوقيع جديد. لكنها تحمل نفس Idempotency-Key. بهذا لا ينفذ الأمر مرتين أبدا.

تدوير المفاتيح

1. أنشئ مفتاحا جديدا من لوحة المطورين. المفتاحان يعملان معا.
2. انشر المفتاح الجديد على خوادمك.
3. تابع «آخر استعمال» للمفتاح القديم في اللوحة. حين يتوقف، ألغه.
4. الإلغاء فوري. إذا ظننت أن السر تسرب، ألغه مباشرة ثم أنشئ غيره.

مفاتيح التكرار (Idempotency-Key) وحدود المعدل مرتبطة بحسابك وبيئتك، لا بالمفتاح. التدوير لا يعيد تنفيذ أمر، ولا يغير حدودك.

سر الـ webhook يدور بالطريقة نفسها. أثناء فترة التدوير نرسل توقيعين في الترويسة نفسها، فاقبل أيهما طابق.

أخطاء التوقيع

كلها ترد بـ 401. أكثر سبب شائع لـ SIGNATURE_INVALID: توقيع مسار بلا نص الاستعلام، أو إعادة ترميز JSON بعد التوقيع.