Checklist tích hợp Gigago eSIM API: chuẩn bị, test Sandbox và chuyển sang Production

Đăng: 10/2026

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 thật, dựa trên tài liệu chính thức của Gigago tại api-docs.gigago.com.

Nội dung

Checklist tóm tắt

Giai đoạn	Việc cần làm
1. Chuẩn bị	Có tài khoản agency và apiKey
	Có developer làm việc được với REST API và JSON
	Có backend để lưu apiKey và gọi API
	Đã xây endpoint webhook url_notify
	Có cơ chế tạo và lưu request_id duy nhất
	Đã đọc “Quy ước chung” trong tài liệu
	Đã chuẩn bị cách giao eSIM cho khách
2. Test trên Sandbox	Test các API lấy dữ liệu (quốc gia, gói cước)
	Test tạo đơn với gói GIGA-DEMO
	Test webhook nhận eSIM
	Test tra cứu chi tiết đơn
	Test kiểm tra số dư và màn hình giao eSIM
3. Chuyển sang Production	Nhận base_url Production
	Đổi base_url và apiKey
	Dùng key Production riêng, lưu an toàn
	Thay GIGA-DEMO bằng mã gói thật
	Kiểm tra số dư tài khoản agency
	Chạy và kiểm tra đơn đầu tiên
	Theo dõi Changelog

3 giai đoạn và các bước tích hợp Gigago eSIM API từ chuẩn bị đến test sandbox và lên production

Giai đoạn 1: Chuẩn bị trước khi tích hợp

Giai đoạn chuẩn bị là bước kiểm tra tài khoản, nhân sự kỹ thuật, backend, webhook và cơ chế xử lý đơn trước khi bắt đầu gọi API.

1. Có tài khoản agency và apiKey

apiKey được cấp sẵn khi đối tác có tài khoản agency của Gigago và có thể được quản lý trong phần Profile / API Key. Doanh nghiệp chưa có tài khoản có thể đăng ký làm đối tác tại trang Đối tác Gigago.

Lưu ý: Sandbox và Production sử dụng apiKey riêng. Không dùng chung key giữa hai môi trường.

2. Có developer làm việc được với REST API và JSON

Gigago Agent eSIM API giao tiếp bằng REST + JSON qua HTTPS. Đội kỹ thuật có thể là developer nội bộ của doanh nghiệp hoặc đơn vị IT được thuê ngoài.

Developer cần có khả năng làm việc với:

REST API
JSON
HTTP method
request/response
webhook

Người quản lý dự án không nhất thiết phải trực tiếp viết code, nhưng nên nắm được các thành phần chính của luồng tích hợp để phối hợp với đội kỹ thuật.

3. Có backend để lưu apiKey và gọi API

apiKey có giá trị như mật khẩu. Nếu bị lộ, người khác có thể sử dụng key để tạo đơn và phát sinh chi phí trên tài khoản của đối tác.

Vì vậy, apiKey cần được lưu và sử dụng ở phía server, không đặt trong frontend hoặc source code mà người dùng có thể truy cập.

Trong môi trường Production, key nên được lưu bằng biến môi trường hoặc trình quản lý secret và không commit trực tiếp lên Git.

→ Xem thêm: Bảo mật apiKey khi tích hợp eSIM API

4. Đã xây endpoint webhook

url_notify.url_notify là endpoint do đối tác tự xây dựng, không phải endpoint do Gigago cung cấp.

Khi đơn hoàn tất, Gigago gửi request POST tới địa chỉ này kèm thông tin eSIM. Địa chỉ được khai báo trong trường metadata.url_notify mỗi lần tạo đơn.

5. Có cơ chế tạo và lưu `request_id` duy nhất.

Mỗi đơn hàng cần có một request_id duy nhất do hệ thống của đối tác tạo.

request_id được sử dụng xuyên suốt quá trình xử lý đơn:

Tạo đơn → nhận webhook → đối chiếu đơn → tra cứu chi tiết đơn khi cần.

Gửi lại một request_id đã tồn tại sẽ bị từ chối. Vì vậy, hệ thống nên tạo và lưu request_id cùng với đơn hàng để có thể đối chiếu về sau.

6. Đã đọc “Quy ước chung” trong tài liệu

Trước khi bắt đầu tích hợp, developer nên nắm các quy ước chung của Gigago API, bao gồm:

Request và response sử dụng JSON, UTF-8.
Request sử dụng header apiKey.
Content-Type: application/json.
Response có cấu trúc chuẩn gồm code, message, totalRecords, result và extra.
Các API có cơ chế phân trang và lọc dữ liệu.

Đây là phần kiến thức nền giúp developer hiểu cách các endpoint khác nhau trong Agent eSIM API hoạt động thống nhất.

7. Đã chuẩn bị cách giao eSIM cho khách

