اصطلاحات واجهة البرمجة

تشترك واجهات HyoNova البرمجية في مجموعة صغيرة من الاصطلاحات للأخطاء والتقسيم إلى صفحات وإعادة المحاولة والحدود. وتتبعها واجهة Mail البرمجية اليوم. وواجهة برمجة عامة شاملة مخططة، وستتبع الاصطلاحات نفسها.

الطلبات والاستجابات#

• تستخدم الطلبات والاستجابات صيغة JSON (Content-Type: application/json).
• تحمل كل استجابة الترويسة X-Request-Id. أرفقها عند التواصل مع HyoNova بشأن مشكلة.
• لا تُخزَّن استجابات طلبات الواجهة مؤقتاً (Cache-Control: no-store).

الأخطاء#

لكل خطأ الشكل نفسه، أياً كانت نقطة النهاية:

{
  "error": {
    "code": "SENDER_NOT_VERIFIED",
    "message": "Add and verify a sender before sending."
  }
}

• code نص ثابت تقرؤه الآلة. اعتمد عليه لا على نص الرسالة.
• message شرح مقروء للبشر، وقد يتغير، ولا يُقصد تحليله آلياً.

تعيد أخطاء الخادم غير المتوقعة رسالة عامة (INTERNAL_ERROR). وتُسجَّل التفاصيل لدى HyoNova تحت معرّف الطلب، ولا تُعاد في الاستجابة أبداً.

رموز حالة HTTP#

لا تظهر أبداً السجلات التي تخص شركة أخرى، أياً كان الطلب أو المفتاح.

التقسيم إلى صفحات#

تستخدم نقاط النهاية التي تعيد قوائم — GET /mail/v1/messages وGET /mail/v1/contacts — مؤشراً معتماً.

• مرّر limit لاختيار حجم الصفحة. القيمة الافتراضية 25 والحد الأقصى 100.
• تحتوي الاستجابة على items وnextCursor. وعندما تكون nextCursor مساوية لـ null فلا صفحات أخرى.
• للحصول على الصفحة التالية، أعِد قيمة nextCursor في المعامل cursor. لا تبنِ المؤشرات بنفسك ولا تغيّرها.

{
  "items": [{ "id": "…" }, { "id": "…" }],
  "nextCursor": "b3f1…"
}

منع التكرار#

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

• يُحفظ أول رد تحت المفتاح لمدة 24 ساعة لمفتاح API ذاته. وإعادة المحاولة بالمفتاح نفسه والمحتوى نفسه تعيد الرد نفسه مع Idempotent-Replayed: true.
• المفتاح نفسه مع محتوى مختلف يردّ بالرمز 409 IDEMPOTENCY_CONFLICT.
• في POST /mail/v1/send يسمّي المفتاح الرسالةَ أيضاً على مستوى شركتك كلها: أي استدعاء لاحق بالمفتاح نفسه يعيد الرسالة الأصلية مع "replayed": true ولا يرسل شيئاً جديداً. استخدم مفتاحاً يسمّي الرسالة، مثل order-1001-confirmation، حتى 160 حرفاً.

حدود المعدل#

تقبل واجهة Mail حتى 600 طلب في الدقيقة لكل مفتاح API (و300 في الدقيقة لـ POST /mail/v1/conversions). تحمل كل استجابة x-ratelimit-limit وx-ratelimit-remaining وx-ratelimit-reset. وعند تجاوز الحد تتلقى الحالة 429 مع الترويسة retry-after بالثواني. اكتشفها من رمز الحالة، وانتظر، واستخدم فترات متزايدة بين المحاولات.

مثال: التعامل مع الأخطاء#

async function sendWithRetry(body: unknown, idempotencyKey: string) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch('https://api.hyonova.com/mail/v1/send', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.HYO_MAIL_API_KEY}`, // YOUR_API_KEY
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey, // the same key on every retry
      },
      body: JSON.stringify(body),
    });
    if (response.status === 202) return response.json();
    if (response.status === 429 || response.status >= 500) {
      const wait = Number(response.headers.get('retry-after')) || 2 ** attempt;
      await new Promise((r) => setTimeout(r, wait * 1000)); // back off, then retry
      continue;
    }
    const { error } = await response.json();
    const requestId = response.headers.get('X-Request-Id');
    throw new Error(`${error.code} (${requestId}): ${error.message}`); // do not retry
  }
  throw new Error('Gave up after 5 attempts');
}

curl -i -X POST "https://api.hyonova.com/mail/v1/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-confirmation" \
  -d '{"to": "name@example.com", "subject": "Your order", "html": "<p>Thank you.</p>"}'
# -i prints the status line, X-Request-Id and the x-ratelimit-* headers

الحالة#