تصحيح بيانات علامة تجارية حالية للمراسلة
حدّث العلامة التجارية الحالية عند تغيّر معلومات الاتصال بالمنشأة أو عنوانها. احتفظ بمعرّف العلامة؛ فإنشاء تسجيل آخر ليس الطريقة المناسبة لتصحيح بيانات منشأة قائمة. استخدم حساب API مفعّلًا عبر HTTPS من عنوان IP مصدر مسموح به. يجب أن تكون العلامة مملوكة لذلك الحساب.
ابدأ بقراءة السجل الحالي. حافظ على خصوصية نسختك المحلية لأنها تتضمن بيانات هوية المنشأة ومعلومات الاتصال بها.
curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
"https://api.multitel.net/tcr/v2/brand/$BRAND_ID" \
--output current-brand.jsonالحفاظ على الحقول الحالية للعلامة التجارية
أعدّ brand-update.json من السجل الحالي، مع اختيار حقول العلامة القابلة للكتابة فقط. حافظ على هوية المنشأة والقيم المطلوبة الأخرى أثناء تطبيق التصحيح المقصود. لا ترسل استجابة GET كاملة: فلا مكان في التحديث لـ brandId أو نتائج الهوية والحالة أو الطوابع الزمنية أو الحقول الأخرى المخصصة للاستجابة فقط.
يتطلب مخطط التحديث entityType وdisplayName وcountry وemail وbrandRelationship. وتظل القواعد الخاصة بكل نوع من الكيانات سارية. بالنسبة إلى المؤسسة، احتفظ باسم الشركة القانوني ومعرّفها الضريبي وبلد إصداره وعنوانها وقطاع نشاطها، بحسب ما ينطبق. أما بالنسبة إلى صاحب المنشأة الفردية، فاحتفظ بدلًا من ذلك بالحقول ذات الصلة بالاسم الشخصي وبيانات الاتصال عبر الهاتف المحمول. استخدم القيم الفعلية الحالية، لا القيم النائبة الواردة في مثال تسجيل.
| الحقول | كيفية استخدامها |
|---|---|
| displayName, email, phone | اسم علامة يسهل التعرّف عليه ومعلومات اتصال صالحة. الحدود القصوى للأطوال: 255 و100 و20 حرفًا. استخدم التنسيق الدولي لأرقام الهاتف، بوضع علامة + متبوعة برمز البلد. |
| street, city, state, postalCode, country | عنوان حقيقي ومتسق للمنشأة. الحدود: 255 و100 و20 و10 و2 حرفًا. استخدم رموز الولايات الأمريكية المعتمدة حاليًا حيثما ينطبق ذلك. |
| entityType, companyName, ein, einIssuingCountry | الهوية القانونية. تُقيّد هذه التغييرات عندما تكون الحملات أو إجراءات التدقيق الخارجي قيد الانتظار أو نشطة. لا تحذف حملات تعمل لمجرد تجاوز قيد متعلق بالهوية. |
| firstName, lastName, mobilePhone, businessContactEmail | بيانات الهوية أو معلومات الاتصال الخاصة بالتحقق، حين تكون مناسبة لنوع الكيان. الحدود: 100 و100 و20 و255 حرفًا. |
| brandRelationship, vertical | الرموز الحالية للعلاقة وقطاع النشاط. يُسمح بتغيير العلاقة مرة واحدة فقط كل ثلاثة أشهر. لا يتيح نموذج التعديل المعتاد في البوابة تغيير العلاقة. |
| website, altBusinessIdType, altBusinessId, stockSymbol, stockExchange | الموقع الإلكتروني وبيانات الهوية البديلة للمنشأة وتفاصيل الشركة المدرجة في البورصة، بحسب ما ينطبق. احتفظ بالقيم اللازمة للتحقق من صحة بيانات الكيان. |
| referenceId, ipAddress | البيانات الوصفية المدعومة لمرجع المنشأة وعنوان IP الأصلي. لا يحدد أيّ منهما الحساب المالك، ولا يعمل أيّ منهما كمفتاح منع تكرار تنفيذ الطلب. |
استخدم كتالوجات المراسلة الحالية للاطلاع على الرموز. لا يتيح مخطط التحديث استخدام mock وسيلةً لتغيير بيئة العلامة. استخدم سير العمل المنفصل الذي خضع للمراجعة للانتقال من البيئة التجريبية إلى بيئة الإنتاج بدلًا من تغيير هذا الخيار أثناء التعديل.
إرسال التصحيح بعد مراجعته
curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
--request PUT \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--data-binary @brand-update.json \
"https://api.multitel.net/tcr/v2/brand/$BRAND_ID"استخدم مفتاحًا واحدًا لهذا التحديث المقصود، واحتفظ ببايتات جسم الطلب كما هي تمامًا. تؤدي إعادة استخدامه مع تغيير طريقة الطلب أو مساره أو معلمات الاستعلام أو جسمه إلى تعارض؛ كما تؤدي إعادة تنسيق JSON إلى تغيير البصمة. قد يُرجع الطلب المكرر الذي لا تزال معالجته جارية الرمز 409 مع Retry-After. ويمكن للطلب المكتمل أن يعيد نتيجته المحفوظة، بما في ذلك الخطأ. احتفظ بتفاصيل الطلب عند التحقق من نتيجته بعد انتهاء المهلة بدلًا من إنشاء مفتاح جديد تلقائيًا.
التحقق من السجل المحفوظ وحالة التحقق من صحة البيانات
يُرجع التحديث الناجح HTTP 200 وكائن JSON للعلامة مباشرةً، دون غلاف v3 status/response القديم. تحقّق من brandId الخاص به، ثم اجلب العلامة نفسها مجددًا باستخدام GET وقارن الحقول المقصودة. لا يقبل مسار التحديث العام غلاف changes/version الخاص بالبوابة، ولا يوفر فحص التزامن التفاؤلي الذي توفره. نسّق بين من يجرون تعديلات متزامنة؛ فمفتاح منع تكرار التنفيذ يمنع تكرار الإرسال، لكنه لا يمنع تغييرات شخص آخر يجري التعديل.
تقرأ البوابة الحالية بيانات العلامة، وتحافظ على حقولها القابلة للكتابة، وتتحقق من إصدار النموذج قبل الحفظ، ثم تقرأ النتيجة مجددًا. وتقفل حقول الهوية القانونية الأساسية عندما تجد حملات نشطة. يمكن للسجل فرض قيود إضافية، بما فيها قيود التدقيق الخارجي، حتى لو أتاح النموذج تعديل الحقل.
لا يؤدي حفظ المعلومات المصححة تلقائيًا إلى طلب تحقق جديد من الهوية، ولا يضمن الموافقة. إعادة التحقق إجراء منفصل قد تترتب عليه رسوم؛ استخدم البوابة لمراجعة الحالة الحالية وتأكيد الموافقة صراحةً على أي رسوم معروضة. لا تؤدي تحديثات العلامة المعتادة باستخدام PUT إلى خصم رسوم تسجيل منفصلة في خدمة API الحالية. وتظل رسوم الحملات والمراسلة وغيرها من الرسوم القائمة منفصلة.
معالجة الأخطاء دون إنشاء تسجيل مكرر
اقرأ حالة HTTP وتفاصيل الخطأ بصيغة JSON. عند ظهور 400، صحّح الحقل المعني أو التزم بالقيد المتعلق بالهوية أو العلاقة. وعند ظهور 401 أو 403 أو 404، تحقّق من بيانات الاعتماد وعنوان IP المصدر المسموح به والحساب المالك. وعند ظهور 429، التزم بـ Retry-After. قد يظهر 500 أو 502 بعد أن يكون السجل قد قبل التحديث؛ احتفظ بأي requestId واقرأ السجل الحالي قبل الإرسال مجددًا.
قد تترك استجابة تحديث غير فارغة لكنها غير مكتملة نسخةً محلية غير مكتملة من البيانات؛ وقد يؤدي جسم استجابة نجاح فارغ إلى إبقاء حقول قديمة في النسخة المحلية. لا تستنتج الحفاظ على الحقول من مجرد حالة نجاح. اجلب بيانات العلامة كاملةً مجددًا وعالج أي اختلاف عبر الدعم. لا يضمن هذا الدليل تنفيذ تحديثات السجل وذاكرة التخزين المؤقت المحلية والفوترة كوحدة ذرّية واحدة.