Tai lieu huong dan tich hop API VAS cloud v8 06122018

TẬP ĐỒN BƯU CHÍNH VIỄN THƠNG VIỆT NAM TỔNG CƠNG TY TRUYỀN THƠNG TÀI LIỆU HƯỚNG DẪN TÍCH HỢP API HỆ THỐNG VAS CLOUD Phiên bản: 4.0 Ngày xuất bản: 16/11/2017 Contents TÀI LIỆU HƯỚNG DẪN TÍCH HỢP API HỆ THỐNG VAS CLOUD I Mô tả chung II Các phân hệ hệ thống VAS Cloud: III API VAS Cloud 3.1 Phân hệ SMS GW 3.1.1 Đối tượng áp dụng 3.1.2 API gửi MT 3.1.2.1 Quy trình gửi tin broadcast 3.1.2.2 Quy trình gửi tin content lẻ 10 3.1.3 Nhận MO 10 3.1.4 Quy trình gửi tin broadcast 11 3.1.5 Quy trình gửi tin content lẻ 12 3.2 Phân hệ ChargingGW 12 3.2.1 Đối tượng sử dụng 12 3.2.2 API cung cấp 12 3.2.3 Mẫu tin XML gửi để charge cước 13 3.2.4 Response trả 17 3.2.5 Một số ví dụ cụ thể 18 3.2.6 Đăng ký gói EXAMPLE trường hợp không khuyến mại 18 3.2.7 Đăng ký gói miễn phí 19 3.2.8 Gia hạn gói trường hợp khơng có khuyến mại 20 3.2.9 Gia hạn gói trường hợp có khuyến mại 20 3.2.10 Mua content trường hợp không khuyến mại 21 3.2.11 Mua content trường hợp khuyến mại 22 3.3 Tích hợp mua content lẻ kênh WEB/WAP 22 3.3.1 Các tham số gửi đến link 22 3.3.2 Link Request 23 3.3.3 Thông tin link API notifyUrl nhận thông tin charge để đồng thông tin 24 3.4 OneCMS 24 3.5 Unify Portal 25 3.5.1 Tích hợp đăng kí /hủy kênh SMS 25 3.5.2 Tích hợp đăng kí /hủy kênh WAP 25 3.5.2.1 Mô tả 25 3.5.2.2 Đăng ký dịch vụ 25 3.5.2.3 Hủy dịch vụ 26 3.5.2.4 Các tham số kết nối 27 3.5.2.5 Hướng dẫn mã hóa MD5 27 3.6 SDP 29 3.6.1 Subman API 29 3.6.1.1 Hủy dịch vụ cho thuê bao - unsubscribe 30 3.6.2 CDR Exporter 32 3.6.3 Event Notifier 34 3.6.4 Notify kiện kiểm tra dịch vụ 38 3.6.5 Subman Admin 40 3.7 Phân hệ đăng kí IVR 40 3.8 Phân hệ đăng kí USSD 42 3.9 Phân hệ từ chối 44 3.10 Phân hệ VoiceGW: 45 3.10.1 Quy định chung 45 3.10.2 Tập lệnh 46 3.10.2.1 Khởi tạo gọi IAM 46 3.10.2.2 Báo chuông ACM 46 3.10.2.3 Trả lời ANM 46 3.10.2.4 Kết thúc gọi REL 47 3.10.2.5 Bridge gọi 47 3.10.2.6 Bấm phím DTMF 47 3.10.2.7 Play âm 48 3.10.2.8 Play finish 48 3.10.2.9 Stop âm 48 3.10.2.10 ACK 49 3.10.2.11 Kiểm tra trạng thái gọi 49 3.10.2.12 Kiểm tra trạng thái kênh 49 3.10.2.13 Tạo gọi nhỡ 50 3.10.2.14 Bản tin call forward 50 3.11 Phân hệ USSDGW: 51 3.11.1 Mô tả kết nối 51 3.11.2 Định dạng tin giao tiếp với USSD GW 52 3.11.2.1 SP gửi yêu cầu Login vào hệ thống 52 3.11.2.2 USSD GW phản hồi xác thực 53 3.11.2.3 Bản tin ACK 53 3.11.2.4 Bản tin phản hồi ACK 54 3.11.2.5 Định dạng trường tin trao đổi USSD GW SP 54 3.11.2.6 Ví dụ trường hợp Khách hàng chủ động 57 3.11.2.7 Ví dụ trường hợp SP chủ động 60 I Mơ tả chung Tài liệu mơ tả tính phân hệ hệ thống VAS Cloud, tương ứng với phân hệ hướng dẫn tích hợp API tương ứng II Tùy theo kịch dịch vụ cụ thể mà CP/SP kết nối API tương ứng Các phân hệ hệ thống VAS Cloud: Chức STT Tên hệ thống SMS GW Cổng SMS tất dịch vụ giá trị gia tăng, kết nối đến hệ thống SMPPGW nhà mạng thực gửi/nhận MT/MO Các MO đến từ khách hàng phần tử mạng lõi định tuyền SMSGW Tùy theo kịch cụ thể, SMSGW định tuyến cú pháp dịch vụ CP/SP thành phần hệ thống VasCloud để xử lý tiếp ChargingGW Cổng charging tất dịch vụ giá trị gia tăng, với mục đích kết nối đến hệ thống OCG nhà mạng thực trừ tiền khách hàng sử dụng dịch vụ GTGT Hiện nay, cổng Charging GW kết nối đến hệ thống OCG theo giao thức HTTP, hỗ trợ hình thử charge cước theo gói, content lẻ OneCMS Đây phân hệ quản lý nội dung, cho phép người dùng, CP quản trị nội dung dịch vụ Trong trường hợp CP khơng có CMS sử dụng phân hệ Phân hệ cung cấp sẵn số API để CP, người dùng sử dụng lập trình Unify Portal Là cổng đăng kí, hủy tập trung toàn dịch vụ qua kênh Web/Wap SMS SDP Là tảng phân phối dịch vụ, bao gồm phân hệ: Subman API : Cung cấp API quản lý thuê bao, gói cước, dịch vụ, thay đổi số điện thoại, trạng thái sử dụng gói cước th bao, truy vấn thơng tin dịch vụ, truy vấn thông tin thuê bao sử dụng dịch vụ,… Các API giúp cho trình lập trình tích hợp với phân hệ bên ngồi thực cách nhanh chóng xác CDR Exporter: Phân hệ tạo file liệu chứa thông tin thuê bao gia hạn thành cơng ngày Các file CDR giúp CP biết số thuê bao gia hạn thành công từ hệ thống SDP VasCloud Khi triển khai dịch vụ thức CP cần cung cấp tài khoản FTP để lấy file phục vụ trình đồng thông tin thuê bao, gia hạn với hệ thống dịch vụ CP Event Notifier: Phân hệ thực đồng thông tin ĐK/HUY dịch vụ từ hệ thống VasCloud sang hệ thống dịch vụ/CP, kênh phát sinh kiện ĐK/HUY hệ thống VasCloud đồng tới hệ thống CP Hệ thống đồng cho CP thơng qua hình thức Notify API Khi triển khai dịch vụ, để nhận Notify CP cần cung cấp API, cần thiết kế theo định dạng tin VasCloud quy định Subman Admin: Đây trang web quản trị dịch vụ, gói cước, CP, cấu hình tham số cho dịch vụ, CP Ngồi cịn kênh tra cứu thơng tin: Lịch sử đăng ký/hủy gói, lịch sử trừ cước, thơng tin Notify cho CP, … Voice GW Cổng kết nối thoại, cho phép dịch vụ make gọi thông qua cổng Hiện VoiceGW kết nối đến GMSC qua giao thức BICC USSD GW Cổng USSD tập trung cho dịch vụ Các dịch vụ có kết nối kiểu USSD qua cổng SCE Nhằm giúp CP tập trung phát triển dịch vụ họ tảng hợp VAS Cloud mà quan tâm đến vấn đề khác CSDL gì, để kết nối dùng tài nguyên gì, phần cứng, cổng kết nối với Telco… CP cần có tài khoản cung cấp quyền tương ứng phát triển dịch vụ tảng VAS Cloud cách dễ dàng CP cần nhập nội dung thông qua OneCMS thiết kế kịch dịch vụ môi trường SCE III API VAS Cloud 3.1 Phân hệ SMS GW 3.1.1 Đối tượng áp dụng Thông thường cú pháp ĐK, HUY, confirm định tuyến đến phân hệ Unify Portal, phân hệ xử lý phản hồi thuê bao cú pháp đăng kí, hủy, confirm Các cú pháp khác mật khẩu, sai cú pháp, cú pháp sử dụng dịch vụ … định tuyến đến hệ thống dịch vụ CP/SP CP/SP tự xử lý kịch xử lý gửi, nhận MO/MT theo API mục 3.1.2, 3.1.3 3.1.2 API gửi MT URL Service API : http://10.144.18.112/services/SMS_GW_MT_PROXY?wsdl - Giao thức kết nối : http/post xml - HTTP/POST XML : o Định dạng chung Request : SMSGW REQUEST [tran_id] [ID MO tương ứng MT] [số điện thoại nhận] [đầu số dịch vụ] [brandname dịch vụ] [Loại tin] [username_cp] [pass] [nội dung MT] [command code tương ứng với MT] [Mã CP SDP] [Mã CP charge SDP] [Mã dịch vụ SDP] [Mã gói SDP] [Giá gói SDP] o Định dạng chung Response : SMSGW RESPONSE [Mã lỗi] [Mô tả mã lỗi] Đầu vào : Loại Bắt buộc Thời gian lấy theo current miliseconds long YES ID MO tương ứng với MT Long YES destination_address Số điện thoại nhận MT String YES Đầu số dịch vụ String YES Brandname dịch vụ String NO TEXT/ TEXT_UTF8/FLASH/SILENT YES STT Tên transaction_id mo_id Mô tả source_address brandname content_type user_name Username xác thực String YES authenticate Chuỗi xác thực theo mô tả bên String Yes info Nội dung MT String YES 10 command_code Command Code tương ứng MT String NO 11 cp_code Mã CP SDP String YES 12 cp_charge Mã CP charge SDP String YES 12 service_code Mã dịch vụ SDP String YES 13 package_code Mã gói SDP String YES Loại tin 14 package_price Giá gói SDP Number YES Quy định mã hóa key xác thực : authenticate = MD5( MD5(transaction_id+user_name) + MD5(smsgw@2016+destination_address) + password) Trong : +) user_name password hệ thống SMSGW cung cấp cho CP +) MD5 : hàm mã hóa theo chuẩn quốc tế + Giữa tham số khơng có dấu cách Mã lỗi ERROR CODE ERROR DESCRIPTION Thành công SMS GW insert DB error Username or password is wrong 100 Invalide Content 101 Invalid ServiceId and Brandname 102 Invalid IP 103 CP have no permission 500 server internal error 3.1.2.1 Mô tả chi tiết Quy trình gửi tin broadcast - Bước : Format tin gửi MT không thay đổi - Bước : thay đổi nội dung thẻ thành PUSH_Mã dịch vụ 0 - Bước : Cung cấp package_code với người vận hành hệ thống SMS GW - Bước : Người vận hành hệ thống SMS GW khai báo package_code vào trang quản trị hệ thống - Bước : Sau người quản trị khai báo thành công, bắt đầu tiến hành gửi tin broadcast 3.1.2.2 Quy trình gửi tin content lẻ - Bước : Format tin gửi MT không thay đổi - Bước : thay đổi nội dung thẻ thành CONTENT_Mã dịch vụ [Giá content lẻ đó] - Bước : Tiến hành gửi tin GHI CHÚ : Đối với tin Trợ giúp, Hướng dẫn, Sai cú pháp … giá trị mặc định gói dịch vụ 3.1.3 Nhận MO - URL Service API : http://10.33.68.30:8280/services/SMS_GW_MO_PROXY.SMS_GW_MO_PROXY HttpSoap11Endpoint - Giao thức kết nối : http/post xml - HTTP/POST XML : o Định dạng chung Request : SMSGW NOTIFY [id MO tương ứng] [ đầu số dịch vụ] [số điện thoại gửi] [brandname dịch vụ] TEXT [Nội dung MO] [callback_url] Đầu vào : 10 Response: ACK 3.10.2.10 ACK Request: VOICEGWGW ACK number OK/ERROR/LIVE/PLAYING/NEXIST/IDLE/BLOCKED/INUSE String 3.10.2.11 Kiểm tra trạng thái gọi Request: VOICEGWGW STATE_CALL number Response: ACK 3.10.2.12 Kiểm tra trạng thái kênh Request: VOICEGWGW CHANNEL Response: 49 VOICEGWGW CHANNEL String idle/blocked/inuse String idle/blocked/inuse 3.10.2.13 Tạo gọi nhỡ Request: VOICEGWGW MISS number String String Trường hợp dịch vụ khởi tạo gọi, crn để trống - Response: thành công điền crn vào tin gửi ngược lại, lỗi trả tin ERROR 3.10.2.14 Bản tin call forward Request: VOICEGWGW 50 FORWARD String Trường hợp gọi bị forward tới số C, có tin gửi cho dịch vụ tương ứng 3.11 Phân hệ USSDGW: 3.11.1.Mô tả kết nối - Tài liệu hướng dẫn cách tích hợp SP với USSD GW qua giao tiếp Socket XML - Trước kết nối, SP cần chuẩn bị số thông tin sau o spid: mã id SP USSD GW cấp phát o password: mật tương ứng với spid USSD GW cấp phát o IP server SP cần đăng ký với USSD GW để tránh trường hợp bị chặn IP - Trong giao tiếp dạng này, USSD GW đóng vai trị Socket server, SP client USSD GW cung cấp IP Port để SP kết nối vào SP kết nối với USSD GW giữ kết nối, giao tiếp trao đổi tin thực qua socket Nếu lý đó, socket bị đóng, SP cần kết nối lại ban đầu trao đổi thông tin kết nối - SP chưa kết nối cần gửi tin Login để xác thực, sau xác thực thành công, kết nối giữ Nếu xác thực không thành công, lý khác IP khơng có phép, spid bị khóa, chưa đăng ký v.v… socket bị đóng Khi SP cần thực lại bước đăng nhập để tạo kết nối - Trường hợp SP tạo kết nối khơng thực login sau khoảng thời gian timeout, kết nối tự động bị đóng - Mỗi tài khoản SP mở socket đến USSD GW, thời điểm có nhiều kết nối dùng chung tài khoản kết nối trước bị đóng - Trong ví dụ đây, tag xuống dòng để minh họa, thực tế tin gửi sang cần đóng gói dòng kết thúc ký tự xuống dòng (\n) Nếu tag xuống dòng bị xem tin khơng hợp lệ Ví dụ tin hợp lệ: avgmD232d1f@\n 51 - Nếu nội dung ussdString muốn hiển thị xuống dịng điện thoại chuỗi truyền sang sử dụng ký tự xuống dòng: ký tự \t (Horizontal Tab) có mã ASCII Ví dụ muốn hiển thị điện thoại khách hàng là: Please vote: Yes No Thì chuỗi ussdString truyền sang là: String ussdString = “Please vote:\t1 Yes\t2 No” - Chú ý: Do giao tiếp SP USSD giữ kết nối, nên thấp điểm, lưu lượng, phía SP cần chủ động thiết lập thông số socket để tránh trường hợp bị timeout socket khơng có trao đổi Hoặc SP định kỳ gửi tin ACK đến USSD để đảm bảo socket khơng bị timeout khơng có lưu lượng Định dạng tin ACK mô tả phần - Có cách giao tiếp với khách hàng: o SP chủ động nhắn tin USSD xuống khách hàng (Push) o Khách hàng chủ động gọi tới shortCode SP (Pull) Ví dụ: *101# 3.11.2.Định dạng tin giao tiếp với USSD GW 3.11.2.1 SP gửi yêu cầu Login vào hệ thống Hình 1: Trao đổi tin Login avg 52 mD232d1f@ Trong đó: - (String) spid: mã id sp tương ứng - (String) password: mật cấp phát cho sp Chú ý: Thực tế tin gửi sang cần viết dòng kết thúc ký tự \n 3.11.2.2 USSD GW phản hồi xác thực avg 0 Trường hợp xác thực thành công, USSD GW trả mã lỗi 0, mã lỗi khác mặc định không thành cơng giao dịch bị đóng 3.11.2.3 Bản tin ACK Hình 2: Bản tin ACK trao đổi avg 12345 Trong đó: - (String) spid: mã id sp tương ứng - (String) id: id tin ACK 53 - Chú ý: Thực tế tin gửi sang cần viết dòng kết thúc ký tự \n 3.11.2.4 Bản tin phản hồi ACK avg 12345 0 - Mã lỗi tương ứng việc gửi/nhận ACK thành công 3.11.2.5 Định dạng trường tin trao đổi USSD GW SP avg_1253698 avg_12021458 15 23 84912998101 Hello World 15 PUSH_REQ 0 avg 108 1460453880 120 Chú ý: Thực tế tin gửi sang cần viết dòng kết thúc ký tự \n Trong đó: Tên trường msg_id Kiểu liệu String Chú thích id tin trao đổi SP USSD GW, SP cấp phát nhằm mục đích đối sóat trường hợp tin Định dạng: spid_uniquenumber 54 String id phiên giao dịch với khách hàng Nếu tin khách hàng chủ động (Pull), thông số USSD GW cấp phát, SP chủ động (Push), thông số SP cấp phát Dựa vào trường SP xác định tin trả thuộc phiên giao dịch Định dạng: spid_ uniquenumber otid/dtid Long id xác định tin trao đổi với HLR, nhằm truy vết trường hợp gửi tin sang Vinaphone bị lỗi Trường hợp khách hàng chủ động (Pull) , tin USSD GW truyền thông số cho SP, từ tin trao đổi sau phiên, SP sử dụng thông số Trường hợp SP chủ động (Push), tin gửi sang, để trống trường này, sau USSD GW phản hồi chứa thơng tin SP dung tin msisdn String Số điện thoại khách hàng bắt đầu 84 String tin nhắn gửi tới khách hàng phản hồi từ khách hàng gửi lên String Định dạng tin nhắn gửi tới khách hàng Thông thường đặt mặc định 15 (GSM-7 bit) String Nếu type kết thúc _NTF tức kết thúc phiên Kết thúc _REQ tức giữ phiên Gồm giá trị: - PULL_REQ: Dùng cho tin trao đổi qua lại SP khách hàng trường hợp khách hàng chủ động khởi tạo phiên tới SP (dạng menu) - PULL_NTF: SP Khách hàng dừng phiên giao dịch (không phải dạng menu) - PUSH_REQ: Dùng cho tin trao đổi qua lại SP khách hàng trường hợp SP chủ động khởi tạo phiên giao dịch (dạng menu) - PUSH_NTF: SP Khách hàng ngắt phiên giao dịch (dạng menu) - PUSH_INIT_NTF: Dùng cho tin SP muốn khởi tạo phiên với khách hàng (dạng khơng có menu) đồng thời kết thúc phiên - PUSH_INIT_REQ: Dùng cho tin SP muốn khởi tạo phiên với khách hàng (dạng có menu) giữ phiên - PULL_INIT_REQ: Dùng cho tin khách hàng gọi lên đầu số trans_id ussdString dataCoding type 55 - PULL_INIT_NTF: Dùng cho tin khách hàng gọi lên đầu số SP muốn kết thúc phiên errCode String Mã lỗi trình giao dịch Mã lỗi tương ứng thành công spid String mã id SP shortCode String Đầu số tương ứng với dịch vụ Các SP nhận thông số tin đến từ USSD GW sử dụng giá trị cho tin SP gửi requestTime Long unix time Int Trường hợp SP muốn hủy phiên khách hàng không phản hồi sau khoảng thời gian timeout Bằng mặc định không set timeout 56 3.11.2.6 Ví dụ trường hợp Khách hàng chủ động Hình 3: Khách hàng chủ động (Pull) - Bản tin [1a] : USSD GW gửi sang SP khách hàng gọi *108# avg_1253698 avg_12021458 15 23 84912998101 *108# 15 PULL_INIT_REQ 0 avg 57 108 1460453880 0 Chú ý: Thực tế tin gửi sang cần viết dòng kết thúc ký tự \n - Bản tin [2a]: SP phản hồi cho khách hàng “Xin chao Bam de dang ky Bam de tu choi” Chú ý: o Các thông số tạo mới: msg_id, ussdString, requestTime, timeout (nếu có) o Các thơng số giữ nguyên: trans_id, otid, dtid, dataCoding, type (nếu chưa kết thúc giao dịch), spid, shortCode avg_123456 avg_12021458 15 23 84912998101 Xin chao Bam de dang ky Bam de tu choi 15 PULL_INIT_REQ 0 avg 108 1460453990 0 - Bản tin [3a]: Khách hàng phản hồi “2” avg_256456 avg_12021458 15 23 84912998101 2 58 15 PULL_REQ 0 avg 108 1460463985 0 Chú ý: Thực tế tin gửi sang cần viết dòng kết thúc ký tự \n - Bản tin [4a]: SP kết thúc phiên giao dịch tin nhắn “Cam on quy khach” Chú ý: o Các thông số tạo mới: msg_id, ussdString, requestTime, type (chuyển thành PULL_NTF) o Trường hợp khách hàng chủ động ngắt phiên, tin gửi sang SP có type PULL_NTF Tất tin có type _NTF mặc định tin kết thúc phiên o Các thông số giữ nguyên: trans_id, otid, dtid, dataCoding, spid, shortCode avg_366456 avg_12021458 15 23 84912998101 Cam on quy khach 15 PULL_NTF 0 avg 108 1660483989 0 59 3.11.2.7 Ví dụ trường hợp SP chủ động Hình 4: SP chủ động (Push) - Bản tin [1b]: SP chủ động yêu cầu USSD gửi tin nhắn tới số 84912998101 với nội dung: “Xin chao Bam de dang ky Bam de bo qua.” avg_1553698 avg_16661458 84912998101 Xin chao Bam de dang ky Bam de bo qua 15 PUSH_INIT_REQ 0 avg 108 1460400000 0 60 Chú ý: Thực tế tin gửi sang cần viết dòng kết thúc ký tự \n - Bản tin [2b]: Khách hàng nhắn lên “2” Chú ý: o Các trường thay đổi: msg_id, otid, dtid, ussdString, type, requestTime SP sử dụng otid dtid từ đến kết thúc giao dịch o Trường type = PUSH_INIT_REQ dùng cho tin đầu tiên, tin sau đổi thành PUSH_REQ, kết thúc dùng PUSH_NTF o Các trường giữ nguyên:trans_id, msisdn, dataCoding, shortCode, errCode (nếu không lỗi), spid, timeout avg_1693698 avg_16661458 123 321 84912998101 2 15 PUSH_REQ 0 avg 108 1460400060 0 Chú ý: Thực tế tin gửi sang cần viết dòng kết thúc ký tự \n - Bản tin [3b]: SP kết thúc phiên giao dịch với khách hàng tin nhắn “Cam on quy khach” Chú ý: o Các trường thay đổi: msg_id, ussdString, requestTime, type (dùng PUSH_NTF) Nếu khách hàng chủ động ngắt phiên type gửi sang SP PUSH_NTF Tất tin có type _NTF mặc định tin kết thúc phiên o Các trường giữ nguyên:trans_id, msisdn, dataCoding, shortCode, errCode (nếu không lỗi), spid, timeout 61 avg_1703698 avg_16661458 123 321 84912998101 Cam on quy khach 15 PUSH_NTF 0 avg 108 1460400870 0 Bảng mã errorCode ý nghĩa errorCode Ý nghĩa Thành công Spid đăng nhập socket khác 203 nên không tạo socket 204 Lỗi đăng nhập user/pass 205 IP không cho phép 206 Giá trị đầu vào sai 207 Chưa đăng nhập (login) Spid tin khác với spid 208 dùng đăng nhập socket 209 dataCoding không tồn 210 Vượt TPS 211 ShortCode spid chưa active Msg_id trans_id cần bắt đầu 212 spid_ 62 Tài khoản Spid không gửi tin 213 dạng PUSH PULL 63 ... CP VNPT VAS cung cấp STT Tham số Giá trị Cp CP ID Vascloud cung cấp Service ID dịch vụ Vascloud cung cấp (number) Package ID gói Vascloud cung cấp (number) securepass mật mã an toàn Vascloud cung...Contents TÀI LIỆU HƯỚNG DẪN TÍCH HỢP API HỆ THỐNG VAS CLOUD I Mô tả chung II Các phân hệ hệ thống VAS Cloud: III API VAS Cloud 3.1 Phân hệ SMS GW ... encode lower Cp String 10 ký tự Cp ID Vascloud cung cấp Service String 20 ký tự ID dịch vụ Vascloud cung cấp (number) Package String 10 ký tự ID gói Vascloud cung cấp (number) requestdatetime