Hướng dẫn

Gói data Dcar

Mua gói data Dcar cho eSIM đang hoạt động. Giá trả về là giá bán cho khách hàng; đơn mua được xử lý bất đồng bộ qua job queue.

Catalog

Mã gói	Data/ngày	Chu kỳ	Giá bán
DCAR100	2GB/ngày	30 ngày	200.000đ
DCAR125	5GB/ngày	30 ngày	250.000đ
DCAR150	7GB/ngày	30 ngày	300.000đ
DCAR200	10GB/ngày	30 ngày	400.000đ

Lấy catalog

GET /packages trả về các gói đang bán, kèm dailyQuotaMB, durationDays và salePriceVnd.

Catalog

bash

curl -H "x-api-key: $KOVITEL_API_KEY" \
  "https://api-sandbox.kovitel.com/api/v1/packages"

Mua gói

SIM phải ở trạng thái ACTIVE. API trả 202 cùng orderId và jobId. Dùng header idempotency-key để tránh tạo trùng đơn khi retry.

Purchase

bash

curl -X POST \
  "https://api-sandbox.kovitel.com/api/v1/sim/8984048000000000001/packages" \
  -H "x-api-key: $KOVITEL_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: order-2026-001" \
  -d '{
    "packageCode": "DCAR150"
  }'

# 202 Accepted
{
  "orderId": "…",
  "jobId": "…",
  "packageCode": "DCAR150",
  "status": "PENDING",
  "totalPriceVnd": 300000
}

Theo dõi job

Job hoàn tất sẽ tạo một PackageGrant trên SIM. Poll job hoặc chờ webhook PACKAGE_PURCHASED.

Job

bash

curl -H "x-api-key: $KOVITEL_API_KEY" \
  "https://api-sandbox.kovitel.com/api/v1/jobs/<jobId>"

# COMPLETED
{
  "status": "COMPLETED",
  "result": {
    "orderId": "…",
    "packageCode": "DCAR150",
    "status": "COMPLETED",
    "dailyQuotaMB": 7168,
    "expiresAt": "2026-12-09T…",
    "salePriceVnd": 300000
  }
}

Gói đang active trên SIM

Active packages

bash

curl -H "x-api-key: $KOVITEL_API_KEY" \
  "https://api-sandbox.kovitel.com/api/v1/sim/8984048000000000001/packages"

Webhook

PACKAGE_PURCHASED — mua gói thành công, kèm orderId, packageCode, expiresAt.
PACKAGE_FAILED — mua gói thất bại sau retry.

Xác minh x-kovitel-signature trên raw body như hướng dẫn webhook.

Sandbox

Sandbox dùng mock telco, không phát sinh cước. Catalog có 4 gói Dcar. ICCID kết thúc bằng 8 mô phỏng số dư không đủ; kết thúc bằng 9 mô phỏng SIM không đủ điều kiện. Các ICCID khác mua thành công.

API sandbox dùng cùng contract; chỉ khác base URL và API key test. Sau khi hoàn tất test, chuyển sang production chỉ cần đổi base URL và key.

Mở dashboard gói data API reference