مرجع API · شحن العدادات

قراءة عملية شحن

GET/v1/meter-charges/{operationId}

تابع الشحن، واقرأ جميع رموزه عند النجاح، أو سبب الفشل وحالة إعادة المال.

الصلاحيةmeter_charges:read

المصادقةقراءة موقَّعة

ردّ أنيسموقَّع

حدود الموظفين التي يُحتسب ضمنهاكل الاستدعاءات

حزمة SDK لـ ‎.NETanis.MeterCharges.GetAsync(operationId)

كل ردّ معالجة بالحالة 202 يحتوي فقط operationId وoperationType وstatus: "processing"؛ وتكون operationType هي meterCharge. تستخدم القراءة الكاملة الحالة 200.
إذا رُفض الإنشاء وسُجّل رفضًا فلا عملية شحن نشأت: تعيد القراءة هذا الرفض المسجّل (409 أو 422) مع Idempotency-Replayed: true، ولم يُخصم شيء. وعند القراءة يعني idempotency_conflict أنه لا توجد عملية شحن عداد لتطبيقك بهذا المعرّف.

المعاملات

الاسم	الموضع	النوع	ملاحظات
`operationId`إلزامي	`path`	UUID	معرّف UUID بأحرف صغيرة مع الشرطات.

الاستدعاء

موقَّعة بمفتاحك. بلا محتوى وبلا رقم استخدام لمرة واحدة (nonce).

الترويسات: Signature-Input، Signature، X-Anis-Date، Accept-Language (اختياري). تضبطها حزم SDK كلها نيابةً عنك.

المحتوى: لا يوجد.

الردود

الحالة	المعنى	المحتوى
200	نجاح.	MeterCharge
202	قُبل — لا نتيجة بعد.	MeterChargeAccepted
400	مرفوض: الاستدعاء الموقّع غير سليم البنية.	مشكلة
401	مرفوض: لم تتم المصادقة.	مشكلة
403	مرفوض: غير مسموح.	مشكلة
404	مرفوض: غير موجود، أو ليس لك.	مشكلة
409	مرفوض: يتعارض مع الحالة الحالية.	مشكلة
422	مرفوض: الاستدعاء يخالف قاعدة.	مشكلة
429	مرفوض: بلغتَ حدًا.	مشكلة
503	لا قرار: خدمة مطلوبة غير متاحة.	مشكلة

كل ردّ على هذا الاستدعاء موقَّع من أنيس — النجاح وكل رفض. اشترط وجود التوقيع وتحقّق منه قبل أن تتصرف بناءً على الردّ؛ والردّ بلا توقيع فشل، لا يُعدّ ردًّا (كيف).

حالات الرفض

كل رفض لهذا الاستدعاء مشكلةٌ موقَّعة. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.

الخطأ	الرمز	الحالة
بيانات اعتماد غير صالحة	`invalid_credentials`	401
استدعاء موقّع غير سليم البنية	`malformed_signed_request`	400
صلاحية غير كافية	`insufficient_scope`	403
عنوان المصدر غير مسموح	`source_ip_not_allowed`	403
تجاوزت حدّ الاستدعاءات	`rate_limited`	429
فشل التحقق	`validation_failed`	422
الخدمة غير متاحة	`dependency_unavailable`	503
انتهت مهلة الاستدعاء	`request_timeout`	504
خطأ داخلي	`internal_error`	500
غير موجود	`resource_not_found`	404
الرصيد غير كافٍ	`insufficient_balance`	409
تغيّر السعر	`price_changed`	409
الباقة غير متاحة	`package_unavailable`	409
العداد مرفوض	`meter_rejected`	422
معرّف العملية مستخدم من قبل	`idempotency_conflict`	409

الأنواع

MeterCharge

الحقل	النوع	ملاحظات
`operationId`موجود دائمًا	UUID	قيمة UUID نفسها المرسلة في `Idempotency-Key` لهذا الشراء.
`status`موجود دائمًا	MeterChargeStatus	تكون `processing` أو `succeeded` أو `failed`. وتحتاج قراءة الفشل إلى `refund.status` لتوضيح مصير المال.
`walletId`موجود دائمًا	string	المحفظة المستخدمة في هذا الشراء.
`meterNumber`موجود دائمًا	string	رقم العداد كنص؛ احتفظ بأصفاره الأولى.
`package`موجود دائمًا	MeterChargePackage	الباقة المسجّلة لهذا الشحن.
`total`موجود دائمًا	Money	إجمالي تكلفة المحفظة المثبّت في كل حالة بصيغة Money وعملة LYD.
`personalPrice`موجود دائمًا	Money	سعر التجزئة المثبّت في كل حالة؛ لا تستبدل به إجمالي الدفع.
`externalReference`	string	مرجعك الخاص؛ يظهر إن أرسلته.
`createdAt`موجود دائمًا	string (date-time)	وقت تسجيل الشحن بتوقيت UTC.
`completedAt`	string (date-time)	وقت نجاح الشحن؛ ويُحذف في حالتي المعالجة والفشل.
`receipt`	MeterReceipt	يظهر بعد نجاح الشحن؛ ويضم جميع الرموز.
`failure`	MeterFailure	سبب فشل الشحن ورسالته باللغتين؛ يظهر عند الفشل.
`refund`	MeterRefund	يوضح عند فشل الشحن هل عاد المال أو لم يُخصم أو ما زال قيد الإعادة.

