الوقت والصيغ

صيغة JSON والنصوص

• نصوص الطلبات والاستجابات بصيغة JSON بترميز UTF-8، مع الترويسة Content-Type: application/json. ويستخدم رفع الملفات الصيغة multipart/form-data.
• أسماء الحقول وقيم التعداد بصيغة snake_case: next_retry_at، وindex_failed.
• رسائل الأخطاء ونصوص واجهة API بالإنجليزية. أما النصوص التي تكتبها أنت، مثل عناوين البطاقات، فتُعاد كما كتبتها، بأي لغة.

الأوقات

كل وقت هو طابع زمني بصيغة RFC 3339 بالتوقيت العالمي المنسق (UTC):

{"created_at": "2026-10-24T10:00:00Z"}

• تستخدم الحقول الأحدث الصيغة القصيرة مع Z، كما في المثال أعلاه.
• بعض الحقول التي وُجدت من قبل تستخدم الصيغة 2026-10-24T10:00:00.123456+00:00، مع ما يصل إلى ست خانات لأجزاء الثانية. وهي اللحظة نفسها بتوقيت UTC. حلّل الصيغتين بمحلل RFC 3339 قياسي، ولا تقارن الطوابع الزمنية بوصفها سلاسل نصية.
• كل حقل ينتهي اسمه باللاحقة _at هو طابع زمني.

يجب أن تتضمن الأوقات التي ترسلها إزاحة المنطقة الزمنية: إما Z وإما إزاحة رقمية مثل +02:00. الوقت بلا إزاحة ملتبس، ويعيد الحالة 422 مع الرمز validation.failed. يحوّل Sursa كل وقت يستلمه إلى UTC.

const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString(); // "2026-10-23T10:00:00.000Z"

في سلسلة الاستعلام يجب كتابة + على شكل %2B، وإلا قُرئت مسافة. طبّق ترميز URL على قيم الوقت، أو استخدم Z.

التواريخ والمدد والأعداد

المبالغ المالية

المبالغ في الاستجابات المالية سلاسل نصية عشرية، مثل "1250.00"، وليست أبدًا أعدادًا بفاصلة عائمة، كي لا تضيع الدقة. والعملة حقل منفصل برمز وفق ISO 4217، مثل "EUR". حلّل المبالغ بنوع عشري في لغتك البرمجية.

المعرّفات

المعرّفات سلاسل نصية أو أعداد صحيحة بحسب الكائن. انظر معرّفات الكائنات.

التعدادات

الحقول ذات القائمة الثابتة من القيم، مثل الحالة، سلاسل نصية. وأي تعداد في الاستجابة قد تُضاف إليه قيم جديدة في إصدار لاحق: تعامل مع القيمة التي لا تعرفها على أنها «أخرى». انظر الإصدارات والتوافق.

القيمة null والحقول الغائبة

• القيمة null تعني «لا قيمة»: البطاقة التي لا مسؤول لها فيها "owner_id": null.
• قد يغيب حقل من الاستجابة حين لا ينطبق على هذا الكائن أو هذا الطلب. ويحدد مرجع API الحقول الموجودة دائمًا.
• في الطلب PATCH يحتفظ الحقل الذي لا ترسله بقيمته. أرسل null لتفريغ الحقل إذا ذكر المرجع أن القيمة null مسموح بها فيه.