יצירת פרופיל רישום

יצירת הפרופיל פעם אחת בלבד

בקשה זו יוצרת פרופיל רישום מקומי יחד עם רשומות זהות וכתובת אצל הספק. התחילו מהרשימות העדכניות של מדינות הרישום, סוגי המספרים וכן הדרישות. הדרישות תלויות במדינה ובסוג המספר שבכוונתכם לרשום.

תגובת יצירה מוצלחת אינה אישור רגולטורי ואינה הפעלה של מספר. שמרו בנפרד את ה-UUID של המסמך, את מזהה הזהות ואת מזהה הכתובת: הם משמשים למטרות שונות. בקשה זו משנה נתוני חשבון ואינה פעולה של אימות בלבד.

בקשת יצירה

בצעו אימות באמצעות חשבון MultiTEL API המופעל שלכם וכתובת ה-IP המורשית שלו. הדוגמאות משתמשות בפרטי גישה מסוג HTTP Basic השמורים במשתני סביבה. בדקו גם את תגובת ה-HTTP וגם את ערך ה-JSON status.code; תגובת HTTP 200 לבדה אינה מעידה על הצלחה. כל ערכי הדוגמה בדויים.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data @registration-profile.json \
  https://api.multitel.net/v3/create_document

{
  "identity_type": "Personal",
  "first_name": "Example",
  "last_name": "Person",
  "phone_number": "12025550123",
  "email": "end-user@example.com",
  "city": "Example City",
  "postal_code": "00000",
  "country": "US",
  "address": "1 Example Street",
  "nationality": "US",
  "signature": "BASE64_PNG_OF_THE_AUTHORIZED_END_USER_SIGNATURE"
}

ה-JSON הוא פרופיל Personal להמחשה בלבד, ולא זהות אמיתית מוכנה להגשה. החליפו את פרטיו ואת החתימה במידע של משתמש הקצה הנדרש לפי כללי הרישום שנבחרו. נתמך גם קלט בקידוד טופס.

שדות פרופיל הרישום
שדה	חובה ופורמט
`identity_type`	חובה. השתמשו בערך המדויק Personal או Business; האימות המותנה תלוי באותיות רישיות.
`first_name, last_name`	חובה, כל אחד עד 64 תווים לכל היותר. עבור עסק, ספקו את פרטי הנציג הנדרשים על ידי המדינה שנבחרה.
`phone_number`	ערך טלפון מספרי חובה, באורך שמונה תווים לפחות. מספר בינלאומי המורכב מספרות בלבד וכולל את קידומת המדינה מתאים לאימות זה; זהו מספר ליצירת קשר, ולא רכישה של מספר.
`city, postal_code, address`	חובה, כל אחד עד 64 תווים לכל היותר.
`country`	קוד ISO חובה של מדינת הכתובת מתוך קטלוג הרישום. השירות ממפה אותו לרשומת המדינה אצל הספק.
`signature`	נתוני חתימה חובה. הפורטל הנוכחי מספק בתים של תמונת PNG בקידוד Base64 ללא הקידומת data:image/png;base64,. השיגו את חתימת משתמש הקצה דרך תהליך העבודה המורשה שלכם; מציין מקום שאינו ריק אינו חתימה בעלת משמעות.
`nationality`	חובה עבור Personal, כקוד ISO של מדינה. אין להחליפו ב-UUID של מדינה.
`company_name, incorporation_country`	חובה עבור Business. שם החברה הוא עד 64 תווים לכל היותר; incorporation_country הוא קוד ISO של מדינה.
`email`	כתובת דואר אלקטרוני אופציונלית ליצירת קשר עם משתמש הקצה, עד 254 תווים לכל היותר. דואר אלקטרוני שהושמט או ריק אינו יורש את הדואר האלקטרוני של חשבון הבסיס.
`company_reg_number, vat_id, id_number, personal_tax_id, birth_date, description`	אופציונליים במטפל זה, אך המדינה/הספק שנבחרו עשויים לדרוש חלק מהם. ספקו את הפורמטים הנדרשים לאותו רישום. קריאות API ישירות אינן מחילות אוטומטית כל נרמול שהפורטל מבצע.

