توثيق API

المصادقة

تتطلب جميع طلبات API المصادقة بمفتاح API. احصل على مفتاحك من إعدادات الحساب.

لا تشارك مفتاح API أبدًا. استخدم OAuth 2.0 للتطبيقات العامة.

مثال cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.ureticy.com/v1/stations

مثال JavaScript / Fetch

const response = await fetch('https://api.ureticy.com/v1/stations', { headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } });

نقاط نهاية API

عنوان URL الأساسي

https://api.ureticy.com/v1

أنواع المحتوى

application/json
application/x-www-form-urlencoded

تحديد معدل الطلبات

طلبات API محدودة بـ 100 طلب في الدقيقة. ستتلقى HTTP 429 عند تجاوز هذا الحد.

إدارة المحطات

عرض قائمة المحطات

GET/stations

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي: 1)
`limit`	integer	عدد السجلات في الصفحة (الحد الأقصى: 100)
`status`	string	active \| inactive \| error

استجابة ناجحة

{"status":"success","data":{"stations":[{"id":"station_123","name":"İstanbul-01","status":"active","connector_count":2}],"pagination":{"page":1,"total":48}}}

ابدأ الشحن

POST/stations/{id}/start

المعامل	مطلوب	الوصف
`connector_id`	نعم	معرّف الموصل
`user_id`	نعم	معرّف المستخدم

المعاملات

GET/transactions

المعامل	مثال
`station_id`	station_123
`date_from`	2026-01-01
`date_to`	2026-04-18

Webhooks

احصل على إشعارات فورية بالأحداث المهمة.

الأحداث المدعومة

station.connected
station.disconnected
transaction.started
transaction.completed
error.critical

مثال على الحمولة

{ "event": "transaction.completed", "timestamp": "2026-04-18T10:30:00Z", "data": { "transaction_id": "txn_789", "station_id": "station_123", "energy_consumed": 15.5, "duration_minutes": 45, "amount": 82.50 } }

رموز الأخطاء

الرمز	الوصف
`400`	طلب غير صالح — معاملات غير صحيحة
`401`	غير مصرّح — مفتاح API مطلوب
`403`	محظور — صلاحيات غير كافية
`404`	غير موجود — المورد غير متوفر
`429`	طلبات كثيرة جدًا — تم تجاوز حد المعدل
`500`	خطأ داخلي في الخادم

مثال على استجابة خطأ

HTTP 401 Unauthorized

{"status":"error","error":{"code":"INVALID_API_KEY","message":"The provided API key is invalid or expired.","timestamp":"2026-04-18T10:30:00Z"}}