Một đơn eSIM đi qua API như thế nào? Luồng tích hợp Gigago eSIM API cho đối tác

Trần Vân

|

Đăng: 10/2026

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 dưới đây đi qua toàn bộ luồng từ lúc khách chọn điểm đến đến khi hệ thống của đối tác nhận được thông tin eSIM, kèm endpoint, phương thức HTTP, các trường dữ liệu quan trọng và ví dụ request trên Sandbox.

Nếu chưa nắm tổng quan về Gigago Agent eSIM API, bạn có thể đọc trước bài Gigago eSIM API: Tài liệu tích hợp cho đối tác và developer hoặc xem trực tiếp tại Tài liệu Gigago Developer Docs.

Toàn bộ luồng một đơn eSIM

Luồng tổng quát:

Chọn quốc gia → Lấy gói → Chọn gói → Tạo đơn → Gigago xử lý → Webhook trả eSIM → Đối tác giao eSIM cho khách

Nếu webhook cần được kiểm tra lại, hệ thống có thể sử dụng request_id để gọi API chi tiết đơn hàng.

Trước khi bắt đầu: hệ thống cần gì?

Mọi request tới Gigago Agent eSIM API đều cần hai header:

• apiKey (mã định danh đối tác do Gigago cấp) và
• Content-Type: application/json.

Địa chỉ gọi API là {{base_url}} cộng đường dẫn của từng API.

Gigago cung cấp môi trường Sandbox (DEV) để đối tác kiểm thử trước khi chuyển sang Production:

Khi chuyển từ Sandbox sang Production, đội kỹ thuật chỉ cần đổi base_url và apiKey. Cấu trúc request và response giữ nguyên. apiKey được cấp sẵn khi đối tác có tài khoản agency, và chỉ được dùng ở phía server.

Lưu ý: Không đưa apiKey vào frontend hoặc code hiển thị cho người dùng. Đây là thông tin xác thực của tài khoản agency.

Bước 1: Lấy danh sách quốc gia

Tóm tắt: hệ thống lấy danh sách quốc gia có gói eSIM để hiển thị cho khách chọn điểm đến.

API Danh sách mã quốc gia (POST /api/partner/getCountryCodes) trả về mỗi quốc gia với mã quốc gia theo chuẩn ISO Alpha-2 (ví dụ cn, fr), tên châu lục, tên quốc gia và thủ đô. Mã quốc gia này được dùng để lọc gói cước ở bước 2.

Phần extra trong response có thêm ba nhóm dữ liệu hữu ích cho giao diện bán hàng:

• continent_country: danh sách châu lục, dùng để nhóm quốc gia theo châu lục.
• popular_countries: các quốc gia bán chạy.
• regions_type: các loại khu vực để lọc gói: ALL (tất cả), LOCAL (gói một quốc gia), MUL (gói nhiều quốc gia).

Request body gồm columnFilters (để {} nếu không lọc), page (bắt đầu từ 0) và pageSize (đặt 0 để lấy tất cả).

Bước 2: Lấy gói cước theo quốc gia

Tóm tắt: hệ thống lấy các gói eSIM của quốc gia khách đã chọn, hiển thị thông tin gói và lưu lại mã gói để tạo đơn.

API Danh sách gói cước (POST /api/partner/getPackages) cho phép lọc theo:

• columnFilters.country: mã quốc gia, ví dụ "cn".
• columnFilters.region_type: ALL, LOCAL hoặc MUL.
• language_code: ngôn ngữ dữ liệu trả về, ví dụ "en" hoặc "vi".

Mỗi gói trả về các thông tin để hiển thị cho khách, gồm:

• Tên gói (name), dung lượng (data), thời hạn (validity) và giá (price).
• Gói có phát hotspot không (hotspot), có kèm số điện thoại không (phone_number), có nạp thêm dung lượng được không (topup_extension).
• Kiểu mạng (network_type), danh sách quốc gia hỗ trợ (countries) và nhà mạng theo từng quốc gia (operator).

Trường quan trọng nhất là ggg_plan_id, tức mã gói cước. Hệ thống cần lưu mã này để dùng khi tạo đơn ở bước 3.

Lưu ý cho developer: countries và operator được trả về dưới dạng chuỗi JSON (JSON string), cần parse trước khi hiển thị.

Bước 3: Tạo đơn hàng

Tóm tắt: khi khách chọn gói, hệ thống gửi yêu cầu tạo đơn kèm mã gói, số lượng và địa chỉ webhook để nhận eSIM.

API Tạo đơn hàng (PUT /api/partner/createPartnerOrder) cần các trường:

Ví dụ request trên Sandbox với gói demo GIGA-DEMO:

curl -X PUT “https://sandbox-partners-api.gigago.com/api/partner/createPartnerOrder“
-H “apiKey: YOUR_API_KEY”
-H “Content-Type: application/json”
-d ‘{
“request_id”: “YOUR_UNIQUE_REQUEST_ID”,
“orders”: [ { “ggg_plan_id”: “GIGA-DEMO”, “amount”: 1 } ],
“metadata”: {
“note”: “test order”,
“url_notify”: “https://your_domain/api/esim_notify“
}
}’

Khi tạo đơn thành công, Gigago trả về request_id, mã đơn của đối tác (agency_order_id), mã đơn nội bộ (code) và trạng thái đơn, ví dụ order_status: "PROCESSING". Lúc này đơn đang được xử lý, thông tin eSIM chưa có trong response. Thông tin eSIM sẽ được gửi về webhook ở bước 4.

Lưu ý: gửi lại một request_id đã tồn tại sẽ bị từ chối. Hệ thống của đối tác nên tạo request_id duy nhất cho mỗi đơn và lưu lại để tra cứu về sau.

Bước 4: Nhận eSIM qua webhook url_notify

Tóm tắt: khi đơn được xử lý xong, Gigago tự động gửi thông tin eSIM về địa chỉ webhook mà đối tác khai báo ở bước 3.

url_notify là endpoint do đối tác tự xây dựng, không phải endpoint của Gigago. Khi đơn hoàn tất, Gigago gửi một request POST tới địa chỉ này, kèm chi tiết eSIM và metadata của đơn.

Dữ liệu Gigago gửi về gồm:

• result: tổng giá trị đơn (total_price), chi tiết eSIM (order_detail) và kênh mua hàng (website).
• extra:request_id, agency_order_id, mã đơn nội bộ (code), ghi chú và trạng thái đơn. Hệ thống dùng request_id để ghép thông tin eSIM với đúng đơn của khách.

Trường order_detail là một chuỗi JSON chứa thông tin của từng eSIM:

Từ dữ liệu này, đối tác giao eSIM cho khách, thường bằng mã QR hoặc chuỗi LPA kèm hướng dẫn cài đặt. Sự khác nhau giữa QR và LPA được giải thích trong bài “QR code và LPA: hai cách nhận eSIM qua API” (link: bài 6).

Bước 5: Tra cứu chi tiết đơn bằng request_id

Tóm tắt: khi cần kiểm tra lại trạng thái đơn hoặc lấy lại thông tin eSIM, hệ thống gọi API Chi tiết đơn hàng với request_id đã dùng khi tạo đơn.

API Chi tiết đơn hàng (POST /api/partner/getOrderDetailAgency) nhận columnFilters.request_id và trả về thông tin eSIM của đơn, gồm ICCID, gói cước, dung lượng, thời hạn, giá, qr_code, short_link và trạng thái.

Nếu không tìm thấy dữ liệu, API trả về message: "failed" và result: null.

Kiểm tra số dư tài khoản agency

API Kiểm tra số dư (GET /api/partner/getBalance) trả về số dư tài khoản agency (result) và đơn vị tiền tệ (currency, ví dụ VND). Đối tác có thể gọi API này bất kỳ lúc nào để theo dõi số dư.

Test toàn bộ luồng trên Sandbox với GIGA-DEMO

Đối tác có thể chạy thử toàn bộ 5 bước trên môi trường Sandbox mà không phát sinh giao dịch hay chi phí thật. Gói giả lập GIGA-DEMO (ggg_plan_id: GIGA-DEMO) luôn có hàng trên Sandbox, dùng để tạo đơn test và kiểm tra webhook nhận eSIM. Hướng dẫn chi tiết có trong 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).

Những lỗi thường gặp khi tích hợp

• Trùng request_id: request bị từ chối. Mỗi đơn cần một request_id duy nhất.
• Quên parse chuỗi JSON:order_detail, countries và operator là chuỗi JSON, không phải object. Hệ thống cần parse trước khi đọc.
• url_notify không nhận được request: địa chỉ webhook phải là endpoint mà hệ thống Gigago gửi tới được. Trong lúc chờ khắc phục, đối tác vẫn tra cứu được thông tin eSIM bằng API Chi tiết đơn hàng.
• Dùng nhầm apiKey giữa hai môi trường: key Sandbox và key Production tách biệt, không dùng chung.
• Để apiKey ở frontend: apiKey phải nằm ở phía server, không đưa vào code website hay ứng dụng (link: bài 5).

Câu hỏi thường gặp