Sau khi nhận thông tin từ Gigago, hệ thống của đối tác cần có cách đưa eSIM đến khách hàng.

Thông tin trả về có thể bao gồm:

qr_code
short_link
iccid
thông tin gói cước
thời hạn và dung lượng

Đối tác cần xác định eSIM sẽ được giao qua kênh nào, chẳng hạn màn hình xác nhận đơn hoặc email, đồng thời chuẩn bị hướng dẫn cài đặt phù hợp.

→ Xem thêm: QR code và LPA: hai cách nhận eSIM qua API

Giai đoạn 2: Test toàn bộ luồng trên Sandbox

Sandbox là môi trường dùng để kiểm thử tích hợp Gigago API bằng dữ liệu demo, không phát sinh giao dịch hoặc chi phí thật.

Trong giai đoạn này, hệ thống dùng base_url là https://sandbox-partners-api.gigago.com cùng key Sandbox, không sử dụng key Production.

Mục tiêu của giai đoạn này không chỉ là kiểm tra từng API riêng lẻ mà là xác nhận toàn bộ luồng từ lấy gói → tạo đơn → nhận eSIM → tra cứu đơn hoạt động đúng.

1. Test các API lấy dữ liệu

Gọi Danh sách mã quốc gia (getCountryCodes) và hiển thị được danh sách cho khách.
Gọi Danh sách gói cước (getPackages) có lọc theo country, region_type và language_code.
Parse đúng các trường trả về dưới dạng chuỗi JSON, như countries và operator.
Lưu được ggg_plan_id của gói khách chọn.

ggg_plan_id là mã gói được sử dụng ở bước tạo đơn, vì vậy đây là một trường quan trọng cần kiểm tra trong quá trình tích hợp.

2. Test tạo đơn với gói GIGA-DEMO

GIGA-DEMO là gói giả lập dành cho Sandbox, được sử dụng để tạo đơn test mà không phát sinh giao dịch hoặc chi phí thật.

Tạo đơn (createPartnerOrder) với ggg_plan_id: "GIGA-DEMO". Đây là gói giả lập luôn có hàng trên Sandbox.
Nhận response thành công với trạng thái PROCESSING, lưu request_id và mã đơn trả về.
Gửi lại một request_id đã dùng và xác nhận hệ thống xử lý đúng khi request bị từ chối.

3. Test webhook và nhận eSIM

Endpoint url_notify nhận được request POST và xử lý đúng cấu trúc payload theo tài liệu.
Parse trường order_detail (chuỗi JSON) để lấy qr_code, iccid, short_link và các thông tin gói.
Ghép thông tin eSIM với đúng đơn của khách qua request_id trong phần extra.

Đây là bước quan trọng để đảm bảo eSIM nhận được từ API không bị gắn nhầm với đơn hàng khác.

4. Test tra cứu đơn

Webhook là một phần của luồng nhận eSIM, nhưng hệ thống cũng cần kiểm tra khả năng tra cứu lại đơn bằng API Chi tiết đơn hàng.

Gọi Chi tiết đơn hàng (getOrderDetailAgency) bằng request_id và đọc được thông tin eSIM.
Xử lý đủ các trạng thái eSIM: 0 Processing, 1 Delivered, 2 Recalled.
Xử lý trường hợp không có dữ liệu (message: "failed", result: null).

Việc kiểm thử cả trạng thái thành công và trường hợp không có dữ liệu giúp hệ thống tránh chỉ xử lý một response “happy path”.

5. Test số dư và giao eSIM

Gọi Kiểm tra số dư (getBalance) và hiển thị số dư cùng đơn vị tiền tệ.
Kiểm tra màn hình hoặc email giao eSIM cho khách: mã QR hiển thị đúng, có hướng dẫn cài đặt.

Đến cuối giai đoạn Sandbox, đối tác nên có thể kiểm tra được toàn bộ chuỗi:

Lấy quốc gia → lấy gói → tạo đơn GIGA-DEMO → nhận webhook → lấy thông tin eSIM → tra cứu đơn → giao eSIM.

Xem chi tiết endpoint, parameter và response của từng bước trong bài Một đơn eSIM đi qua API như thế nào?

Giai đoạn 3: Chuyển từ Sandbox sang Production

Production là môi trường bán hàng thật. Các đơn được tạo trong môi trường này là giao dịch thực tế và có thể phát sinh chi phí.

Sau khi đã kiểm thử các luồng cần thiết trên Sandbox, đối tác có thể chuẩn bị chuyển sang Production.

1. Nhận thông tin kết nối Production

Thông tin kết nối Production được Gigago cung cấp khi đối tác đăng ký làm đại lý.

Đội kỹ thuật cần có:

base_url Production
apiKey Production

2. Đổi `base_url` và `apiKey`

Khi chuyển từ Sandbox sang Production, đối tác đổi base_url và apiKey sang thông tin của môi trường Production.

