الانتقال إلى المحتوى الرئيسي
الأحداث هي أساس الفوترة المعتمدة على الاستخدام. أرسل الأحداث عند حدوث إجراءات قابلة للفوترة، وتجمع العدادات هذه الأحداث في رسوم.

مرجع API - استيعاب الأحداث

وثائق API كاملة مع أمثلة وأكواد استجابة.

هيكل الحدث

event_id
string
required
معرف فريد. استخدم UUIDs أو اجمع بين معرف العميل + الطابع الزمني + الإجراء.
customer_id
string
required
معرف عميل Dodo Payments. يجب أن يكون عميلًا موجودًا صالحًا.
event_name
string
required
نوع الحدث الذي يتطابق مع اسم حدث العداد الخاص بك (حساس لحالة الأحرف). أمثلة: api.call, image.generated
timestamp
string
طابع زمني ISO 8601. الافتراضي هو وقت الخادم إذا تم إغفاله. قم بتضمينه لفوترة دقيقة مع الأحداث المتأخرة/الدفعات.
metadata
object
خصائص إضافية للتجميع والتصفية:
  • القيم الرقمية: bytes, tokens, duration_ms
  • الفلاتر: endpoint, method, quality
metadata: {
  endpoint: "/v1/orders",
  method: "POST",
  tokens: 1024
}

إرسال الأحداث

await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [{
      event_id: "api_call_1234",
      customer_id: "cus_abc123",
      event_name: "api.call",
      metadata: { endpoint: "/v1/orders" }
    }]
  })
});
اجمع حتى 100 حدث لكل طلب لتحسين الأداء.

مخططات الاستيعاب

أنماط الأحداث الجاهزة للحالات الشائعة. ابدأ بمخطط مثبت بدلاً من البناء من الصفر.

أفضل الممارسات

استخدم معرفات حتمية لمنع التكرار: ${customerId}_${action}_${timestamp}
أعد المحاولة عند حدوث أخطاء 5xx مع زيادة زمن الانتظار. لا تعيد المحاولة عند حدوث أخطاء 4xx.
تجاهل للأحداث في الوقت الحقيقي. قم بتضمينها للأحداث المتأخرة/الدفعات للدقة.
تتبع معدلات النجاح وقم بتجميع الأحداث الفاشلة لإعادة المحاولة.

استكشاف الأخطاء وإصلاحها

  • يجب أن يتطابق اسم الحدث تمامًا مع العداد (حساس لحالة الأحرف)
  • يجب أن يكون معرف العميل موجودًا
  • تحقق من أن فلاتر العداد لا تستبعد الأحداث
  • تحقق من أن الطوابع الزمنية حديثة
تحقق من أن مفتاح API صحيح واستخدم التنسيق: Bearer YOUR_API_KEY
تأكد من وجود جميع الحقول المطلوبة: event_id, customer_id, event_name
  • يجب أن تتطابق مفاتيح البيانات الوصفية مع “الخاصية الزائدة” للعداد تمامًا
  • استخدم الأرقام، وليس السلاسل: tokens: 150 وليس tokens: "150"

الخطوات التالية