Gửi hồ sơ đăng ký số điện thoại

Chuẩn bị hồ sơ đã lưu và số điện thoại

Sử dụng quy trình này để liên kết hồ sơ đăng ký đã lưu với số điện thoại đã mua và yêu cầu xét duyệt đăng ký đối với các số được nhà mạng hỗ trợ. Đây không phải là API kích hoạt chung cho mọi nhà cung cấp số điện thoại. Yêu cầu thành công không chứng minh rằng tài liệu đã được phê duyệt hoặc số điện thoại đã hoạt động.

Sử dụng tài khoản API MultiTEL đã được bật qua HTTPS với thông tin xác thực và các hạn chế IP đã cấu hình cho tài khoản đó. Cả hồ sơ chưa bị xóa và số điện thoại đã mua, chưa bị hủy đều phải thuộc tài khoản của bạn.

Tạo một hồ sơ đăng ký hoặc chọn hồ sơ hiện có. Lưu lại uuid của hồ sơ cục bộ do create_document trả về; get_document trả về cùng mã tham chiếu cục bộ đó trong id.
Để gửi yêu cầu qua nhà mạng, hồ sơ cần có các mã tham chiếu danh tính và địa chỉ đã lưu. Đính kèm các bằng chứng và tài liệu bổ trợ bắt buộc theo quy trình tương ứng trước khi gửi.
Kiểm tra xem số điện thoại và hồ sơ có đáp ứng các yêu cầu áp dụng cho quốc gia và số điện thoại đó hay không. Đừng cho rằng hồ sơ đã lưu được phê duyệt cho mọi số điện thoại.

Gửi yêu cầu liên kết

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

Đường dẫn chứa số điện thoại đã mua, không phải UUID của số đó, số máy nhánh PBX hay mã định danh danh tính. Trình xử lý loại bỏ các ký tự không phải chữ số khỏi số điện thoại. Sử dụng số quốc tế đầy đủ có mã quốc gia. Ví dụ này là giả định và bạn phải thay bằng số điện thoại của mình cùng mã tham chiếu hồ sơ cục bộ đã lưu.

Các trường gửi đăng ký
Trường	Bắt buộc	Ý nghĩa
`document_uuid`	Có	Giá trị uuid chính xác của hồ sơ cục bộ đã lưu. Không thay bằng identity_id, address_id từ xa đã được che, mã định danh tệp tải lên hoặc giá trị registration_details_id được trả về.
`service_description`	Không	Mô tả dịch vụ dự kiến, được chuyển tiếp để nhà mạng xác minh. Khoảng trắng ở đầu và cuối được loại bỏ.
`onetime_files`	Tùy thuộc quy trình	Mảng được chấp nhận cho các tài liệu dùng một lần của nhà mạng. Trình xử lý hiện tại loại bỏ khoảng trắng ở đầu và cuối rồi chuyển tiếp các chuỗi trong mảng mà không phân giải các mã tham chiếu tệp tải lên cục bộ. Chưa xác định được khả năng tương thích với các mã định danh đã được che do create_encrypt_files trả về; hãy xem phần giới hạn đối với tài liệu dùng một lần bên dưới trước khi sử dụng trường này.

Đối với yêu cầu nhiều phần, mảng sử dụng các trường onetime_files[] lặp lại. Yêu cầu JSON cũng được chấp nhận với Content-Type: application/json; các thuộc tính của yêu cầu được hợp nhất vào dữ liệu biểu mẫu. Có thể cung cấp number trong dữ liệu gửi khi không có số điện thoại trong đường dẫn. Nên dùng đường dẫn tường minh như minh họa ở trên để tránh mơ hồ.

Phân biệt liên kết với phê duyệt

Đọc cả kết quả HTTP và status.code trong JSON. Lỗi JSON có thể được trả về cùng HTTP 200. Khi thành công qua nhà mạng, thông báo là Address verification task created; awaiting carrier review. Ví dụ này sử dụng các mã tham chiếu giả định.

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

Các mã định danh liên quan đến nhà cung cấp là các mã tham chiếu đã được che, không phải các mã định danh hồ sơ cục bộ có thể dùng thay thế cho nhau. document_uuid vẫn là mã tham chiếu hồ sơ cục bộ mà bạn đã gửi. Trong nhánh xử lý qua nhà mạng của trình xử lý này, registration_details_id là giá trị băm thêm từ mã tham chiếu cục bộ đó; không dùng nó để thay thế document_uuid trong các yêu cầu hồ sơ hoặc gửi đăng ký sau này.

