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

شحن عداد

POST/v1/wallets/{walletId}/meter-charges

اشحن العداد بمعرّف عملية تحفظه قبل الإرسال. يعني الردّ 202 أن الشحن قُبل أو أن التحقق من نتيجته ما زال جاريًا.

الصلاحيةmeter_charges:create

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

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

حدود الموظفين التي يُحتسب ضمنهاكل الاستدعاءات، المشتريات (حدّ الطلبات)

حزمة SDK لـ ‎.NETanis.MeterCharges.CreateAsync(walletId, operationId, request)

كل ردّ معالجة بالحالة 202 يحتوي فقط operationId وoperationType وstatus: "processing"؛ وتكون operationType هي meterCharge. تستخدم القراءة الكاملة الحالة 200.
عدم ظهور العملية في القراءة لا يثبت غيابها. أعد المحتوى المحفوظ نفسه بمعرّف العملية نفسه وتوقيع جديد. يبقى الردّ على العملية المكررة 202 أثناء تأخر ظهورها. لا تُغلق العملية بالرمز idempotency_conflict والحالة 409 إلا إذا كشفت هذه المحاولة تكرار العملية بعد مرور 60 ثانية أو أكثر منذ قبولها الأول، ثم لم تجدها قراءة لاحقة خاصة بتطبيقك. غياب القراءة أو انتهاء المهلة وحده لا يثبت التعارض. ولا يثبت هذا الرمز أن شيئًا لم يُخصم: فقد يكون الطلب الأول قُبل بالفعل، فاقرأ العملية قبل أي محاولة جديدة.
تُحتسب عملية الشراء ضمن حدّ orders الحالي وسقف الإنفاق اليومي نفسه للتطبيق مع طلبات البطاقات والمشتريات الأخرى.

المعاملات

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

الاستدعاء

موقَّع بمفتاحك، مع رقم استخدام لمرة واحدة (nonce) وبصمة للمحتوى ومعرّف العملية في Idempotency-Key.

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

المحتوى: CreateMeterChargeRequest، بصيغة JSON.

الحقل	النوع	ملاحظات
`packageId`إلزامي	UUID	معرّف الباقة المختارة من قائمة الباقات.
`meterNumber`إلزامي	string	رقم العداد كنص؛ احتفظ بأصفاره الأولى.
`expectedTotal`إلزامي	any	الإجمالي الذي أكّدته من الباقة أو عرض السعر، بصيغة Money وعملة LYD.
`externalReference`	string	مرجعك الخاص؛ يظهر إن أرسلته.

الردود

الحالة	المعنى	المحتوى
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
الحساب غير مخوَّل	`binding_not_authorized`	403
الحساب غير فعّال	`account_inactive`	403
المحفظة غير ممنوحة	`wallet_not_granted`	404
غير موجود	`resource_not_found`	404
العملة غير مدعومة	`currency_not_supported`	422
المحفظة معطّلة	`wallet_disabled`	409
انتهت صلاحية المحفظة	`wallet_expired`	409
يلزم اشتراك أعمال	`business_subscription_required`	409
اكتُشف تكرار	`replay_detected`	409
معرّف العملية مستخدم من قبل	`idempotency_conflict`	409
تغيّر السعر	`price_changed`	409
الرصيد غير كافٍ	`insufficient_balance`	409
بُلغ سقف الإنفاق	`spending_limit_exceeded`	429
العداد مرفوض	`meter_rejected`	422
الباقة غير متاحة	`package_unavailable`	409

الأنواع

CreateMeterChargeRequest

الحقل	النوع	ملاحظات
`packageId`إلزامي	UUID	معرّف الباقة المختارة من قائمة الباقات.
`meterNumber`إلزامي	string	رقم العداد كنص؛ احتفظ بأصفاره الأولى.
`expectedTotal`إلزامي	any	الإجمالي الذي أكّدته من الباقة أو عرض السعر، بصيغة Money وعملة LYD.
`externalReference`	string	مرجعك الخاص؛ يظهر إن أرسلته.

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`