Bắt đầu

Quickstart

Hướng dẫn tối thiểu để có request đầu tiên. Bạn cần tài khoản partner đã được kích hoạt và một pool/eSIM đã cấu hình.

1. Lấy API key

Đăng nhập portal partner, vào API keys để xem prefix hoặc rotate key. Raw key chỉ hiển thị một lần khi tạo/rotate. Lưu key vào biến môi trường phía server:

.env

bash

KOVITEL_API_URL=https://api.kovitel.com/api/v1
KOVITEL_API_KEY=kov_live_…

2. Kiểm tra pool và inventory

Xác nhận tài khoản đã có pool hoạt động và eSIM AVAILABLE trước khi allocate.

Inventory

bash

curl -H "x-api-key: $KOVITEL_API_KEY" \
  "https://api.kovitel.com/api/v1/sim/inventory?status=AVAILABLE&limit=5"

3. Allocate eSIM

Gán eSIM vào thiết bị. Nếu bỏ iccid, hệ thống chọn eSIM AVAILABLE lâu nhất trong pool đang hoạt động và khóa row để tránh cấp trùng.

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",
    "iccid": "8984048000000000001"
  }'

4. Đổi trạng thái và poll job

Các action ACTIVATE, SUSPEND, RESUME, RELEASE trả về 202 cùng jobId. Worker xử lý nền; poll job hoặc nhận webhook.

Suspend

bash

curl -X PUT \
  "https://api.kovitel.com/api/v1/sim/8984048000000000001/status" \
  -H "x-api-key: $KOVITEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "action": "SUSPEND" }'

# 202 Accepted
# { "jobId": "8f3c2d1a-…", "status": "PENDING" }

Poll job

bash

curl -H "x-api-key: $KOVITEL_API_KEY" \
  "https://api.kovitel.com/api/v1/jobs/8f3c2d1a-…"

# { "status": "COMPLETED", "result": { "status": "SUSPENDED" } }

5. Nhận webhook

Cấu hình URL trong portal, xác minh HMAC-SHA256 trên raw body và phản hồi 2xx. Xem hướng dẫn webhook để biết payload và retry policy.

Biến môi trường gợi ý

Biến	Ý nghĩa
KOVITEL_API_URL	Base URL API, kết thúc bằng /api/v1
KOVITEL_API_KEY	API key partner, chỉ lưu phía server
KOVITEL_WEBHOOK_SECRET	Secret để xác minh chữ ký webhook

Vòng đời eSIM API reference