מטפל v3 ישיר זה דורש שדות כתובת ויוצר כתובת. אל תניחו שאפשרות דחיית הכתובת של הפורטל זמינה דרכו.

שמרו את כל שלושת המזהים

להלן מוצגים שדות תגובה נבחרים; התגובה בפועל מכילה גם את פרטי הפרופיל שהוגשו ואת נתוני החתימה. התייחסו לתגובה המלאה כאל מידע פרטי.

{
  "status": {
    "code": 200,
    "msg": "Success Create Registration Detail."
  },
  "response": {
    "uuid": "11111111111111111111111111111111",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "country_iso": "US",
    "email": "end-user@example.com"
  }
}

response.uuid מזהה את הפרופיל המקומי. השתמשו בו עם get_document. בתגובות של documents ושל get_document, אותו מזהה פרופיל נקרא id.
response.identity_id מזהה את הזהות לצורך הגשה מאוחרת יותר של הוכחות זהות וכן מסמכים תומכים.
response.address_id מזהה את הכתובת שנוצרה. שמרו אותו בנפרד; ה-UUID של הפרופיל המקומי אינו מזהה כתובת. התאימות של צירוף הוכחת כתובת מאוחר יותר לפרופילים שנוצרו זה עתה עדיין נמצאת בבדיקה.

שתי נקודות הקצה לקריאה חוזרת של הפרופיל אינן מחזירות identity_id או address_id, ולכן שמרו את תגובת היצירה המוצלחת המקורית. אם היא אבדה, פנו אל תצוגת המסמכים בפורטל או צרו קשר עם התמיכה לפני יצירת תחליף.

מתקדם: צירוף הוכחות שהועלו מראש במהלך היצירה

ניתן לספק את identity_encryptfiles ואת address_encryptfiles כמערכים של מזהים שהוחזרו על ידי create_encrypt_files. העלו באמצעות סוג הוכחה המתאים לקטגוריית הישות, ולאחר מכן הגישו לפני פקיעת הפניית הקובץ, החלה לאחר כ-20 דקות. מטפל היצירה בודק את החשבון, הקטגוריה ומועד הפקיעה של כל הפניה שסופקה.

לשדות אלה שמות שונים מ-encrypted_file_ids של נקודת הקצה המאוחרת לצירוף. במהלך היצירה, כל קובץ נשלח כבקשת הוכחה נפרדת, גם כאשר כמה קבצים חולקים סוג הוכחה אחד. עבור הוכחת זהות שחייבת להכיל כמה קבצים יחד, השתמשו בבקשת create_proof המאוחרת עם מערך אחד. יצירת פרופיל מוצלחת לבדה אינה מספקת תוצאות אישור של הוכחות בודדות.

אם הוכחת כתובת מאוחרת יותר נדחית עבור כתובת שנוצרה זה עתה, אל תחליפו אותה ב-UUID של הפרופיל ואל תיצרו את הזהות מחדש שוב ושוב. עצרו ובדקו את הפרופיל בפורטל או מול התמיכה. נתיב הקריאה החוזרת/החיפוש של הוכחת הכתובת נותר מגבלת סקירה.

כשלים ויצירה חלקית

קוד API 400 מכסה אימות שדות, כשלי יצירה אצל הספק וכשלי שמירה מקומית. שגיאות אימות עשויות להופיע כרשומות לפי שם שדה בתוך response. קוד 500 משמש למדינת רישום לא זמינה/לא חוקית, וקוד 404 להפניות שהועלו מראש אך חסרות או שפג תוקפן. קראו את status.msg בנוסף לקוד.

הפרופיל המקומי ופעולות הספק במעלה הזרם אינם טרנזקציה אטומית אחת. בקשה שנכשלה עלולה להשאיר מצב אצל הספק גם כאשר אף פרופיל מקומי אינו מופיע ברשימה. לא נחשף מפתח אידמפוטנטיות ללקוח. לאחר פסק זמן או כשל לא ודאי, בדקו את הפרופילים הקיימים וצרו קשר עם התמיכה לפני שתחזרו על היצירה; רשימת documents ריקה אינה הוכחה לכך שלא נוצר דבר אצל הספק.