تنسيق الاستجابة

نوع المحتوى

تُرجع كل نقطة نهاية application/json بترميز UTF-8، بصرف النظر عن ترويسة Accept. أرسل Content-Type: application/json في الطلبات التي تحمل متنًا.

شكلان، عن قصد

تغلّف نقاط نهاية المجموعات حمولتها في data؛ أما نقاط نهاية الكائن المفرد فتُرجع حقولها في المستوى الأعلى. هذا ليس مصادفة، ويستحق أن تعرفه قبل كتابة أي محلّل:

{ "data": [ { "id": 47, "slug": "wavalid-realtime" } ] }

{ "balance": "5.230000" }

GET /v1/products هي حالة المجموعة؛ وGET /v1/balance وGET /v1/api-key هما حالة الكائن المفرد. وتُرجع نقاط نهاية الوقت الفعلي كائن الطلب نفسه — request_id وstatus وresults — في المستوى الأعلى.

الأخطاء

تستخدم الأخطاء كائنًا ثابتًا بحقلين:

{
  "code": "invalid_realtime_request",
  "message": "A realtime request cannot mix phone and email products."
}

الحقل	المعنى
code	معرّف ثابت قابل للقراءة آليًا. تفرّع بناءً عليه.
message	تفصيل مقروء للبشر. قد تتغيّر الصياغة؛ لا تُحلّله.

قيم code موثّقة لكل نقطة نهاية، مع حالة HTTP التي تصل معها — راجع رموز الأخطاء للقائمة الكاملة.

المبالغ

تظهر المبالغ في شكلين، والفرق بينهما مهم عند التحليل:

الموضع	النوع	مثال
balance في GET /v1/balance	string	"5.230000"
total_charged وcharged_amount وrefunded_amount في استجابات الوقت الفعلي	number	0.004000

يُصدر الرصيد كسلسلة عشرية ثابتة الدقة حتى لا يرى أي عميل أثرًا للتقريب على قيمة على وشك مقارنتها بحد معيّن. أما مبالغ الوقت الفعلي فهي أرقام مقرّبة إلى ست منازل عشرية — تعامل معها كتقريبية بعد المنزلة السادسة.

المبالغ بعملة الدولار الأمريكي (USD). ولا يُدرج رمز العملة في الحمولة.

الطوابع الزمنية

الطوابع الزمنية بمعيار ISO 8601 بتوقيت UTC، مع لاحقة Z:

2026-09-13T10:00:00Z

يتبع هذا checked_at في نتيجة الوقت الفعلي، والطوابع الزمنية للمهمة في الاستجابات الجماعية.

حالة HTTP ليست النتيجة

يوجد نمطان وكلاهما مقصود:

• الوقت الفعلي: حالة HTTP 200 تعني أن الطلب نُفّذ، لا أن كل منتج أجاب. اقرأ status وbilling_status لكل مدخل.
• الجماعي: يُرجع الإرسال قبولًا للمهمة على نمط 202؛ ويستمر العمل بشكل غير متزامن، ولا توجد النتيجة إلا عندما تصل المهمة إلى حالة نهائية.

القاعدة في الحالتين: يخبرك رمز الحالة بما إذا كان عليك إعادة المحاولة، ويخبرك المتن بما حدث.

التالي

• رموز الأخطاء — كل code، لكل نقطة نهاية
• حدود المعدّل — الترويسات التي تعود مع 429