استيراد جهات الاتصال
للاستيراد خطوتان. أولا ترفع الملف فتعود أعمدته وعينة منه وربط مقترح. ثم تؤكد أي عمود يحمل أي حقل، فيعمل الاستيراد في الخلفية 500 صف في كل مرة. يُحفظ الملف مشفرا حتى ينتهي الاستيراد ثم يُحذف.
كائن الاستيراد
Section titled “كائن الاستيراد”| الحقل | النوع | الوصف |
|---|---|---|
id |
string | imp_… |
fileName |
string | |
status |
string | uploaded أو queued أو processing أو completed أو failed. |
rowCount |
integer | صفوف البيانات دون سطر العناوين. |
columns |
string[] | أسماء العناوين. |
sample |
string[][] | حتى 5 صفوف كما رُفعت، في استجابة الرفع فقط. |
suggestedMapping |
object | الحقل مقابل العنوان، مستنتج من أسماء العناوين بالإنجليزية والعربية، في استجابة الرفع فقط. |
processed وcreated وupdated وskipped |
integer | عدادات التقدم. |
report |
object أو null | { skipped: { reason: count }, rows: [{ line, reason, column? }] }، أول 500 صف متخطى. |
error |
string أو null | سبب failed. |
startedAt وcompletedAt وcreatedAt |
string أو null |
أسباب التخطي: missing_phone وinvalid_phone وinvalid_email وinvalid_field وduplicate_in_file (رقم ظهر سابقا في الملف) وblacklisted وalready_exists (عندما تكون updateExisting بالقيمة false).
رفع ملف
Section titled “رفع ملف”/v1/contact-importscontacts:manageبصيغة multipart/form-data مع جزء واحد اسمه file. يعيد 201. يُحتسب ضمن حد العمليات المجمعة. يُسجل في التدقيق باسم contacts.import_uploaded.
| قاعدة الملف | الحد |
|---|---|
| النوع | نص UTF-8: .csv أو .txt أو .tsv |
| الحجم | 5 MB |
| الصفوف | 100000 |
| الأعمدة | 50 |
| الخلية | 1000 حرف |
| الفاصل | , أو ; أو Tab، ويُكتشف تلقائيا |
curl https://api.smsfabric.com/v1/contact-imports \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -F "file=@customers.csv;type=text/csv"{ "id": "imp_g2j5m8p1s4v7y0b3e6h9k2n5", "fileName": "customers.csv", "status": "uploaded", "rowCount": 3, "columns": ["Mobile", "First name", "Last name", "City"], "sample": [ ["0100 123 4567", "Mona", "Hassan", "Cairo"], ["+966501234567", "Omar", "Saleh", "Riyadh"], ["01001234568", "Youssef", "Adel", "Giza"] ], "suggestedMapping": { "phone": "Mobile", "firstName": "First name", "lastName": "Last name" }, "processed": 0, "created": 0, "updated": 0, "skipped": 0, "report": null, "error": null, "startedAt": null, "completedAt": null, "createdAt": "2026-11-19T11:00:00.000Z"}| الخطأ | متى |
|---|---|
400 file_required |
لا يوجد جزء file. |
413 payload_too_large |
الملف أكبر من 5 MB. |
415 unsupported_file_type |
ليس CSV، أو ملف ثنائي، أو ليس UTF-8. |
400 csv_empty وcsv_too_many_rows وcsv_too_many_columns وcsv_cell_too_long وcsv_unterminated_quote وcsv_duplicate_header |
تعذر تحليل الملف. |
بدء الاستيراد
Section titled “بدء الاستيراد”/v1/contact-imports/:id/startcontacts:manageيؤكد الربط ويضع الاستيراد في الطابور. يعيد 202 مع status: "queued". يُحتسب ضمن حد العمليات المجمعة. يُسجل في التدقيق باسم contacts.import_started، ثم باسم contacts.import_completed مع الأعداد عند انتهائه.
| حقل المحتوى | النوع | إلزامي | الوصف |
|---|---|---|---|
mapping |
object | نعم | العنوان لكل حقل: phone (إلزامي)، وfirstName، وlastName، وemail، وtags (تُقسم الخلايا عند ; أو , أو |)، وtimeZone، وcustom ({ "snake_case_key": "Header" }). |
defaultCountry |
string | لا | رمز ISO 3166-1 للأرقام المكتوبة دون رمز الدولة، مثل EG للرقم 0100 123 4567. الأرقام التي تبدأ بـ 00 مقبولة. |
groupId |
string | لا | أضف كل جهة اتصال مستوردة إلى هذه المجموعة. |
tags |
string[] | لا | حتى 5 وسوم تُضاف إلى كل جهة اتصال مستوردة. |
consent |
object | لا | { source, at?, text? } يُكتب في جهات الاتصال الجديدة، وفي الموجودة التي لا موافقة لها. |
updateExisting |
boolean | لا | true (الافتراضي) يملأ الحقول الفارغة في جهات الاتصال الموجودة ويدمج الحقول المخصصة ويضيف الوسوم. false يتخطاها كـ already_exists. |
curl https://api.smsfabric.com/v1/contact-imports/imp_g2j5m8p1s4v7y0b3e6h9k2n5/start \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mapping": { "phone": "Mobile", "firstName": "First name", "lastName": "Last name", "custom": { "city": "City" } }, "defaultCountry": "EG", "groupId": "grp_t6w9z2c5f8i1l4o7r0u3x6a9", "tags": ["import-nov"], "consent": { "source": "import", "text": "Opted in at the store counter" } }'| الخطأ | متى |
|---|---|
400 validation_failed |
عنوان مربوط غير موجود في الملف (مذكور في errors[]). |
404 not_found |
الاستيراد أو groupId لا يتبع مؤسستك. |
409 import_already_started |
بدأ الاستيراد من قبل. |
عرض عمليات الاستيراد
Section titled “عرض عمليات الاستيراد”/v1/contact-importscontacts:readمن الأحدث إلى الأقدم، مقسمة إلى صفحات عبر limit وcursor.
curl https://api.smsfabric.com/v1/contact-imports \ -H "X-Api-Key: $SMSFABRIC_API_KEY"قراءة عملية استيراد
Section titled “قراءة عملية استيراد”/v1/contact-imports/:idcontacts:readاستعلم عنها حتى تصبح status بالقيمة completed أو failed.
curl https://api.smsfabric.com/v1/contact-imports/imp_g2j5m8p1s4v7y0b3e6h9k2n5 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "id": "imp_g2j5m8p1s4v7y0b3e6h9k2n5", "fileName": "customers.csv", "status": "completed", "rowCount": 3, "columns": ["Mobile", "First name", "Last name", "City"], "processed": 3, "created": 2, "updated": 0, "skipped": 1, "report": { "skipped": { "duplicate_in_file": 1 }, "rows": [{ "line": 4, "reason": "duplicate_in_file", "column": "Mobile" }] }, "error": null, "startedAt": "2026-11-19T11:01:02.000Z", "completedAt": "2026-11-19T11:01:03.000Z", "createdAt": "2026-11-19T11:00:00.000Z"}