API وwebhooks لبرامج الورش
هل تطوّر برامج تخطيط أو ورش أو وكلاء؟ بمفتاح من الورشة يقرأ نظامك السيارات ورموز الأعطال والتقارير والرحلات، ويتلقى إشارة عند حدوث شيء. للقراءة فقط، ودائمًا بإذن مالك السيارة.
المرجع التقني (نقاط النهاية، الحقول، الأمثلة) بالإنجليزية، مثل الـ API نفسه.
البدء
- لدى الورشة Car-Z Garage. يفتح المالك أو مدير الورشة تبويب التكاملات.
- ينشئ مفتاحًا باسم ويحدد ما يمكنه قراءته، وينسخه مرة واحدة في برنامجك.
- يرسل برنامجك المفتاح مع كل طلب. للإشارات، تُدخل الورشة هناك أيضًا عنوان الـ webhook الخاص بك.
المصادقة
أرسل المفتاح في ترويسة Authorization كـ Bearer token، عبر HTTPS فقط. لا تضعه في رابط أبدًا. كل مفتاح يخص ورشة واحدة؛ والمفتاح الملغى يتوقف فورًا. نحفظ بصمة المفتاح فقط، لذا لا يمكن عرض مفتاح مفقود مرة أخرى: أنشئ مفتاحًا جديدًا.
Authorization: Bearer cz_…Test the key
curl -s https://car-z.com/api/v1 \
-H "Authorization: Bearer $CARZ_API_KEY"List cars (first page of 100)
curl -s "https://car-z.com/api/v1/cars?limit=100" \
-H "Authorization: Bearer $CARZ_API_KEY"Fault codes of one car in a period, descriptions in Dutch
curl -s "https://car-z.com/api/v1/cars/$CAR_ID/codes?from=2026-10-01&to=2026-10-31&lang=nl" \
-H "Authorization: Bearer $CARZ_API_KEY"Next page
curl -s "https://car-z.com/api/v1/cars/$CAR_ID/trips?cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $CARZ_API_KEY"نقاط النهاية
كل نقاط النهاية للقراءة فقط (GET)، مرقّمة الإصدار في المسار، وتجيب بـ JSON بأسماء حقول إنجليزية ثابتة، وتواريخ ISO 8601 بتوقيت UTC، ووحدات مترية في اسم الحقل (distance_km، avg_speed_kmh).
| الطريقة | المسار | النطاق | الوصف |
|---|---|---|---|
| GET | /api/v1 | — | The key itself: workspace, scopes, rate limit. Use it to test a key. |
| GET | /api/v1/cars | cars | Cars of the garage, plus customers' cars with running access and download permission. Sorted by id. |
| GET | /api/v1/cars/{car_id} | cars | One car. |
| GET | /api/v1/cars/{car_id}/codes | codes | Fault code episodes (first seen until cleared), newest first. |
| GET | /api/v1/cars/{car_id}/reports | reports | Inspection reports made in the garage's own workspace (a customer's car: empty list). |
| GET | /api/v1/cars/{car_id}/trips | trips | Trip summaries, newest first. |
المرشّحات والصفحات
تأتي القوائم على صفحات. اطلب الصفحة التالية بقيمة next_cursor من الإجابة، حتى تصبح null. المؤشر لا يتخطى صفًا ولا يكرره أبدًا، حتى عند وصول صفوف جديدة.
| المعامل | الوصف |
|---|---|
| limit | Rows per page, 1–200. Default 50. |
| cursor | The next_cursor of the previous page. Opaque; pass it back unchanged. |
| from | YYYY-MM-DD, inclusive (UTC). Codes: seen on or after this day. Trips and reports: started/created on or after. |
| to | YYYY-MM-DD, inclusive (the whole day, UTC). Codes: first seen before the end of this day. |
| lang | codes only: language of the description (en, nl, de, fr, es). Default en. |
إجابة قائمة
{
"data": [
{
"id": "0b9c7d0e-5a3f-4d8e-9c1a-2f6b8e4d7a10",
"code": "P0420",
"description": "Catalyst system efficiency below threshold (bank 1)",
"state": "stored",
"first_seen_at": "2026-10-02T07:41:12.000Z",
"last_seen_at": "2026-10-09T16:05:40.000Z",
"cleared_at": null,
"days_seen": 4
}
],
"next_cursor": "eyJ0IjoiMjAyNi0xMC0wMlQwNzo0MToxMi4wMDBaIiwiaSI6IjBiOWM3ZDBlLi4uIn0"
}سيارة عميل: بلا VIN
{
"data": {
"id": "6f1e2d3c-4b5a-4978-8a6b-5c4d3e2f1a0b",
"access": "shared",
"name": "Golf",
"make": "Volkswagen",
"model": "Golf",
"year": 2019,
"plate": "AB-123-C",
"vin": null,
"access_expires_at": "2026-12-01T09:00:00.000Z",
"created_at": "2026-05-04T10:11:12.000Z",
"updated_at": "2026-11-10T08:00:00.000Z"
}
}الأخطاء
للخطأ حالة HTTP ورمز ثابت: {"error": {"code": "…", "message": "…"}}. اعتمد على الرمز، لا على الرسالة.
| الحالة | الرمز | الوصف |
|---|---|---|
| 400 | invalid_parameter | A query parameter is not valid (limit, cursor, from, to). |
| 401 | invalid_key | No key, an unknown key or a revoked key. |
| 403 | plan_required | The garage has no active paid plan. |
| 403 | insufficient_scope | The key does not have the scope of this endpoint. |
| 404 | not_found | Unknown car, or no access to it. The two are deliberately the same. |
| 429 | rate_limited | More than 120 requests in this minute. See Retry-After. |
| 503 | unavailable | Temporarily unavailable. Try again later. |
حدود المعدّل
120 طلبًا في الدقيقة كحد أقصى لكل مفتاح، لجميع خوادمنا معًا. كل إجابة تحوي X-RateLimit-Limit وX-RateLimit-Remaining؛ وفوق الحد تحصل على 429 مع Retry-After بالثواني. اجلب التغييرات بفترة (from، to) بدلًا من جلب كل شيء في كل مرة.
Webhooks
تُدخل الورشة عنوان https واحدًا وتختار الأحداث، وما إذا كانت تصل واحدًا تلو الآخر أو مجمّعة كل ساعة أو كل يوم. نرسل طلب POST بـ JSON، موقّعًا بسرّ الورشة.
بلا إرهاق من التنبيهات: لا تسمع الورشة إلا عن عطل مؤكَّد، مع لمبة فحص المحرك مضاءة، ومستمر، وعن كل عطل مرة واحدة فقط.
الأحداث
| code.confirmed | A confirmed code (stored or permanent) with the check-engine light on, not cleared, seen on at least 2 days. Once per episode; again only after clearing and coming back. Pending codes never. |
| access.granted | A customer's access for your garage started (after accepting and, if asked, the owner's confirmation). |
| access.ended | That access ended: revoked by the owner or the garage, or expired. |
| report.created | An inspection report was made for one of the garage's own cars. |
POST https://your-system.example/webhook
Content-Type: application/json
Webhook-Signature: t=1763107200,v1=5f2b…(64 hex)
Webhook-Event: code.confirmed
Webhook-Id: 3a1d…
{
"id": "3a1d…",
"type": "code.confirmed",
"created_at": "2026-11-14T08:00:00.000Z",
"workspace_id": "…",
"data": {
"car_id": "6f1e2d3c-…",
"code": "P0301",
"state": "stored",
"first_seen_at": "2026-11-10T07:02:00.000Z",
"last_seen_at": "2026-11-13T17:45:00.000Z",
"days_seen": 3,
"mil_on": true
}
}
Digest (hourly or daily): one POST with "type": "digest" and "events": [ … ], each with id, type, created_at, data.التحقق من التوقيع
تحوي ترويسة Webhook-Signature القيمتين t (وقت Unix بالثواني) وv1 (HMAC-SHA256 لـ "t.body" بالسرّ، بصيغة hex). قارن في زمن ثابت وارفض أي t أقدم من 5 دقائق، للحماية من إعادة الإرسال.
// Node.js: check the signature before you trust the body (use the raw body, not re-serialised JSON).
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; // replay
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && timingSafeEqual(expected, given);
}
// Answer 2xx quickly. Anything else (or no answer within 10 s) is retried, at most 6 attempts.
// Use the "id" to ignore a delivery you already processed.التسليم وإعادة المحاولة
أجب بـ 2xx خلال 10 ثوانٍ. وإلا نحاول لاحقًا (بعد 10 دقائق، ثم 30 دقيقة، ثم 2 و6 و24 ساعة)، 6 مرات كحد أقصى. لا نتبع إعادة توجيه أبدًا ونرسل فقط إلى عناوين عامة. ترى الورشة آخر عمليات التسليم في التكاملات.
الخصوصية: المالك يقرر
- سيارة العميل لا تظهر إلا ما دام المالك قد منح الورشة الوصول، وفقط إذا سمح المالك بالتنزيل. الإلغاء أو انتهاء المدة يعني: تختفي من الـ API فورًا.
- لا VIN لسيارة العميل أبدًا، ولا مواقع أبدًا، ولا رابط تقرير أبدًا.
- كل طلب مسجّل في سجل الورشة، ولسيارة العميل في سجل المالك أيضًا. ما جلبه نظامك يبقى لدى الورشة: تعامل معه كبيانات شخصية.
- للقراءة فقط: لا يستطيع الـ API تغيير أي شيء أو مسح الرموز أو إرسال أي شيء إلى سيارة.
ربط جاهز مع برنامج معيّن؟
الربط مع برامج ورش معيّنة متاح عند الطلب. أخبرنا أي برنامج تستخدمه أو تطوّره.