MeterChargeStatus

MeterChargePackage

الحقل	النوع	ملاحظات
`id`موجود دائمًا	UUID	معرّف باقة شحن العداد.
`name`موجود دائمًا	string	اسم واحد محفوظ للباقة، وليس كائن نص بلغتين.
`gecolPackageName`موجود دائمًا	string	اسم الباقة لدى شركة الكهرباء.

Money

الحقل	النوع	ملاحظات
`amount`موجود دائمًا	string	نص عشري، وليس عدد JSON. قد يكون رصيد المحفظة سالبًا عند استخدام الدين المسموح. تتبع الأسعار والإجماليات قواعد المبلغ لكل مسار.
`currency`موجود دائمًا	string	رمز عملة من ثلاثة أحرف كبيرة، مثل `LYD`. اقرأ عملة المحفظة من `balance.currency`.
`asOf`	string (date-time)	وقت قراءة هذا السعر أو الرصيد.

MeterReceipt

الحقل	النوع	ملاحظات
`receiptNumber`	string	رقم الإيصال الوارد من شركة الكهرباء.
`creditedAmount`	string	نص المبلغ المضاف كما ورد من شركة الكهرباء دون تغيير؛ وليس إجمالي المحفظة.
`tokens`موجود دائمًا	list of MeterToken	كل رموز الشركة بترتيبها، بما فيها تغيير المفتاح قبل إضافة الرصيد.
`taxes`موجود دائمًا	list of MeterTax	بنود الضرائب في إيصال الشركة.

MeterToken

الحقل	النوع	ملاحظات
`sequence`موجود دائمًا	integer	ترتيب الرمز لدى الشركة؛ احتفظ بالفجوات دون إعادة الترقيم.
`label`موجود دائمًا	string	تسمية الرمز الواردة من الشركة.
`code`موجود دائمًا	string	نص الرمز كاملًا، بما فيه المسافات والأصفار الأولى.
`description`	string	وصف الرمز للعرض إن ورد.

MeterTax

الحقل	النوع	ملاحظات
`description`موجود دائمًا	string	وصف الضريبة الأصلي من شركة الكهرباء بالعربية، دون تغيير.
`amount`موجود دائمًا	string	نص مبلغ الشركة الأصلي؛ دون تحويل إلى مقياس Money.

MeterFailure

الحقل	النوع	ملاحظات
`code`موجود دائمًا	string	قيمة لفشل قراءة الشحن، وليست رمز مشكلة HTTP. القيم: `meter_number_invalid`, `meter_not_whitelisted`, `meter_not_linked`, `meter_removed`, `meter_inactive`, `meter_account_blocked`, `meter_data_incomplete`, `meter_debt_exceeds_package`, `package_unavailable`, `package_limit_reached`, `token_not_written`, `insufficient_balance`, `gecol_unavailable`, `charge_failed`
`message`	LocalizedText	رسالتان بالعربية والإنجليزية تصفان نتيجة الشحن.

LocalizedText

الحقل	النوع	ملاحظات
`ar`	string	النص العربي؛ يُحذف حين يكون فارغًا.
`en`	string	النص الإنجليزي؛ يُحذف حين يكون فارغًا.

MeterRefund

الحقل	النوع	ملاحظات
`status`موجود دائمًا	MeterRefundStatus	تعني `refunded` عودة المال، و`notCharged` عدم خصمه، و`pending` أنه لم يعد بعد.
`amount`	any	مبلغ الإعادة بصيغة Money إن ورد؛ لا تستنتج التسوية من المبلغ وحده.

MeterRefundStatus

MeterChargeAccepted

الحقل	النوع	ملاحظات
`operationId`موجود دائمًا	UUID	قيمة UUID نفسها المرسلة في `Idempotency-Key` لهذا الشراء.
`operationType`موجود دائمًا	string	تكون دائمًا `meterCharge`. القيم: `meterCharge`
`status`موجود دائمًا	string	تكون دائمًا `processing`؛ النتيجة لم تصبح نهائية. القيم: `processing`