دليل تنفيذ مكتوب وفق سلوك الـ API الموثَّق؛ ولا يذكر اسم أي عميل. نُشر في .
المشكلة: العرض دقيق، أما الصورة فلا
عرض التأجير التمويلي محدد: سنة صنع واحدة، والفئة التي حُسب عليها القسط، ولون طلاء من لوحة الألوان الحالية للشركة المصنعة، ومبلغ شهري صالح حتى تاريخ معين. أما الصورة المجاورة له فغالبًا ليست كذلك: صورة صحفية من العام الماضي، أو لون لم تعد السيارة متوفرة به، أو هيكل مختلف. وعندما يكون القسط دقيقًا والصورة تقريبية، تكون الصورة هي ما يشكك فيه العميل.
ثم ينتقل العرض نفسه: إلى صفحة الطراز، وإلى ملف PDF لعرض السعر، وإلى بريد إلكتروني، وإلى أداة تهيئة يُدير فيها العميل السيارة. ويحتاج كل منها المركبة نفسها باللون نفسه.
كيف يبدو التكامل
- عرض تأجير لكل سنة طراز، مرتبط بمعرّف مركبة الكتالوج لتلك السنة.
- طلاء الشركة المصنّعة كرمز hex، على كل صورة في العرض.
- الصورة نفسها في ملف PDF لعرض السعر وفي البريد الإلكتروني، عبر عناوين URL موقّعة، فلا يحتفظ أي مستند أو أداة عرض بمفتاح أبدًا.
- نموذج ثلاثي الأبعاد لكل لون طلاء لأداة التهيئة، يُنشر كتضمين من سطرين.
الخطوة 1: اربط كل عرض بمعرّف المركبة الخاص بسنة طرازها
GET /api/v1/vehicles?make=&model= مجاني وعام، ويعرض كل سنوات الطراز، ولكل سنة معرّف مركبة ثابت. خزّن معرّف سنة الطراز الخاصة بالعرض مع العرض نفسه.
curl -s "https://carimage.dev/api/v1/vehicles?make=honda&model=cr-v"{
"data": {
"make": {
"id": 474,
"name": "HONDA",
"slug": "honda"
},
"model": {
"name": "CR-V",
"slug": "cr-v",
"vehicle_type": "Passenger Car"
},
"vehicles": [
"…",
{
"year": 2025,
"id": "veh_exjyt8r21gmhe"
},
{
"year": 2026,
"id": "veh_b6kgpb03d73r9"
},
{
"year": 2027,
"id": "veh_8nr7res56a6jq"
}
]
}
}عندما تُطرح عروض 2027 تأخذ معرّف 2027، وتحتفظ عروض 2026 بمعرّفها: فالمعرّف لا يتغير أبدًا، لذا تظل الصفحة أو عرض السعر المبني عليه يعمل بعد تغيّر سنة الطراز. يعتمد الكتالوج على الشركة المصنّعة والطراز والسنة، لذا فإن فئة التجهيز التي يُحتسب عليها القسط (EX-L أو Sport Touring) نصٌّ في العرض، وليست شيئًا تدّعيه الصورة أبدًا.
الخطوة 2: طلاء الشركة المصنّعة، بقيمة hex
تغطي الإعدادات المسبقة البالغ عددها 15 الألوان الشائعة؛ أما العرض فيحتاج إلى اللون الذي تُعرض به السيارة فعلًا. خذ رمز hex من عينة لون الشركة المصنّعة وأرسله دون علامة في عنوان URL (color=1f3a5f) أو مع علامة # في JSON ("color": "#1f3a5f"). يكلّف رمز hex القدر نفسه الذي يكلّفه الإعداد المسبق، أي رصيدًا واحدًا، لأن كل لون طلاء هو إعادة تلوين لصورة محايدة واحدة، ورمز hex المطابق لعينة إعداد مسبق هو ذلك الإعداد نفسه، ويُخزَّن مؤقتًا مرة واحدة.
# the 2026 offer's hero: its model year, in the paint it is offered in, cropped to a 16:9 slot
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
"https://carimage.dev/api/v1/images/car?vehicle=veh_b6kgpb03d73r9&view=front-3-4&color=1f3a5f&w=1024&h=576&fit=contain&trim=1&padding=4&format=webp" \
-o cr-v-2026-offer.webpالخطوة 3: ملف PDF لعرض السعر والبريد الإلكتروني للعرض عبر عناوين URL موقّعة
عادةً ما يكون ملف PDF لعرض السعر صفحة HTML تُحوَّل بواسطة خدمة PDF أو متصفح بلا واجهة. ضعوا في القالب URL موقّعًا من POST /api/v1/image-urls، ولا تضعوا المفتاح أبدًا: يحمّل المحوِّل الصورة مرة واحدة ويضمّنها، لذا فإن المدة الافتراضية البالغة 1 ساعة كافية تمامًا، ويقوم format: "jpg" بتسطيحها على خلفية بيضاء، وهو ما يناسب المستندات. يكلّف URL 1 رصيد عند إنشائه.
تُفتح رسالة العرض متى ما وصل إليها العميل. أنشئ صورتها مع renew: true وttl_seconds عند الحد الأقصى البالغ 7 يومًا، واضبط renew_days على عدد الأيام المتبقية في العرض: كل أسبوع إضافي تُفتح فيه الرسالة يكلّف رصيدًا واحدًا، والأسابيع الهادئة لا تكلّف شيئًا، وعند انتهاء العرض يتوقف العنوان عن التجدد وتنتهي صلاحيته. في الخطة المدفوعة، يغطي الترخيص الصورة المُنشأة ضمن ما ينتجه منتجك للعملاء، بما في ذلك عروض الأسعار.
import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";
const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });
// The offer's picture: its model year, in the paint it is offered in.
const offerImage: ImageParams = {
vehicle: offer.vehicleId, view: "front-3-4", color: offer.paintHex, // "#1f3a5f"
width: 1024, height: 576, fit: "contain", trim: true, padding: 4,
};
// The quote PDF: rendered from HTML, the picture loaded once and embedded, on white.
const { data: [forPdf] } = await client.createImageUrls({ ...offerImage, format: "jpg" });
const pdf = await renderQuotePdf({ ...quote, vehicleImageUrl: forPdf.url });
// The offer email: loads for as long as the offer runs, then stops renewing.
const { data: [forEmail] } = await client.createImageUrls(
{ ...offerImage, width: 600, height: 338, format: "auto" },
{
ttlSeconds: 604800,
renew: true,
renewDays: Math.min(Math.max(daysUntil(offer.endsOn), 1), 365),
idempotencyKey: `offer:${offer.id}:email`,
}
);الخطوة 4: نموذج ثلاثي الأبعاد لأداة تخصيص السيارة
POST /api/v1/3d مع معرّف مركبة العرض ولون طلائها وpublish: true يبني نموذجًا مكسوًّا بالخامات (GLB وUSDZ وFBX ونسخة للمتصفح) ويمنحه عناوين URL لا تحتاج إلى مفتاح مع شيفرة تضمين من سطرين. تبلغ التكلفة 100 رصيد (1.00 US$) لكل مركبة ولون، تُخصم مرة واحدة؛ وطلب المركبة نفسها باللون نفسه مجددًا من حسابك مجاني. يستغرق النموذج الأول للمركبة 10–20 minutes، وكل لون طلاء إضافي يعيد استخدام شبكتها المضلّعة ويستغرق 1–2 minutes.
curl --fail-with-body -X POST https://carimage.dev/api/v1/3d \
-H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: configurator-cr-v-2026-1f3a5f" \
-d '{"vehicle": "veh_b6kgpb03d73r9", "color": "#1f3a5f", "publish": true}'{
"data": {
"id": "5b0f3c2e-8a41-4d7e-9c10-2f6e1a3b4d58",
"object": "3d_model",
"status": "queued",
"progress": 0,
"vehicle": {
"id": "veh_b6kgpb03d73r9",
"make": "honda",
"model": "cr-v",
"year": 2026
},
"color": "#1f3a5f",
"files": null,
"public": {
"id": "m3d_…",
"url": "https://carimage.dev/api/v1/3d/public/m3d_…",
"files": null,
"embed": {
"script": "https://carimage.dev/embed/3d.js",
"html": "<script src=\"https://carimage.dev/embed/3d.js\" async></script>\n<car-3d model=\"m3d_…\"></car-3d>"
}
}
},
"billing": {
"charged_on": "creation",
"credits_charged": 100,
"already_owned": false
}
}استعلم من GET /api/v1/3d/{id} (كل 10–15 ثانية كافٍ تمامًا)، أو مرّر webhook_url مع webhook_secret لتتلقى طلب POST موقَّعًا واحدًا عندما يصبح النموذج جاهزًا. يحتوي data.public.embed.html على السكربت وعنصر <car-3d>: الصقه في صفحة العرض. يعرض العنصر صورة الغلاف فورًا ويجلب العارض في أول مرة يظهر فيها النموذج عند التمرير؛ وتحدد view وspin وbackdrop وar وalt زاوية البداية، والدوران، والخلفية، وزر الواقع المعزز على الهواتف (Quick Look عبر USDZ على iOS)، والنص البديل. النشر وكل عملية تحميل مجانية.
<script src="https://carimage.dev/embed/3d.js" async></script>
<select id="paint" aria-label="Paint">
<option value="1f3a5f">Blue</option>
<option value="white">White</option>
</select>
<!-- One published model per paint. Only the visible one is loaded: the script
fetches a viewer the first time a model scrolls into view. -->
<car-3d data-paint="1f3a5f" model="m3d_…" view="front-3-4" spin backdrop="studio" ar
alt="2026 Honda CR-V in the offer's blue"></car-3d>
<car-3d data-paint="white" model="m3d_…" view="front-3-4" spin backdrop="studio" ar
alt="2026 Honda CR-V in white" hidden></car-3d>
<script>
document.querySelector("#paint").addEventListener("change", (event) => {
for (const model of document.querySelectorAll("car-3d[data-paint]")) {
model.hidden = model.dataset.paint !== event.target.value;
}
});
</script>أداة تهيئة بعدد 4 من ألوان الطلاء تعني 4 من النماذج، أي 400 رصيد لمرة واحدة. وتطلب ورش التغليف والتظليل التي تستخدم API النماذج ثلاثية الأبعاد بالطريقة نفسها؛ وتتناول قصتها الملفات والصيغ، وتغطي وثائق النماذج ثلاثية الأبعاد الـ webhooks والتنزيلات وإلغاء النشر.
CLI وSDK وMCP
- CLI: يطلب
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitلونًا، وينتظر جاهزيته، ثم يطبع شيفرة التضمين. - SDK:
client.vehicles({ make, model })وclient.createImageUrls(…)وclient.create3dModel({ vehicle }, { color, publish: true })وclient.wait3dModel(id). - MCP: مع
?toolset=all، تتيحcreate_3d_modelوget_3d_modelوpublish_3d_modelللمساعد طلب لون طلاء ونشره لمندوب المبيعات. خطوات الإعداد متوفرة في صفحة MCP.
الأسئلة الشائعة
- هل تُظهر الصورة فئة التجهيز التي احتُسبت عليها الدفعة؟
- لا. يعتمد الكتالوج على الشركة المصنّعة والطراز والسنة، لذا تُعرض جميع فئات طراز السنة نفسها على أنها المركبة نفسها. اذكر الفئة في نص العرض بجوار الصورة، ولا تصف الصورة أبدًا بأنها تلك الفئة أو بأنها سيارة متوفرة في المخزون.
- هل يكلّف طلاء الشركة المصنّعة أكثر من اللون المُعدّ مسبقًا؟
- لا. كل لون طلاء هو إعادة تلوين لصورة محايدة واحدة، لذا يكلّف لون hex وحدة رصيد واحدة مثل أي من الألوان المسبقة البالغ عددها 15، ولون hex المطابق لعيّنة لون مسبق هو ذلك اللون المسبق نفسه. يُطبَّق لون hex بقيمة sRGB تلك تمامًا تحت إضاءة الاستوديو، لذا قارنوا الصورة بعيّنة اللون قبل نشر العرض.
- كم تكلّف أداة تخصيص السيارة بـ 4 من ألوان الطلاء؟
- 400 وحدة رصيد، مرة واحدة: 100 وحدة رصيد لكل لون طلاء للمركبة. إعادة طلب مركبة ولون يملكهما حسابكم بالفعل مجانية (تكون قيمة billing.already_owned هي true)، كما أن النشر والاستعلام الدوري والتنزيلات وكل تحميل لنموذج منشور مجانية أيضًا.
- كم يستغرق إنشاء نموذج ثلاثي الأبعاد، وماذا لو فشل؟
- يستغرق النموذج الأول للمركبة 10–20 minutes؛ وكل لون طلاء إضافي للمركبة نفسها يعيد استخدام شبكتها المضلّعة ويستغرق 1–2 minutes. يُسترد المبلغ كاملًا عن النموذج الذي يفشل، وعندما يبلغ توليد النماذج ثلاثية الأبعاد سعته اليومية يُرفض الطلب مع وقت لإعادة المحاولة قبل خصم أي شيء.
- هل يمكن لملف PDF لعرض السعر أن يحتفظ بالصورة بعد انتهاء العرض؟
- نعم. في الخطط المدفوعة، يغطي الترخيص الصورة المُنشأة ضمن ما ينتجه منتجك للعملاء، بما في ذلك عروض الأسعار والكتيّبات، وتحتفظ الصورة المُسلَّمة ضمن الخطة بهذا الترخيص بعد انتهاء الخطة، فلا يفقد عرض السعر المحفوظ صورته أبدًا. أما إنشاء صورة لعرض جديد فيتطلب خطة نشطة في حينه.