> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.
# تسجيل 10DLC للامتثال لرسائل A2P الأمريكية
> سجّل علامتك التجارية وحملاتك للامتثال لنظام 10-Digit Long Code (10DLC) الأمريكي عبر Orbit لفتح سعة A2P وقابلية التسليم لدى شركات الاتصالات.
# تسجيل 10DLC
10DLC (10-Digit Long Code) هو النظام الذي تفرضه شركات الاتصالات الأمريكية لإرسال رسائل SMS من التطبيق إلى الشخص (A2P) باستخدام أرقام هاتف قياسية مكونة من 10 أرقام. يجب على جميع الشركات التي ترسل رسائل SMS إلى أرقام أمريكية التسجيل عبر 10DLC لضمان قابلية التسليم والامتثال.
## نظرة عامة
تشترط شركات الاتصالات الأمريكية (T-Mobile وAT\&T وVerizon) التسجيل في 10DLC لرسائل A2P. الحركة غير المسجلة تواجه:
* **فلترة شرسة** — رسائل تُحظر بصمت
* **رسوم أعلى** — رسوم إضافية لكل رسالة على المرسلين غير المسجلين
* **سعة منخفضة** — حد أقصى يقارب رسالة واحدة/ثانية مقابل 75+ عند التسجيل
تتولى Orbit عملية التسجيل عبر The Campaign Registry (TCR).
**المسار الموصى به:** استخدم [معالج تسجيل 10DLC](/guides/10dlc-wizard) — فهو يحفظ مسودة قابلة للاستئناف، ويتيح لك تعبئة أقسام العلامة التجارية والحملة بأي ترتيب، ويتحقق من هاتف المالك الفرد عبر OTP، ويقدّم الاثنين معًا بشكل ذرّي. تبقى نقاط النهاية الخطية أدناه متاحة لخطوط المعالجة المبرمجة.
***
## خطوات التسجيل
### الخطوة 1: سجّل علامتك التجارية
أنشئ هوية علامة تجارية تمثل مؤسستك.
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/brand \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "PRIVATE_PROFIT",
"display_name": "Acme Corp",
"company_name": "Acme Corporation Inc.",
"ein": "12-3456789",
"phone": "+14155551234",
"street": "1 Market St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US",
"email": "compliance@acme.com",
"website": "https://acme.com",
"vertical": "TECHNOLOGY"
}'
```
يجب أن يكون `entity_type` أحد `PRIVATE_PROFIT` أو `PUBLIC_PROFIT` أو `NON_PROFIT` أو `GOVERNMENT` أو `SOLE_PROPRIETOR`. الحقول `display_name` و`company_name` و`phone` و`street` و`city` و`state` و`postal_code` و`email` مطلوبة؛ أما `ein` و`website` فاختيارية.
**الاستجابة (`201 Created`):**
```json theme={null}
{
"data": {
"brandId": "BXXXXXX",
"status": "PENDING"
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2026-03-08T12:00:00Z"
}
}
```
عادةً ما يكتمل التحقق من العلامة التجارية خلال 24–48 ساعة.
### الخطوة 2: أنشئ حملة
سجّل حالة الاستخدام المحددة لمراسلاتك.
قبل الإرسال — شغّل [مدقق ما قبل الإرسال](#preflight-your-submission) على حمولة العلامة التجارية + الحملة. فهو يلتقط رفضات TCR الحتمية (غياب صيغة إلغاء الاشتراك، روابط تقصير، تكرار اسم حالة الاستخدام) بينما لا يزال إصلاحها مجانيًا. كل إرسال مرفوض يكلف رسوم تحقق جديدة ويعيد ضبط ساعة المراجعة التي تستغرق 1–5 أيام عمل.
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/campaign \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"brand_id": "BXXXXXX",
"usecase": "CUSTOMER_CARE",
"description": "Sending order updates and support responses to customers who opted in on our website checkout form.",
"sample_message": [
"Your order #12345 has shipped! Track at https://acme.com/track/12345",
"Hi! Your support ticket #567 has been resolved. Reply STOP to unsubscribe."
],
"message_flow": "Customers opt in via a web form at checkout and confirm consent. They can reply STOP at any time to opt out.",
"help_message": "Reply HELP for assistance or contact support@acme.com.",
"optout_message": "You have been unsubscribed and will receive no further messages."
}'
```
يجب أن يكون `description` بطول 40 حرفًا على الأقل، و`message_flow` بطول 40 على الأقل، وكلٌّ من `help_message` و`optout_message` بطول 20 على الأقل. `sample_message` مصفوفة من 1–10 رسائل تمثل الحركة. حملات الفئة السياسية (`usecase` يساوي `POLITICAL_ADVOCACY` أو `POLLING_AND_VOTING`، أو `is_political: true`) تتطلب إضافيًا رمز `cv_token` من Campaign Verify.
**الاستجابة (`201 Created`):**
```json theme={null}
{
"data": {
"campaignId": "CXXXXXX",
"status": "PENDING"
},
"meta": {
"request_id": "req_def456",
"timestamp": "2026-03-08T12:05:00Z"
}
}
```
### الخطوة 3: انتظر الموافقة
تستغرق مراجعة الحملة 1–5 أيام عمل. يمكنك التحقق من الحالة:
```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/compliance/10dlc/campaigns/CXXXXXX/status \
-H "X-API-Key: dv_live_sk_your_key_here"
```
**الاستجابة:**
```json theme={null}
{
"data": {
"campaignId": "CXXXXXX",
"status": "APPROVED",
"brandId": "BXXXXXX",
"mnoStatuses": {
"10017": "APPROVED",
"10035": "APPROVED",
"10095": "REVIEW"
},
"provider": "telnyx"
},
"meta": {
"request_id": "req_ghi789",
"timestamp": "2026-03-09T09:00:00Z"
}
}
```
حقل `status` عند المستوى الأعلى هو قرار مستوى CSP. أما `mnoStatuses` فهو خريطة الموافقة لكل شركة اتصالات (المفاتيح هي معرفات MNO — مثل `10017` لـ T-Mobile، و`10035` لـ AT\&T، و`10095` لـ Verizon)؛ وقد تكون الحملة `APPROVED` على مستوى CSP بينما لا تزال في `REVIEW` لدى شركة اتصالات بعينها.
**الحالات:**
| الحالة | الوصف |
| ---------- | ---------------------------------------- |
| `PENDING` | مُرسلة، بانتظار مراجعة شركة الاتصالات |
| `APPROVED` | مقبولة — يمكنك بدء الإرسال |
| `FAILED` | مرفوضة — راجع `rejectionReason` للتفاصيل |
### الخطوة 4: ابدأ الإرسال
بمجرد الموافقة، تحصل الرسائل المرسلة من الأرقام المسجلة على كامل سعة 10DLC وقابلية التسليم.
إذا عاد إيداع بنتيجة `FAILED`، أو حدّت درجة التحقق من فئتك، أو احتجت إلى السعة الفعلية التي تحصل عليها حملة معتمدة — يغطي [دليل رفضات 10DLC وإعادة التحقق](/guides/10dlc-rejections-and-revet) نقاط نهاية فك الترميز وإعادة التحقق والسعة.
***
## افحص إيداعك قبل الإرسال
معظم رفضات TCR حتمية — نفس مجموعة أنماط المحتوى ونقص
الاكتمال تُسقِط الإيداعات الأولى مرارًا وتكرارًا. كل رفض
يحرق رسوم تحقق جديدة (4–15 دولارًا لكل إعادة إرسال) ويعيد
ضبط ساعة مراجعة 1–5 أيام عمل. تُرفِق Orbit مدقق ما قبل إرسال
يُقيّم حمولة العلامة التجارية + الحملة مقابل كتالوج أنماط
الرفض المعروفة **قبل** إرسالها، ويعيد نتائج لكل حقل — كل منها
مع درجة خطورة، والمقطع النصي المخالف بالضبط، واقتراح
إعادة صياغة ملموس.
`POST /api/v1/compliance/10dlc/preflight`
المدقق محرك قواعد خالص: لا شيء يُرسَل إلى TCR، ولا شيء يُخزَّن،
ولا يُنشأ أي طلب. يمكن لأي دور في المؤسسة استدعاؤه — لا يلزم
نطاق `numbers:write`.
أرسل كائني العلامة التجارية والحملة تمامًا كما تنوي إيداعهما،
مع `brand_vetting_score` اختياري (0–100) إذا كنت تحصل على واحد
بالفعل:
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/preflight \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"brand": {
"display_name": "Acme Corp",
"entity_type": "PRIVATE_PROFIT",
"ein": "12-3456789",
"email": "compliance@acme.com",
"website": "https://acme.com"
},
"campaign": {
"usecase": "MARKETING",
"description": "Acme sends weekend promotional offers to customers who opt in on our checkout page.",
"sample_message": [
"Acme: 20% off today. Shop at https://bit.ly/acme-sale"
],
"message_flow": "Customers opt in at checkout. They can reply STOP at any time to opt out.",
"help_message": "Reply HELP for assistance or email support@acme.com.",
"optout_message": "You are unsubscribed. Reply STOP to opt out.",
"expected_msg_per_day_per_number": 5000
},
"brand_vetting_score": 45
}'
```
**الاستجابة (`200 OK`):**
```json theme={null}
{
"data": {
"score": 61,
"verdict": "block",
"findings": [
{
"ruleId": "R-CAMP-SAMPLE-SHORTENER",
"severity": "error",
"field": "campaign.sample_message[0]",
"message": "Public URL shortener detected. Carriers auto-reject shortener domains in sample messages.",
"match": "bit.ly",
"suggestion": "Replace the shortener with a link on your own domain (e.g. acme.com/sale)."
},
{
"ruleId": "R-CAMP-SAMPLES-COUNT",
"severity": "warn",
"field": "campaign.sample_message",
"message": "Only one sample message provided. TCR vets 2-10 distinct samples covering your real traffic.",
"suggestion": "Add distinct samples (welcome, reminder, confirmation) so TCR sees the full campaign."
},
{
"ruleId": "R-CAMP-SAMPLE-CTA-STOP",
"severity": "warn",
"field": "campaign.sample_message[0]",
"message": "Sample message does not reference STOP. Carriers expect opt-out wording in at least one sample.",
"match": "Acme: 20% off today.",
"suggestion": "Append \"Reply STOP to unsubscribe.\" to the sample."
},
{
"ruleId": "R-CAMP-THROUGHPUT-TIER",
"severity": "warn",
"field": "campaign.expected_msg_per_day_per_number",
"message": "Declared throughput exceeds the daily cap your vetting tier qualifies for.",
"suggestion": "Lower the declared volume or raise your vetting score to qualify for a higher tier."
}
],
"engine": "tcr-preflight/v1"
},
"meta": {
"request_id": "req_pf001",
"timestamp": "2026-08-28T09:00:00Z"
}
}
```
**شكل الاستجابة.** حقل `score` من `0` إلى `100` (حيث `100` = لم تُطابق أي أنماط معروفة؛ تُخصم كل نتيجة بحسب خطورتها). `verdict` هو القرار المجمَّع — `block` عند وجود أي نتيجة بخطورة `error`، و`warn` دون درجة 75، وإلا `pass`. كل إدخال في `findings[]` يحمل `ruleId` مستقرًا، و`severity` (`error` | `warn` | `info`)، والمسار النقطي `field` الذي ينطبق عليه، وملخصًا بشريًا، و`match` اختياريًا مع النص المخالف بالضبط (لإبرازه في واجهتك)، و`suggestion` — إعادة صياغة تحل النتيجة. `engine` هو إصدار محرك القواعد (`tcr-preflight/v1`)، لتتمكن من مقارنة الدرجات عبر الزمن.
حكم `pass` يعني "لم تُطابق أنماط رفض معروفة" — لا "سيقبل TCR".
يلتقط المدقق الغالبية الحتمية من الرفضات؛ ولا يزال إيداعك يمر
بمراجعة شركات الاتصالات العادية. هو مستشار، ولا يكون بوابة أبدًا:
أنت تقرر متى تُودع.
### ما الذي يفحصه مدقق 10DLC
يُرمِّز الكتالوج الأنماط التي يرفض TCR وشركات الاتصالات عليها. أهم القواعد:
| معرّف القاعدة | الخطورة | ما تلتقطه |
| ----------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `R-BRAND-EIN` | error | صيغة EIN لا تطابق شكل معرّف ضريبي أمريكي صالح |
| `R-BRAND-EMAIL-DOMAIN` | warn | بريد إلكتروني على نطاق مزوّد مجاني تخفّض شركات الاتصالات وزنه (gmail.com ونحوها) |
| `R-BRAND-WEBSITE` | warn | الموقع غائب أو ليس رابطًا عامًا ذا علامة |
| `R-CAMP-DESC-LEN` / `R-CAMP-DESC-GENERIC` | error | الوصف قصير جدًا، أو يكرر اسم حالة الاستخدام حرفيًا |
| `R-CAMP-SAMPLES-COUNT` | warn | عينات رسائل قليلة جدًا — المدقق يُبلغ أيضًا عن نص نائب مثل `Hi {{firstName}}` (`R-CAMP-SAMPLE-PLACEHOLDER`) |
| `R-CAMP-SAMPLE-SHAFT` | error | محتوى SHAFT-C في العينات (جنس، كراهية، كحول، أسلحة نارية، تبغ، قنّب) — فئات الرفض التلقائي |
| `R-CAMP-SAMPLE-BLOCKLIST` | error | عبارات قائمة حظر المحتوى لدى شركات الاتصالات (MEF / UCC §3.4) — كتالوج مشترك مع مدقق الرموز القصيرة |
| `R-CAMP-SAMPLE-SHORTENER` | error | مقصّرات URL العامة (bit.ly وt.co وtinyurl.com …) — شركات الاتصالات ترفضها تلقائيًا |
| `R-CAMP-SAMPLE-CLICK-HERE` | warn | "انقر هنا" غامض بلا اسم وجهة |
| `R-CAMP-SAMPLE-CTA-STOP` | warn | لا عينة تذكر إلغاء الاشتراك STOP |
| `R-CAMP-HELP` / `R-CAMP-OPTOUT` | error | `help_message` / `optout_message` تفتقر مجموعة الكلمات المفتاحية القياسية |
| `R-CAMP-FLOW` | error | `message_flow` غائب أو عامي (سير الاشتراك الذي يدقق TCR بأشد ما يكون عليه) |
| `R-CAMP-AI-USECASE` | warn | حملة مدفوعة بالذكاء الاصطناعي يغيب وصفها عن إفصاح حالة استخدام الذكاء الاصطناعي |
| `R-CAMP-THROUGHPUT-TIER` | warn | الحجم اليومي المُعلَن يتجاوز السقف الذي يؤهل له `brand_vetting_score` |
أصلح كل نتيجة بترتيب الخطورة، أعد تشغيل المدقق حتى تكون
الاستجابة نظيفة (`verdict: "pass"`)، ثم أودع نفس الحمولة
عبر [الخطوة 2](#step-2-create-a-campaign).
***
## أنواع حالات الاستخدام
مرِّر إحدى هذه القيم في حقل `usecase` عند إنشاء حملة
(الخطوة 2). رموز TCR **كبيرة الحالة** — أرسلها كما تراها بالضبط؛
تُرفض القيمة صغيرة الحالة عند التسجيل.
| حالة الاستخدام | الوصف | السعة |
| ----------------------------- | ------------------------------------------------------------------------ | ---------------------- |
| `CUSTOMER_CARE` | دعم الحساب، وردود الخدمة، والتنبيهات | تُحدَّد بدرجة التحقق |
| `MARKETING` | العروض الترويجية، والعروض، والتواصل التجاري | تُحدَّد بدرجة التحقق |
| `ACCOUNT_NOTIFICATION` | تغييرات الحساب، والفوترة، والإشعارات الأمنية | تُحدَّد بدرجة التحقق |
| `DELIVERY_NOTIFICATION` | تحديثات الطلب والشحن والتسليم | تُحدَّد بدرجة التحقق |
| `TWO_FACTOR_AUTH` | رموز المرور لمرة واحدة وتحديات 2FA | تُحدَّد بدرجة التحقق |
| `POLLING_AND_VOTING` | الاستطلاعات والاقتراع (الحملات السياسية تحتاج أيضًا رمز Campaign Verify) | تُحدَّد بدرجة التحقق |
| `PUBLIC_SERVICE_ANNOUNCEMENT` | إعلانات ذات نفع عام | تُحدَّد بدرجة التحقق |
| `CHARITY` | رسائل المنظمات المسجلة 501(c)(3) غير الربحية | منخفضة (ممر 501(c)(3)) |
| `EMERGENCY` | رسائل السلامة والتنبيه العام | أولوية شركات الاتصالات |
| `MIXED` | حالات استخدام متعددة في حملة واحدة (الافتراضي) | سقف يومي منخفض |
***
## فئات السعة
تُمنح سعة 10DLC كـ**سقف مقاطع رسائل في اليوم، لكل رقم**،
وليس كمعدل في الثانية. فئتك تُحدَّد بدرجة تحقق علامتك (0–100) و
نوع كيانك المسجل. سقف كل فئة اليومي ينطبق على كل رقم
مُسنَد إلى الحملة، لذا تتناسب سعة حملتك الكلية مع عدد
الأرقام المسندة.
| الفئة | الأهلية | السقف اليومي لكل رقم |
| --------------- | ----------------------------------------- | ---------------------- |
| مالك فردي | نوع كيان `SOLE_PROPRIETOR` | \~1,000 رسالة/يوم |
| حجم منخفض قياسي | الأساس (أي علامة، بما فيها غير المُقيّمة) | \~30,000 رسالة/يوم |
| قياسية | درجة تحقق 50 فأعلى | \~200,000 رسالة/يوم |
| فئة عليا | درجة تحقق 75 فأعلى | \~2,000,000 رسالة/يوم |
عكس هذه الأرقام افتراضيات T-Mobile؛ لدى AT\&T وVerizon هي ضمن
حوالي 10%. تُمنح أعلى فئة يؤهل لها درجة تحققك. العلامة التي لا
درجة لها بعد تعود افتراضيًا إلى أساس الحجم المنخفض القياسي.
حسّن درجة تحققك بتقديم معلومات علامة مكتملة ودقيقة، بما فيها EIN والموقع ورابط رمز السهم المالي (إن كانت عامة). تفتح الدرجة 75 فأعلى سقف الفئة العليا اليومي.
***
## متطلبات الامتثال
1. **موافقة اشتراك صريحة.** يجب أن تملك موافقة صريحة من كل مستلم قبل الإرسال.
2. **معالجة إلغاء الاشتراك.** أنجِز طلبات STOP فورًا. تعالج Orbit تلقائيًا STOP وCANCEL وUNSUBSCRIBE.
3. **محتوى الرسائل.** يجب أن تكون عينات الرسائل ممثلة للحركة الفعلية.
4. **استخدام متسق.** أرسل فقط ما يطابق حالة استخدام حملتك المسجلة.
***
## التسجيل عبر لوحة التحكم
يمكنك أيضًا إتمام تسجيل 10DLC كاملًا عبر لوحة تحكم Orbit:
1. انتقل إلى **Settings > Compliance > 10DLC**
2. انقر **Register Brand** واملأ تفاصيل شركتك
3. بعد موافقة العلامة، انقر **Create Campaign**
4. اختر حالة استخدامك، أضف رسائل عينة، واسند أرقامًا
5. ارفعها لمراجعة شركات الاتصالات
***
## تهيئة مورد قواعد البلاد
هذا القسم موجه إلى **مشغّلي المنصة / النشرات ذاتية الإضافة**. عملاء
SaaS على `api.orbit.devotel.io` لا يحتاجون ضبط هذه — تُحدّ Orbit
قواعد بلاد 10DLC نيابة عنك.
تُبقي Orbit مجموعة قواعد بلد US-10DLC الكنونية (أنواع المرسل، منهج
السعة، اشتراط التسجيل) محدثة بالسحب من **مورد شريك iconectiv TCR**. الموصل يعيش في
`@devotel/compliance/country-rule-feeds` ويعمل في مكانين:
* **عند الطلب** — إجراء إدارة "Refresh from upstream"
(`POST /api/v1/compliance/country-rules/sync?provider=iconectiv`).
* **أسبوعيًا** — حلقة التحديث التلقائي في
جدول مزامنة الامتثال لعامل webhook.
الموصل **اختياري وناجح-فشل-مفتوح**: عند غياب بيانات اعتماده يسجل خطأ
ويتخطى، تاركًا قواعد البلد الموجودة قائمة. هو مورد بيانات قوام
قراءة فقط — وليس مسار نقل رسائل أبدًا، لذا لا تخرج SMS الصادرة
إلا عبر softswitch Devotel.
| المتغيّر | مطلوب | الوصف |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DEVOTEL_TCR_API_KEY` | للمورد | مفتاح API لشريك iconectiv TCR. يتخطّى الموصل عند غيابه. |
| `DEVOTEL_TCR_PARTNER_ID` | للمورد | معرّف شريك iconectiv TCR (جزء مسار في API الشريك). يتخطّى الموصل عند غيابه. |
| `DEVOTEL_TCR_FEED_URL` | اختياري | تتجاوز الرابط الأساسي لـ API الشريك. يفترض `https://csp-api.campaignregistry.com`. |
| `DEVOTEL_TCR_OPTOUT_URL` | اختياري | يتجاوز الرابط الكامل لنقطة TCR Universal Opt-Out التي تحرّك سحب opt-out DNC. يفترض `/v1/partner//universalOptOuts`. قراءة فقط — لا يكون مسار إرسال أبدًا. |
يجب ضبط كل من `DEVOTEL_TCR_API_KEY` و`DEVOTEL_TCR_PARTNER_ID` ليكمل
المورد؛ وإذا نقص أحدهما لا يفعل الموصل شيئًا. سجّل Devotel كشريك TCR
في [iconectiv.com](https://iconectiv.com/) للحصول على بيانات الاعتماد.
***
## استكشاف الأعطال وإصلاحها
| المشكلة | الحل |
| ---------------------- | ------------------------------------------------------------------------------ |
| رفض العلامة | تحقق من مطابقة EIN لسجلات IRS بدقة |
| رفض الحملة | تأكد من أن عينات الرسائل تطابق حالة الاستخدام المحددة وتتضمن صيغة إلغاء اشتراك |
| درجة تحقق منخفضة | قدّم معلومات علامة مكتملة (موقع، رمز سهم، اسم قانوني كامل) |
| لا تزال الرسائل تُفلتر | تأكد من أن حالة الحملة `approved` والأرقام مسندة |
إرسال SMS عالي الحجم دون تسجيل 10DLC قد يسبب فلترة شركة الاتصالات وحجب الرسائل واحتمال تعليق الرقم.