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 định hợp tác. API sử dụng chuẩn REST + JSON qua HTTPS, xác thực bằng apiKey và có môi trường Sandbox riêng để kiểm thử mà không phát sinh giao dịch thật.
Bài viết này tổng hợp Gigago Agent eSIM API là gì, API có thể làm được gì, ai nên dùng, cách API vận hành, nên đọc tài liệu theo thứ tự nào, cách test trước khi chạy thật và cách bảo mật apiKey. Nếu bạn đang cân nhắc tích hợp eSIM vào hệ thống của mình, đây là những nội dung nên nắm trước khi bắt đầu.
Gigago Agent eSIM API (phiên bản v1) cho phép hệ thống của đối tác tra cứu gói cước theo quốc gia, tạo và quản lý đơn hàng, kiểm tra số dư tài khoản và nhận eSIM tự động qua webhook.
Gigago eSIM hiện cung cấp eSIM tại hơn 200 quốc gia và vùng lãnh thổ. Agent API cho phép đối tác kết nối các sản phẩm eSIM này với hệ thống bán hàng của mình thay vì phải xử lý từng đơn hàng thủ công.
Các chức năng chính được cung cấp trong Agent eSIM API v1 gồm:
| Nhóm chức năng | API trong tài liệu | Dùng để làm gì |
| Tra cứu | Danh sách mã quốc gia | Lấy danh sách quốc gia, vùng lãnh thổ có gói eSIM |
| Tra cứu | Danh sách gói cước | Lấy các gói eSIM theo quốc gia để hiển thị cho khách |
| Đơn hàng | Tạo đơn hàng | Đặt mua eSIM cho khách từ hệ thống của đối tác |
| Đơn hàng | Danh sách đơn hàng, Chi tiết đơn hàng | Tra cứu và theo dõi các đơn đã tạo |
| Tài khoản | Kiểm tra số dư | Xem số dư tài khoản agency |
| Webhook | Nhận eSIM (url_notify) | Nhận thông tin eSIM (mã QR hoặc LPA) tự động khi đơn được xử lý |
Tóm lại, Agent eSIM API bao phủ ba phần chính của quy trình bán eSIM: lấy dữ liệu sản phẩm, tạo và tra cứu đơn hàng, sau đó nhận thông tin eSIM để giao cho khách hàng.
Gigago eSIM API phù hợp với các doanh nghiệp đã có website, ứng dụng hoặc hệ thống bán hàng riêng và có đội kỹ thuật (developer) để tích hợp eSIM trực tiếp vào quy trình của mình.
Một số nhóm đối tác có thể phù hợp với mô hình này gồm:
API gắn với tài khoản agency có số dư, tương ứng với các mô hình White-Label và Hybrid trong hệ thống hợp tác của Gigago.
Nếu doanh nghiệp không có đội kỹ thuật, API chưa phải lựa chọn phù hợp. Khi đó có hai hình thức hợp tác khác đơn giản hơn:
Vì vậy, không phải doanh nghiệp nào cũng cần tích hợp API. API phù hợp khi doanh nghiệp muốn chủ động đưa eSIM vào hệ thống bán hàng hoặc sản phẩm của chính mình.
→ Xem thêm bài chi tiết: Bán eSIM qua API là gì? Doanh nghiệp của bạn có cần không?
Hệ thống của đối tác gọi Gigago API để tra cứu gói và tạo đơn. Gigago xử lý đơn, sau đó gửi thông tin eSIM về hệ thống của đối tác qua webhook. Đối tác dùng thông tin đó để giao eSIM cho khách.
Hệ thống của đối tác gọi API để lấy danh sách quốc gia và gói cước từ Gigago API, rồi hiển thị cho khách.
Khách hàng lựa chọn sản phẩm ngay trên website, ứng dụng hoặc hệ thống bán hàng của đối tác.
Sau khi khách hàng hoàn tất quá trình đặt mua, hệ thống của đối tác gửi request đến API Gigago để tạo đơn hàng.
Gigago cung cấp thông tin eSIM cho hệ thống của đối tác thông qua webhook url_notify. Thông tin eSIM có thể bao gồm QR code hoặc LPA.
Hệ thống của đối tác có thể sử dụng thông tin eSIM nhận được để hoàn tất quy trình giao eSIM cho khách hàng.
Toàn bộ quá trình giao tiếp với API sử dụng REST + JSON qua HTTPS và xác thực bằng apiKey. Agent eSIM API có thể tích hợp vào website, ứng dụng di động hoặc hệ thống nội bộ của đối tác.
→ Để hiểu sâu hơn về luồng này, chi tiết từng bước được giải thích trong bài “Một đơn eSIM đi qua API như thế nào?”
Có. Gigago tách riêng hai môi trường: Sandbox (DEV) để test tích hợp và Production (PROD) để chạy thật. Trên Sandbox, đối tác dùng dữ liệu demo, trong đó có gói thử nghiệm GIGA-DEMO, nên không phát sinh giao dịch hay chi phí thật.
| Sandbox (DEV) | Production (PROD) | |
| Mục đích | Test tích hợp | Bán hàng thật |
| Dữ liệu | Dữ liệu demo, gói GIGA-DEMO | Gói cước và đơn hàng thật |
| Giao dịch, chi phí | Không phát sinh | Mỗi đơn phát sinh giao dịch và chi phí thật |
| apiKey | Key riêng cho Sandbox | Key riêng cho Production |
Key của hai môi trường tách biệt hoàn toàn và không dùng chung.
Do đó, quy trình phù hợp là:
Sandbox → kiểm thử → hoàn thiện tích hợp → chuyển sang Production.
→ Nếu bạn là developer hoặc project manager đang chuẩn bị tích hợp, có thể xem thêm bài: “Thử tích hợp eSIM API mà không tốn tiền: Sandbox và gói GIGA-DEMO” (link: bài 4).
Mỗi đối tác có một apiKey riêng, gửi trong header của mọi request qua HTTPS để xác định đối tác, quyền truy cập và các giới hạn tương ứng. Đây là chìa khóa duy nhất để truy cập hệ thống Gigago dưới danh nghĩa đối tác.
apiKey có giá trị như mật khẩu: nếu bị lộ, người khác có thể tạo đơn và phát sinh chi phí bằng tài khoản của đối tác.
Tài liệu của Gigago yêu cầu áp dụng 3 nguyên tắc bảo mật apiKey sau:
→ Nếu bạn đang triển khai API cho hệ thống thực tế, hãy xem chi tiết tại bài Bảo mật apiKey khi tích hợp eSIM API: 5 quy tắc bắt buộc..
Gigago Developer Docs áp dụng bốn nguyên tắc, được ghi ngay trên trang giới thiệu của tài liệu:
Mọi API đều trả về cùng một cấu trúc JSON gồm các trườngcode, message, totalRecords, result và extra, nên đội kỹ thuật chỉ cần xử lý một khung phản hồi cho toàn bộ hệ thống.
Trong đó:
| Trường | Kiểu dữ liệu | Ý nghĩa |
| code | Number | Trạng thái xử lý, ví dụ 200 là thành công |
| message | String | Mô tả kết quả |
| totalRecords | Number | Tổng số bản ghi trả về |
| result | Array / Object / Number / null | Dữ liệu chính |
| extra | Object / null | Dữ liệu bổ sung |
Với đối tác mới, thứ tự dưới đây giúp đi từ nền tảng đến luồng bán hàng hoàn chỉnh:
Khi cần hỗ trợ trong quá trình tích hợp, đối tác nên gửi kèm môi trường đang dùng (DEV hoặc PROD), request_id và thời gian gọi API để đội kỹ thuật Gigago kiểm tra nhanh hơn.
apiKey được cấp sẵn khi đối tác có tài khoản agency của Gigago. Đối tác xem và reset apiKey trong phần Profile / API Key của tài khoản. Để có tài khoản agency, doanh nghiệp đăng ký làm đối tác Gigago.
Có. Gigago Developer Docs có song ngữ Việt – Anh, chuyển đổi bằng nút VI/EN ở góc phải màn hình.
Có. Mọi thay đổi phá vỡ tương thích đều được thông báo trước qua trang Changelog trong tài liệu, để đối tác cập nhật hệ thống trước khi thay đổi có hiệu lực.
Có. Gigago cung cấp môi trường Sandbox / DEV riêng để đối tác kiểm thử API trước khi chuyển sang Production.
Sandbox và Production được tách biệt hoàn toàn và sử dụng apiKey riêng. Sandbox không phát sinh giao dịch thật, phù hợp để developer kiểm tra quá trình tích hợp trước khi đưa hệ thống vào vận hành.
Có. Agent eSIM API cung cấp webhook url_notify để hệ thống của đối tác nhận thông tin eSIM sau quá trình xử lý đơn hàng.
Thông tin eSIM có thể bao gồm QR code hoặc LPA, giúp đối tác tiếp tục xử lý và giao eSIM cho khách hàng trong hệ thống của mình.
Gigago API sử dụng JSON cho request và response, mã hóa UTF-8 và xác thực bằng apiKey trong Header.
API sử dụng cấu trúc response tiêu chuẩn gồm các trường code, message, totalRecords, result và extra. Các API cụ thể có thể có thêm tham số filtering, pagination hoặc sorting theo nhu cầu.
Request và response đều dùng JSON (UTF-8). Mọi API trả về cùng một cấu trúc gồm code (mã trạng thái, 200 là thành công), message, totalRecords, result (dữ liệu chính) và extra (dữ liệu bổ sung).
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 […]
Khi đi du lịch nước ngoài, việc duy trì liên lạc qua iMessage là nhu cầu thiết yếu của nhiều người dùng iPhone. Tuy nhiên, khi chuyển sang sử dụng eSIM du lịch thay vì SIM vật lý, không ít du khách băn khoăn liệu iMessage có hoạt động bình thường hay không. Trong bài […]
Khi sử dụng eSIM du lịch ở nước ngoài, không ít người gặp tình trạng thiết bị tự động chuyển sang một mạng di động có tín hiệu kém hơn, khiến kết nối chậm hoặc mất sóng. Nguyên nhân nằm ở hai cơ chế ít người biết: network switching và network steering. Trong bài viết […]
eSIM là công nghệ thay thế SIM vật lý đang ngày càng phổ biến, đặc biệt với du khách quốc tế. Tuy nhiên, nhiều người vẫn băn khoăn về mức độ an toàn của eSIM. Bài viết này sẽ giúp bạn hiểu rõ eSIM có thực sự an toàn không, và liệu có nên sử […]
eSIM đang ngày càng phổ biến trong các chuyến đi quốc tế nhờ tính tiện lợi và dễ sử dụng. Tuy nhiên, nhiều người dùng vẫn chưa rõ khi gói eSIM hết hạn thì có tự hủy không và cần phải thao tác gì để tránh ảnh hưởng đến thiết bị. Bài viết sau sẽ […]
Việc cài đặt và kích hoạt eSIM trên điện thoại Huawei rất đơn giản. Chỉ vài phút, bạn có thể bắt đầu sử dụng eSIM mà không cần tháo lắp SIM vật lý. Sau đây là chi tiết các bước chuẩn bị, cài đặt và kích hoạt eSIM trên Huawei chi tiết cho người mới. […]