Một số số điện thoại đã được cấp sử dụng liên kết danh tính cục bộ thay vì tạo yêu cầu xác minh qua nhà mạng. Kết quả thành công của các số này là Identity associated. kèm mảng response rỗng. Kết quả đó không tạo tác vụ xét duyệt của nhà mạng và cũng không xác nhận việc phê duyệt. Cổng thông tin có quy trình liên kết mới hơn, với cách xử lý nhà cung cấp và kiểm tra việc gửi lại khác với điểm cuối này.

Xử lý lỗi mà không tạo tác vụ trùng lặp

Mã API 400 áp dụng khi thiếu số điện thoại hoặc mã tham chiếu hồ sơ. Mã 404 áp dụng khi hồ sơ hoặc số điện thoại không khả dụng cho tài khoản, hoặc số điện thoại không có trong kho số của nhà mạng. Mã 422 có thể báo thiếu mã tham chiếu danh tính/địa chỉ, các yêu cầu của bên bán hoặc việc nhà mạng từ chối xác thực. Thiếu cấu hình gọi lại có thể gây ra mã 503, còn lỗi truyền tải khi tạo tác vụ có thể gây ra mã 502. Đọc thông báo và mọi requirement_diagnostics thay vì xử lý mọi lỗi theo cùng một cách.

Nhánh xử lý qua nhà mạng có thể cập nhật các cờ đăng ký đang chờ trong hệ thống cục bộ trước khi hoàn tất việc xác thực yêu cầu, kiểm tra cấu hình gọi lại hoặc tạo tác vụ. Vì vậy, lỗi không có nghĩa là trạng thái cục bộ vẫn giữ nguyên, và chỉ một cờ đang chờ không chứng minh rằng tác vụ đã tồn tại. Không dùng các cờ đó để xác nhận việc phê duyệt hoặc xác nhận yêu cầu đã được chuyển đến nơi nhận.

Nhà cung cấp có thể chấp nhận tác vụ ngay cả khi thao tác cơ sở dữ liệu cục bộ sau đó thất bại, và hàm hỗ trợ này không kiểm tra kết quả của mọi thao tác ghi cục bộ trước khi báo thành công. Trình xử lý này không có tham số phía máy khách để bảo đảm gửi lại không tạo tác vụ mới, cũng không có cơ chế ngăn gửi trùng lặp. Sau khi hết thời gian chờ, gặp lỗi hoặc nhận kết quả không chắc chắn, hãy kiểm tra lịch sử đăng ký của số điện thoại trong cổng thông tin hoặc liên hệ bộ phận hỗ trợ trước khi gửi lại. Chỉ riêng việc không có bản ghi cục bộ không chứng minh rằng nhà cung cấp chưa nhận được gì.

Giới hạn đối với tài liệu dùng một lần

Trình xử lý chấp nhận onetime_files và chuyển tiếp từng chuỗi không rỗng vào quan hệ tệp được mã hóa của nhà mạng. Trình xử lý không tra cứu các bản ghi tải lên của tài khoản sở hữu hoặc chuyển đổi các mã định danh tải lên bên ngoài đã được che thành mã định danh tệp của nhà cung cấp. Việc kiểm tra ngoại tuyến đã xác minh hành vi chuyển tiếp, chứ chưa xác minh việc đính kèm thành công ở phía nhà mạng.

Đừng cho rằng có thể sao chép mã định danh tệp từ create_encrypt_files vào trường này để hoàn tất quy trình thỏa thuận dùng một lần. Sử dụng cổng thông tin hoặc xác nhận với MultiTEL quy trình mã định danh được hỗ trợ khi số điện thoại yêu cầu các tài liệu này. Đây vẫn là phần chưa được giải quyết trong quá trình rà soát API, không phải ví dụ đã được xác minh từ đầu đến cuối.

Bảo vệ thông tin đăng ký

Chỉ gửi thông tin và tài liệu mà bạn được phép sử dụng cho số điện thoại đó. Giữ các mã tham chiếu hồ sơ và xác minh gắn với đúng tài khoản, đồng thời tránh ghi nhật ký toàn bộ dữ liệu đăng ký gửi đi. Yêu cầu này không xóa hoặc thay thế mọi bằng chứng hay lần xác minh trước đó. Việc xét duyệt của nhà mạng, kích hoạt và lưu giữ là các quy trình riêng biệt.