Theo tài liệu, cấu trúc request và response giữ nguyên, vì vậy phần code xử lý API đã xây dựng cho Sandbox có thể được sử dụng lại.

Điểm cần thay đổi chủ yếu là thông tin kết nối của môi trường.

3. Dùng key Production riêng và lưu an toàn

Key Sandbox và key Production tách biệt hoàn toàn, không dùng chung một key cho hai môi trường.

Key Production nên được lưu trong biến môi trường hoặc trình quản lý secret của máy chủ, không commit lên Git.

Đây là bước đặc biệt quan trọng vì Production là môi trường giao dịch thật.

4. Thay `GIGA-DEMO` bằng mã gói thật

Trên Production, hệ thống dùng ggg_plan_id lấy từ API Danh sách gói cước. Từ đây mỗi đơn phát sinh giao dịch và chi phí thật.

Lưu ý: Không giữ GIGA-DEMO trong luồng tạo đơn Production.

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

Dùng API Kiểm tra số dư để theo dõi số dư tài khoản trước và trong quá trình bán.

Đây là một trong những API có thể được gọi trong quá trình vận hành để theo dõi số dư tài khoản.

6. Chạy và kiểm tra đơn Production đầu tiên

Trước khi mở bán rộng, nên chạy thử một đơn thật và kiểm tra toàn bộ luồng: tạo đơn, nhận webhook, tra cứu đơn và giao eSIM cho khách.

Đây là khuyến nghị thực hành khi triển khai, không phải yêu cầu bắt buộc được nêu trong tài liệu API.

Việc kiểm tra đơn đầu tiên giúp đội kỹ thuật xác nhận rằng những khác biệt về cấu hình Production, webhook và quy trình giao eSIM đã được xử lý trước khi hệ thống nhận nhiều đơn.

7. Theo dõi Changelog

Developer Docs của Gigago có trang Changelog để cập nhật các thay đổi của API. Đội kỹ thuật nên theo dõi trang này để cập nhật hệ thống kịp thời

Không nên chỉ kiểm tra Changelog khi hệ thống phát sinh lỗi. Theo dõi các thay đổi API định kỳ giúp đội kỹ thuật chủ động cập nhật integration.

Đăng ký làm đối tác của Gigago

Gặp lỗi khi tích hợp? Cần chuẩn bị thông tin gì để được hỗ trợ?

Khi cần Gigago hỗ trợ kiểm tra một vấn đề liên quan đến API, đối tác nên cung cấp ít nhất các thông tin sau:

Môi trường: DEV/Sandbox hoặc PROD/Production.
request_id: của đơn hoặc request gặp lỗi.
Thời gian gọi API: thời điểm request được thực hiện.

Các thông tin này giúp đội kỹ thuật xác định đúng request và môi trường cần kiểm tra.

Nếu nghi apiKey bị lộ, cần làm ngay 3 bước sau:

Reset apiKey trong Profile / API Key để key cũ mất hiệu lực.
Cập nhật key mới vào hệ thống.
Rà soát các đơn hàng phát sinh trong khoảng thời gian nghi ngờ key bị lộ.

→ Xem thêm: Bảo mật apiKey khi tích hợp eSIM API: 5 quy tắc bắt buộc.

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

Test Gigago eSIM API trên Sandbox có mất tiền không?

Không. Sandbox sử dụng dữ liệu demo để kiểm thử và không phát sinh giao dịch hoặc chi phí thật.
Gói GIGA-DEMO được sử dụng để tạo đơn test trong môi trường Sandbox.

Code viết cho Sandbox có dùng lại được cho Production không?

Có. Khi chuyển từ Sandbox sang Production, chỉ cần đổi base_url và apiKey. Cấu trúc request và response giữ nguyên.
Tuy nhiên, các cấu hình riêng của hệ thống đối tác như webhook, secret và môi trường triển khai vẫn cần được kiểm tra trước khi chạy thật.

Sandbox và Production có dùng chung apiKey không?

Không. Sandbox và Production sử dụng apiKey riêng và được tách biệt.
Khi chuyển sang Production, đối tác cần sử dụng key của môi trường Production thay cho key Sandbox.

apiKey của Gigago lấy ở đâu?

apiKey được cấp sẵn khi đối tác có tài khoản agency của Gigago. Key có thể được quản lý trong phần Profile / API Key của tài khoản.

Nghi lộ apiKey thì phải làm gì?

Reset apiKey ngay để key cũ mất hiệu lực, cập nhật key mới vào hệ thống, sau đó rà soát các đơn hàng phát sinh trong thời gian nghi lộ.

Khi nào nên chuyển sang Production?

Khi đã test xong toàn bộ luồng trên Sandbox (lấy gói, tạo đơn, nhận webhook, tra cứu đơn, giao eSIM cho khách) và đã nhận được base_url cùng apiKey của môi trường Production.