eSIM API Checklist (2026): 12 Tính năng mà một Travel eSIM API Phải có — và Cách kiểm thử từng tính năng

Câu trả lời nhanh

Một API eSIM du lịch sẵn sàng cho môi trường thực tế nên cung cấp xác thực token bảo mật, khóa idempotency để việc thử lại không bao giờ bị tính phí hai lần, báo giá giúp chốt giá, webhook có chữ ký cho mọi sự kiện eSIM, một môi trường sandbox có thể mô phỏng toàn bộ vòng đời và các lỗi của eSIM, nạp tiền, dữ liệu sử dụng, tạm dừng/khôi phục, và một danh mục sản phẩm chi tiết về vùng phủ sóng và quy định sử dụng hợp lý. Hãy kiểm tra mọi tính năng này trong sandbox trước khi bạn chính thức vận hành.

Kết nối một API eSIM với ứng dụng, nền tảng du lịch hoặc công cụ đặt chỗ của bạn không hề khó. Điều khó khăn là sau khi ra mắt, bạn mới phát hiện ra API bị tính phí hai lần khi gặp lỗi timeout, không thể thông báo cho bạn khi khách hàng hết dữ liệu, hoặc không có cách nào để kiểm tra các lỗi xảy ra.

Danh sách kiểm tra này bao gồm 12 tính năng quan trọng trong môi trường thực tế, và với mỗi tính năng, cách để kiểm tra nó trước khi bạn đăng ký. Chúng tôi sử dụng TripoSIM Partner API làm ví dụ thực tế, nhưng bạn có thể sử dụng cùng một danh sách kiểm tra này để so sánh với bất kỳ nhà cung cấp nào.

1. Xác thực token bảo mật

Những gì cần tìm kiếm: OAuth 2.0 client credentials: bạn trao đổi client ID và secret để lấy một access token có thời hạn ngắn. Các secret không bao giờ được gửi kèm trong mỗi yêu cầu.

Cách kiểm tra: yêu cầu một token, sau đó kiểm tra xem nó có hết hạn hay không. Trong TripoSIM API, POST /auth/token trả về một access token có hiệu lực trong 15 phút. Hãy đảm bảo mã của bạn tự động làm mới nó trước khi hết hạn.

2. Khóa idempotency (không tính phí hai lần)

Những gì cần tìm kiếm: một header Idempotency-Key trên mỗi đơn hàng và lần nạp tiền. Nếu yêu cầu của bạn bị timeout và bạn thử lại với cùng một khóa, API phải trả về kết quả ban đầu thay vì tạo ra một eSIM thứ hai đã thanh toán.

Cách kiểm tra: gửi cùng một đơn hàng hai lần với cùng một khóa và xác nhận bạn chỉ nhận được một đơn hàng. Sau đó, gửi cùng một khóa với một nội dung (body) khác — một API tốt sẽ từ chối nó. TripoSIM yêu cầu khóa này cho các đơn hàng và nạp tiền thực tế và trả về 409 IDEMPOTENCY_KEY_REUSED nếu một khóa bị sử dụng lại với một yêu cầu khác.

3. Báo giá giúp chốt giá

Những gì cần tìm kiếm: một cách để lấy giá và giữ mức giá đó trong một thời gian ngắn, để khách hàng của bạn trả chính xác số tiền mà bạn đã hiển thị cho họ.

Cách kiểm tra: tạo một báo giá, chờ đợi, sau đó đặt hàng với báo giá đó. Các báo giá của TripoSIM có hiệu lực trong 10 phút; một báo giá đã hết hạn sẽ trả về 409 QUOTE_EXPIRED để bạn có thể báo giá lại thay vì phải thu một mức giá bất ngờ.

4. Danh mục sản phẩm rõ ràng

Những gì cần tìm kiếm: một endpoint liệt kê mọi gói cước với giá cả, dữ liệu, thời hạn, các quốc gia phủ sóng, 5G, hỗ trợ nạp tiền — và đối với các gói không giới hạn, là giới hạn tốc độ cao hàng ngày.

Cách kiểm tra: lấy danh mục của một quốc gia và so sánh nó với trang web chính thức của nhà cung cấp. Endpoint /catalog của TripoSIM trả về JSON hoặc CSV, bao gồm các gói cước khu vực phủ sóng quốc gia đó, và thêm các trường sử dụng hợp lý (fup_daily_mb, fup_throttle_kbps) cho các gói không giới hạn. Xem [cách các giới hạn hàng ngày không giới hạn hoạt động](/blog/unlimited-esim-daily-limit-by-country-2026).

