Hướng dẫn

Vòng đời eSIM

Inventory, allocation, thay đổi trạng thái và batch. Các thao tác telco chạy qua hàng đợi để tránh timeout và bảo vệ cổng Viettel.

Endpoints

Method	Path	Mô tả
GET	/pool/status	Quota còn lại, hạn pool và số eSIM theo trạng thái
GET	/sim/inventory	Danh sách eSIM, mặc định AVAILABLE
POST	/sim/allocate	Gán eSIM vào deviceId
PUT	/sim/{iccid}/status	Đổi trạng thái, trả jobId
POST	/sim/batch/status	Batch ACTIVATE/SUSPEND tối đa 500 ICCID
GET	/sim/batch/{batchJobId}	Tiến độ tổng hợp của batch
GET	/sim/{iccid}/usage	Usage gần realtime, fallback cache
GET	/jobs/{jobId}	Trạng thái và kết quả job

Allocate

Bỏ trống iccid để hệ thống chọn eSIM AVAILABLE lâu nhất trong pool đang hoạt động. Allocation dùng row lock FOR UPDATE SKIP LOCKED để tránh cấp trùng khi nhiều request đồng thời. Một device chỉ gắn một eSIM trong cùng client.

Allocate

bash

curl -X POST "https://api.kovitel.com/api/v1/sim/allocate" \
  -H "x-api-key: $KOVITEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "deviceId": "meter-hn-014" }'

Đổi trạng thái

Action	Kết quả	Telco
ACTIVATE	ACTIVE	Mở chặn 2 chiều
SUSPEND	SUSPENDED	Chặn 2 chiều
RESUME	ACTIVE	Mở chặn 2 chiều
RELEASE	RELEASED	Local (chưa gọi telco)

Nếu eSIM đã ở trạng thái đích, job hoàn tất mà không gọi telco. Request trùng action đang chạy sẽ trả cùng jobId với deduplicated: true.

Job bất đồng bộ

API trả 202 ngay. Worker gọi telco, retry khi lỗi mạng/5xx, rồi cập nhật job. Poll cho đến khi COMPLETED hoặc FAILED, hoặc dùng webhook.

Job result

json

{
  "jobId": "8f3c2d1a-…",
  "type": "SIM_SUSPEND",
  "status": "COMPLETED",
  "attempts": 1,
  "maxAttempts": 3,
  "result": {
    "iccid": "8984048000000000001",
    "status": "SUSPENDED",
    "previousStatus": "ACTIVE",
    "channel": "REVERSE",
    "changed": true
  }
}

Batch

Tối đa 500 ICCID mỗi request, không trùng. Batch tạo parent job và fan-out thành từng job con. Theo dõi qua /sim/batch/{batchJobId}.

Batch

bash

curl -X POST "https://api.kovitel.com/api/v1/sim/batch/status" \
  -H "x-api-key: $KOVITEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "iccids": ["8984048000000000001", "8984048000000000002"],
    "action": "SUSPEND"
  }'

# 202 { "batchJobId": "…", "total": 2, "message": "Processing in background" }

Usage

GET /sim/{iccid}/usage cố gắng lấy số liệu mới từ Viettel; nếu không được, trả giá trị cache gần nhất và đặt source: "CACHE".

Tiếp: Webhook →API reference →