Ví dụ cURL / SDK

Mọi ví dụ đều dùng base URL công khai:

https://api.zelnum.com/api/v1

Thay YOUR_KEY_HERE bằng key từ Xác thực, và lấy slug sản phẩm từ Sản phẩm hàng loạt.

Gửi một mảng

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
        "product": "YOUR_PRODUCT_SLUG",
        "country": "CN",
        "phones": ["+8613800138000", "+8613800138001"]
      }'

Phản hồi cung cấp cho bạn một task token và số tiền đã trừ trước:

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "summary": { "total": 5000, "cost_deducted": 0.500000 }
}

Tải lên một file

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@numbers.txt"

numbers.txt chứa mỗi dòng một số, tối đa 50 MB. Lưu ý dùng -F, không phải -d: endpoint này nhận multipart/form-data.

Thăm dò cho đến khi hoàn tất

TOKEN=xKj9aP3qLm7v

while true; do
  status=$(curl -s "https://api.zelnum.com/api/v1/tasks/$TOKEN" \
    -H "X-API-Key: YOUR_KEY_HERE")

  printf '%s\n' "$status" | jq '{status, progress, valid, invalid, unknown}'

  case "$(printf '%s' "$status" | jq -r .status)" in
    completed|failed) break ;;
  esac

  sleep 4
done

Bốn giây giữa các lần thăm dò là khoảng thời gian hợp lý cho tác vụ ở bất kỳ quy mô nào; trang tác vụ báo progress dưới dạng phần trăm.

Tải kết quả về

curl -s "https://api.zelnum.com/api/v1/tasks/$TOKEN/result" \
  -H "X-API-Key: YOUR_KEY_HERE" | jq -r .download_url

download_url có giới hạn thời gian — hãy lấy trước expires_at, nếu không file sẽ mất. Sau đó:

curl -L -H "X-API-Key: YOUR_KEY_HERE" \
  "https://api.zelnum.com/api/v1/tasks/$TOKEN/download" -o results.csv

Một script, từ đầu đến cuối

#!/usr/bin/env bash
set -euo pipefail

API="https://api.zelnum.com/api/v1"
KEY="YOUR_KEY_HERE"
SLUG="YOUR_PRODUCT_SLUG"

task=$(curl -s -X POST "$API/detect" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"product\":\"$SLUG\",\"country\":\"CN\",\"phones\":[\"+8613800138000\"]}" \
  | jq -r .task_id)

echo "task $task submitted"

until [ "$(curl -s "$API/tasks/$task" -H "X-API-Key: $KEY" | jq -r .status)" = "completed" ]; do
  sleep 4
done

url=$(curl -s "$API/tasks/$task/result" -H "X-API-Key: $KEY" | jq -r .download_url)
curl -L "$url" -o results.csv

echo "wrote results.csv"

Trạng thái tác vụ — mọi trường mà lần thăm dò trả về
Tải kết quả — quy tắc lưu giữ và hết hạn
Định dạng phản hồi — các quy ước dùng chung