5. Giao hàng đơn hàng và QR tức thì

Những gì cần tìm kiếm: phản hồi đơn hàng (hoặc một webhook vài giây sau đó) nên bao gồm mã kích hoạt theo định dạng LPA tiêu chuẩn, ví dụ: LPA:1$smdp.example.com$ACTIVATION_CODE, để bạn có thể hiển thị mã QR hoặc liên kết cài đặt một chạm.

Cách kiểm tra: đặt một đơn hàng trong sandbox, tạo mã QR từ chuỗi LPA, và quét nó bằng camera điện thoại để kiểm tra xem định dạng có hợp lệ không.

6. Webhook có chữ ký cho mọi sự kiện

Những gì cần tìm kiếm: các thông báo đẩy cho toàn bộ vòng đời eSIM, được ký để kẻ tấn công không thể giả mạo.

TripoSIM gửi tám loại sự kiện: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted và esim.expired. Mỗi yêu cầu đều mang theo header X-TripoSIM-Signature — một mã HMAC-SHA256 của timestamp và body thô bằng cách sử dụng secret ký của bạn:

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) > 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

Cách kiểm tra: đăng ký một webhook, kích hoạt một đơn hàng, và xác minh chữ ký trong mã của bạn. Sau đó, thay đổi một byte trong body và đảm bảo rằng kiểm tra của bạn sẽ từ chối nó.

7. Sandbox mô phỏng toàn bộ vòng đời eSIM

Những gì cần tìm kiếm: các eSIM thực tế mất nhiều ngày để kích hoạt và sử dụng dữ liệu. Một sandbox tốt cho phép bạn tua nhanh quá trình này.

Ready to get connected?

Get a travel eSIM for 200+ destinations — instant QR by email, no roaming charges, with a discount applied automatically at checkout.

Browse eSIM plans

Cách kiểm tra: trong sandbox của TripoSIM, sử dụng POST /sandbox/esims/{iccid}/simulate với các hành động như activate, usage, deplete, expire hoặc reset. Mỗi bước sẽ kích hoạt webhook tương ứng, vì vậy bạn có thể kiểm tra email "dữ liệu của bạn sắp hết" chỉ trong vài phút thay vì vài ngày.

8. Mô phỏng lỗi

Những gì cần tìm kiếm: một cách để cố tình tạo ra lỗi, để bạn biết ứng dụng của mình xử lý chúng như thế nào.

Cách kiểm tra: gửi header X-Sandbox-Simulate với các chế độ như insufficient_balance, price_changed, rate_limit, provider_unavailable hoặc timeout, và kiểm tra xem ứng dụng của bạn có hiển thị thông báo rõ ràng và chỉ thử lại khi cần thiết hay không.

9. Nạp tiền trên cùng một eSIM

Những gì cần tìm kiếm: những khách hàng đã hết dữ liệu nên có thể nạp thêm mà không cần cài đặt một eSIM mới.

Cách kiểm tra: gọi POST /esims/{iccid}/topup trong sandbox (với một khóa idempotency), sau đó kiểm tra số dư dữ liệu mới. Ngoài ra, hãy kiểm tra xem gói cước nào hỗ trợ nạp tiền — danh mục sản phẩm sẽ cho bạn biết.

10. Dữ liệu sử dụng và trạng thái

Những gì cần tìm kiếm: một endpoint cho dữ liệu đã dùng, dữ liệu còn lại và ngày hết hạn, để đội ngũ hỗ trợ và ứng dụng của bạn có thể trả lời câu hỏi "tôi còn bao nhiêu dữ liệu?".

Cách kiểm tra: gọi GET /esims/{iccid}/usage sau một sự kiện sử dụng được mô phỏng. TripoSIM lưu bộ nhớ đệm (cache) dữ liệu sử dụng trong 5 phút, vì vậy hãy sử dụng webhooks (esim.usage_80, esim.depleted) để nhận cảnh báo theo thời gian thực.

11. Tạm dừng và khôi phục

Những gì cần tìm kiếm: một cách để tạm dừng một eSIM — ví dụ khi một khoản thanh toán bị tranh chấp hoặc khách hàng báo mất điện thoại — và khôi phục nó sau đó.

