LPA là chuỗi thông tin kích hoạt eSIM. Mã QR eSIM là cách biểu diễn chuỗi thông tin kích hoạt LPA dưới dạng hình ảnh để thiết bị có thể đọc và sử dụng khi cài eSIM. Vì vậy, người dùng có thể cài eSIM bằng cách quét mã QR hoặc nhập thông tin LPA thủ công.
Với doanh nghiệp bán eSIM qua API, dữ liệu nhận về thường là chuỗi LPA, không phải file ảnh QR. Ví dụ, Gigago eSIM API trả chuỗi LPA trong trường qr_code, không trả file ảnh QR, nên hệ thống của người bán cần tự tạo mã QR và giao kèm thông tin kích hoạt thủ công cho khách.
Bài này giải thích cấu trúc chuỗi LPA, sự khác nhau giữa mã QR và LPA, và cách người bán xử lý, giao thông tin eSIM cho khách. Nếu mới tìm hiểu về API của Gigago, xem tổng quan tại bài Gigago eSIM API: tài liệu tích hợp cho đối tác và developer.
LPA là chuỗi thông tin kích hoạt eSIM, thường có cấu trúc dạng:
LPA:1$<SM-DP+ address>$<Activation Code>Định dạng này được mô tả trong đặc tả SGP.22 của GSMA, tổ chức đặt chuẩn cho eSIM.
Trong đó, các phần được ngăn cách bằng dấu $:
LPA:1: phiên bản của định dạng LPA.Khi người dùng quét mã QR chứa chuỗi này, thiết bị đọc các thông tin cần thiết để thực hiện quá trình cài đặt eSIM.
Đối với hệ thống bán eSIM qua API, điều quan trọng là giữ nguyên chuỗi qr_code khi xử lý và truyền dữ liệu. Không nên tự ý thêm, bớt hoặc thay đổi ký tự trong chuỗi.
Mã QR và chuỗi LPA không phải hai eSIM khác nhau. Mã QR biểu diễn chuỗi LPA dưới dạng hình ảnh để điện thoại đọc bằng camera; chuỗi LPA là cùng thông tin đó ở dạng văn bản.
| Mã QR | Chuỗi LPA | |
| Hình thức | Hình ảnh | Chuỗi ký tự |
| Người dùng | Quét bằng camera hoặc trình cài eSIM | Nhập thủ công |
| Dữ liệu bên trong | Thông tin kích hoạt eSIM | Thông tin kích hoạt eSIM |
| Khi bán qua API | Hệ thống có thể tự tạo từ LPA | API có thể trả trực tiếp |
| Trường hợp sử dụng | Cách cài đặt thuận tiện nhất | Phương án dự phòng khi không quét QR |
Tình huống thường gặp là khách mua eSIM và mở email ngay trên chiếc điện thoại cần cài eSIM. Khi đó khách không thể dùng camera của máy để quét mã QR đang hiển thị trên màn hình của chính nó. Nếu email chỉ có ảnh QR, khách phải mở mã trên laptop, mượn một máy khác hoặc liên hệ hỗ trợ. Vì vậy, người bán nên giao cả mã QR lẫn thông tin kích hoạt thủ công.
→ Cách cài eSIM bằng mã QR hoặc nhập thủ công trên từng loại máy được hướng dẫn trong bài Hướng dẫn cài eSIM trên các thiết bị.
Thông tin eSIM nằm trong trường order_detail của dữ liệu Gigago gửi về webhook url_notify, đồng thời có trong kết quả của API Chi tiết đơn hàng (getOrderDetailAgency).
Luồng đầy đủ từ lúc lấy gói, tạo đơn đến khi nhận eSIM qua webhook được giải thích trong bài Một đơn eSIM đi qua API như thế nào?
order_detail là chuỗi JSON, hệ thống cần parse trước khi đọc. Theo ví dụ trong tài liệu, mỗi eSIM gồm các trường chính:
| Trường | Ý nghĩa | Ví dụ trong tài liệu |
| qr_code | Chuỗi LPA dùng để cài eSIM | LPA:1$…$… |
| iccid | Mã ICCID của eSIM | dãy số |
| msisdn | Số điện thoại, nếu gói có kèm số | no_number khi gói không có số |
| data, validity | Dung lượng và thời hạn gói | Daily 1GB, 1 day |
| apn | Tên APN của mạng | mobile |
| code, ggg_code, description | Mã sản phẩm, mã gói và mô tả eSIM | GIGA-DEMO |
| short_link | Liên kết rút gọn (theo tài liệu) | chuỗi ký tự |
Lưu ý: Dù tên trường làqr_code giá trị là chuỗi LPA, không phải ảnh QR. Hệ thống của đối tác có thể sử dụng chuỗi này làm nội dung để tạo ảnh QR. Cần giữ nguyên chuỗi này khi lưu, xử lý và truyền dữ liệu, không thêm, bớt hay đổi ký tự nào.
Nếu hệ thống của bạn nhận được chuỗi LPA từ API, bạn có thể tạo ảnh QR bằng một thư viện tạo QR tương ứng với ngôn ngữ lập trình đang sử dụng, với nội dung là nguyên văn chuỗi LPA trong qr_code. Không nên tự ý thay đổi nội dung chuỗi trước khi tạo QR. Chỉ cần sai một ký tự, dữ liệu trong QR có thể không còn chính xác.
Ví dụ minh họa (Node.js), đọc qr_code từ order_detail và tạo ảnh QR:
// Ví dụ dùng thư viện "qrcode" (npm install qrcode)const QRCode = require('qrcode');
const esims = JSON.parse(payload.result[0].order_detail); // result là mảng; order_detail là chuỗi JSONconst lpa = esims[0].qr_code; // chuỗi LPA: "LPA:1$...$..."
// Tạo ảnh QR từ nguyên văn chuỗi LPAconst qrImage = await QRCode.toDataURL(lpa);
// Tách các phần của chuỗi nếu cần hiển thị riêng cho khách nhập thủ côngconst [, smdp, activationCode] = lpa.split('$');Ví dụ trên là cách làm phổ biến, không phải code mẫu chính thức trong tài liệu Gigago. Developer có thể sử dụng thư viện phù hợp với ngôn ngữ và framework mà hệ thống đang sử dụng.
Tùy thiết bị và cách cài đặt, khách có thể cần thông tin kích hoạt ở dạng khác nhau. Một số máy cho phép dán nguyên chuỗi LPA, một số máy yêu cầu nhập riêng địa chỉ SM-DP+ và mã kích hoạt. Vì vậy, hệ thống nên lưu và hiển thị được cả chuỗi LPA đầy đủ, địa chỉ SM-DP+ và mã kích hoạt đã tách, thay vì chỉ phụ thuộc vào ảnh QR.
Sau khi nhận dữ liệu eSIM, người bán dựng email, trang giao eSIM hoặc màn hình trong app. Thông tin giao cho khách nên đủ để khách tự cài eSIM mà không cần liên hệ hỗ trợ:
data), thời hạn (validity), số điện thoại nếu gói có (msisdn).apn), phòng khi máy của khách cần cài APN thủ công để vào mạng.Đây là phần xử lý phía người bán, tính từ lúc Gigago gửi kết quả đơn. Có thể tóm tắt toàn bộ phần xử lý sau khi khách mua eSIM như sau:
url_notify.qr_code (chuỗi LPA) và các thông tin gói.Nếu webhook không nhận được thông tin, hệ thống vẫn có thể gọi API Chi tiết đơn hàng với request_id để kiểm tra trạng thái và lấy lại thông tin eSIM. Đây là lý do cần lưu request_id của mỗi đơn ngay khi tạo đơn.
Có. Chuỗi LPA và mã QR là dữ liệu dùng để cài eSIM: người khác có được chúng thì có thể cài eSIM đó lên máy của họ nếu khách chưa cài. Người bán cần xử lý chúng như dữ liệu nhạy cảm của đơn hàng.
Một số nguyên tắc cơ bản như sau:
Khách mua eSIM cũng nên giữ mã QR và chuỗi LPA của mình như một mã riêng, không chia sẻ công khai.
Thông tin eSIM khác với apiKey:
apiKey: thông tin xác thực để hệ thống đối tác gọi Gigago API.qr_code / LPA: thông tin dùng để kích hoạt một eSIM cụ thể.Vì vậy, cả hai đều cần được bảo vệ nhưng vì hai mục đích khác nhau.
→ Xem cách bảo vệ apiKey được hướng dẫn trong bài: Bảo mật apiKey khi tích hợp Gigago eSIM API: 5 quy tắc bắt buộc
LPA là chuỗi thông tin kích hoạt eSIM, thường có dạng LPA:1$$<địa chỉ SM-DP+$$<mã kích hoạt>. Chuỗi này chứa thông tin để điện thoại tải hồ sơ eSIM từ máy chủ SM-DP+ về máy.
Không. Theo tài liệu, trường qr_code chứa chuỗi LPA dạng LPA:1$..., không phải ảnh. Hệ thống của người bán tạo ảnh QR từ chuỗi này.
Không. Mã QR biểu diễn chuỗi LPA dưới dạng hình ảnh để điện thoại đọc bằng camera. Cả hai dùng để cài cùng một eSIM.
Có. Người dùng có thể sử dụng thông tin kích hoạt thủ công nếu thiết bị và hệ điều hành hỗ trợ phương thức cài đặt này.
Khách nhập thủ công trong phần thêm eSIM của điện thoại: địa chỉ SM-DP+ và mã kích hoạt, tách từ chuỗi LPA. Vì vậy thông tin giao cho khách nên có cả mã QR lẫn chuỗi LPA.
Gọi API Chi tiết đơn hàng (getOrderDetailAgency) với request_id của đơn. Kết quả có qr_code và các thông tin eSIM khác.
Sử dụng request_id để gọi API Chi tiết đơn hàng và lấy lại trạng thái cũng như thông tin eSIM.
apiKey là mã định danh và thông tin xác thực mà Gigago cấp cho mỗi đối tác để gọi eSIM API. Key có giá trị như mật khẩu. Nếu bị lộ, người khác có thể sử dụng API dưới tài khoản của đối tác, bao gồm tạo đơn và phát sinh chi phí. Vì vậy, […]
Tích hợp Gigago Agent eSIM API có thể chia thành 3 giai đoạn: chuẩn bị tài khoản và hệ thống, kiểm thử toàn bộ luồng đơn trên Sandbox với gói GIGA-DEMO, sau đó chuyển sang Production. Checklist dưới đây giúp PM và developer kiểm tra những việc cần hoàn tất trước khi chạy bán hàng […]
Với Gigago Agent eSIM API, một đơn eSIM đi qua 5 bước chính: hệ thống của đối tác lấy danh sách quốc gia, lấy gói cước, tạo đơn hàng, rồi nhận thông tin eSIM do Gigago gửi về qua webhook url_notify. Khi cần, hệ thống tra cứu lại chi tiết đơn bằng request_id. Bài viết […]
Bán eSIM qua API là việc doanh nghiệp kết nối website, ứng dụng hoặc hệ thống bán hàng của mình với hệ thống của nhà cung cấp eSIM, để tự động tra gói cước, tạo đơn và nhận eSIM cho khách mà không cần nhân viên thao tác từng đơn. API phù hợp với doanh […]
Gigago cung cấp Agent eSIM API để đối tác tích hợp việc bán và quản lý eSIM du lịch vào website, ứng dụng hoặc hệ thống bán hàng riêng. Toàn bộ tài liệu được công khai tại api-docs.gigago.com, nên đối tác và đội kỹ thuật có thể xem trước cách tích hợp trước khi quyết […]
Khi chuẩn bị cho chuyến du lịch quốc tế, nhiều người lo lắng liệu có thể tiếp tục sử dụng WhatsApp để giữ liên lạc với gia đình và bạn bè khi chuyển sang eSIM du lịch hay không. Đây là câu hỏi hoàn toàn hợp lý, đặc biệt khi WhatsApp đã trở thành ứng […]
