API Reference — Events Ingestion
بنية الحدث
Required Fields
Required Fields
string
مطلوب
معرّف فريد للحدث، يُستخدم لاكتشاف الأحداث المكررة عند إعادة المحاولة. اشتقه من الإجراء، على سبيل المثال: معرّف العميل + الإجراء + الطابع الزمني، بحيث يحتفظ الحدث المُعادّت محاولته بالمعرّف نفسه. إن إنشاء UUID عشوائي جديد في كل إعادة محاولة يتيح احتساب الحدث نفسه مرتين.
string
مطلوب
معرّف عميل Dodo Payments. يجب أن يكون معرّف عميل موجودًا وصالحًا.
string
مطلوب
نوع الحدث الذي يطابق اسم الحدث في meter لديك (مع مراعاة حالة الأحرف). أمثلة:
api.call، image.generated.Optional Fields
Optional Fields
string
طابع زمني بتنسيق ISO 8601 (UTC). يُستخدم وقت الخادم الحالي تلقائيًا إذا لم تُحدده. أدرجه لضمان دقة الفوترة مع الأحداث المؤجلة أو المجمّعة. يتم رفض الطوابع الزمنية الأقدم من ساعة واحدة أو التي تتجاوز 5 دقائق في المستقبل.
object
خصائص إضافية للتجميع والتصفية. بحد أقصى 50 مفتاحًا؛ ويمكن أن يصل طول كل مفتاح إلى 100 حرف، وكل قيمة إلى 500 حرف.
- القيم الرقمية:
bytes،tokens،duration_ms - عوامل التصفية:
endpoint،method،quality
إرسال الأحداث
مخططات إدخال الأحداث
أنماط أحداث جاهزة لحالات الاستخدام الشائعة. ابدأ بمخطط مُثبت بدلاً من البناء من الصفر.LLM Blueprint
API Gateway Blueprint
Object Storage Blueprint
Stream Blueprint
Time Range Blueprint
View All Blueprints
أفضل الممارسات
Use Unique Event IDs
Use Unique Event IDs
استخدم معرّفات حتمية لمنع التكرارات:
${customerId}_${action}_${timestamp}.Implement Retries
Implement Retries
أعد المحاولة عند حدوث أخطاء 5xx وأخطاء
429 مع استخدام التأخير الأُسّي. لا تُعد المحاولة عند حدوث أخطاء 4xx الأخرى.Include Timestamps
Include Timestamps
احذف الطوابع الزمنية للأحداث في الوقت الفعلي. أدرجها للأحداث المؤجلة أو المجمّعة لضمان الدقة.
Monitor Delivery
Monitor Delivery
تتبع معدلات النجاح وضع الأحداث الفاشلة في قائمة انتظار لإعادة المحاولة.
استكشاف الأخطاء وإصلاحها
Events not appearing
Events not appearing
- يجب أن يطابق اسم الحدث meter تمامًا (مع مراعاة حالة الأحرف)
- يجب أن يكون معرّف العميل موجودًا في حسابك
- تحقّق من أن فلاتر meter لا تستبعد الأحداث
- تحقّق من حداثة الطوابع الزمنية
Authentication errors (401)
Authentication errors (401)
تحقّق من صحة API key واستخدم التنسيق:
Bearer YOUR_API_KEY.Validation errors (400)
Validation errors (400)
تأكّد من وجود جميع الحقول المطلوبة:
event_id، customer_id، event_name.Metadata not aggregating
Metadata not aggregating
- يجب أن تطابق مفاتيح Metadata قيمة “Over Property” في meter تمامًا
- استخدم أرقامًا، وليس سلاسل نصية:
tokens: 150وليسtokens: "150"