Cách kiểm tra: tạm dừng một eSIM trong sandbox, xác nhận webhook esim.suspended được gửi đến, sau đó khôi phục nó và xác nhận esim.resumed.

12. Giới hạn tốc độ, mã lỗi và nhật ký thay đổi rõ ràng

Những gì cần tìm kiếm: các giới hạn được tài liệu hóa, mã lỗi cho bạn biết liệu có nên thử lại hay không, và một nhật ký thay đổi (changelog) công khai để các bản cập nhật không bao giờ làm bạn bất ngờ.

Cách kiểm tra: đọc danh sách lỗi và ánh xạ mỗi mã thành "thử lại" hoặc "không thử lại" trong mã của bạn. TripoSIM cho phép 120 yêu cầu mỗi phút cho mỗi tài khoản đối tác (bạn có thể thiết lập giới hạn thấp hơn cho các API key riêng lẻ), trả về header Retry-After trong các phản hồi 429, đánh dấu mọi mã lỗi là có thể thử lại hoặc không, và công bố một endpoint changelog.

Kế hoạch triển khai đơn giản

Ngày 1: lấy khóa sandbox, xác thực, lấy danh mục sản phẩm.
Ngày 2: đặt các đơn hàng sandbox với khóa idempotency và hiển thị mã QR.
Ngày 3: thêm webhooks, chạy các trình mô phỏng vòng đời và lỗi.
Ngày 4: thêm tính năng nạp tiền và sử dụng, sau đó kiểm tra trên điện thoại thật với một eSIM thực tế.
Ngày 5: chính thức vận hành.

Hầu hết các đội ngũ kết nối trong vòng chưa đầy một tuần. Đọc [tài liệu API đầy đủ](https://docs.triposim.com) hoặc xem [hướng dẫn tích hợp API eSIM từng bước của chúng tôi](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform).

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

Một API eSIM du lịch nên bao gồm những gì?

Ít nhất phải có: xác thực token, khóa idempotency, báo giá, danh mục sản phẩm, mã QR/kích hoạt tức thì, webhook có chữ ký, sandbox với trình mô phỏng vòng đời và lỗi, nạp tiền, dữ liệu sử dụng, tạm dừng/khôi phục, cùng với các giới hạn tốc độ và mã lỗi được tài liệu hóa.

Tại sao khóa idempotency lại quan trọng đối với một API eSIM?

Mỗi đơn hàng eSIM đều tốn tiền thật. Nếu một yêu cầu bị timeout và hệ thống của bạn thử lại, một khóa idempotency sẽ đảm bảo việc thử lại trả về kết quả đầu tiên thay vì mua một eSIM thứ hai.

Làm thế nào để tôi kiểm tra một API eSIM mà không cần mua eSIM?

Hãy sử dụng sandbox. Một sandbox tốt sẽ mô phỏng việc đặt hàng, kích hoạt, sử dụng dữ liệu, hết dung lượng và hết hạn — và cho phép bạn cố tình tạo ra lỗi — mà không làm mất tiền trong ví của bạn.

Việc tích hợp API eSIM mất bao lâu?

Với một API được tài liệu hóa tốt và một sandbox đầy đủ, hầu hết các đội ngũ có thể vận hành trong vòng 3–5 ngày làm việc.

API TripoSIM có hỗ trợ cung cấp dịch vụ dưới thương hiệu riêng (white-label) không?

Có. Bạn sẽ nhận được mã kích hoạt và dữ liệu QR, vì vậy bạn có thể cung cấp eSIM ngay trong ứng dụng hoặc email của riêng bạn dưới thương hiệu của mình. Xem [chương trình API](/api-program).

Kết luận

Giá cả rất quan trọng, nhưng đối với một API eSIM, sự khác biệt thực sự sẽ lộ diện sau khi ra mắt: các lần thử lại không bao giờ bị tính phí hai lần, các webhook mà bạn có thể tin tưởng, và một sandbox cho phép bạn kiểm tra mọi thứ trước tiên. Hãy chạy danh sách kiểm tra này với bất kỳ nhà cung cấp nào trước khi bạn cam kết — và [bắt đầu với sandbox của chúng tôi](/api-program) để xem API TripoSIM Partner đạt điểm như thế nào.