تخطَّ إلى المحتوى

استيراد جهات الاتصال

للاستيراد خطوتان. أولا ترفع الملف فتعود أعمدته وعينة منه وربط مقترح. ثم تؤكد أي عمود يحمل أي حقل، فيعمل الاستيراد في الخلفية 500 صف في كل مرة. يُحفظ الملف مشفرا حتى ينتهي الاستيراد ثم يُحذف.

الحقل النوع الوصف
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).

POST/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 تعذر تحليل الملف.
POST/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 بدأ الاستيراد من قبل.
GET/v1/contact-importscontacts:read

من الأحدث إلى الأقدم، مقسمة إلى صفحات عبر limit وcursor.

نافذة طرفيّة
curl https://api.smsfabric.com/v1/contact-imports \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
GET/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"
}