Tài liệu API

Đăng ký quyền truy cập API

1. Nhờ bộ phận hỗ trợ mở tài khoản cho bạn.
2. Gửi cho bộ phận hỗ trợ các dịch vụ bạn cần, tài khoản của bạn và IP đầu ra của máy chủ.
3. Sau đó chúng tôi cấp khóa API và tài liệu tích hợp đầy đủ. Khóa có hiệu lực từ 1–730 ngày, và mỗi khóa cho phép tối đa 32 IP đầu ra.

Quy ước cơ bản

Xác thực

Gửi Authorization: Bearer <khóa API> trong mọi yêu cầu

User-Agent

Bắt buộc. Yêu cầu thiếu User-Agent sẽ bị Cloudflare chặn (error 1010)

Định dạng

Yêu cầu và phản hồi đều là JSON mã hóa UTF-8, trừ khi tải tệp lên

Thời gian

Dấu thời gian Unix theo UTC, tính bằng mili giây

Số tiền

Tối đa tám chữ số thập phân. Hãy dùng kiểu số thập phân và không làm tròn thành hai chữ số

Quy trình tích hợp

1. Lấy danh sách dịch vụ và kiểm tra số dư. Lưu lại productId bạn cần.
2. Đọc tuyên bố sử dụng dữ liệu và chấp nhận nếu bạn chưa làm.
3. Tải tệp số điện thoại lên và lưu lại fileId được trả về.
4. Nhận báo giá bằng productId và fileId. Kiểm tra số lượng, đơn giá và tổng tiền.
5. Tạo và lưu một khóa idempotency, sau đó đặt đơn. Bước này sẽ trừ tiền trong số dư của bạn.
6. Thiết lập webhook để nhận thông báo thay đổi trạng thái đơn, đồng thời đối soát bằng updatedSince mỗi 5–10 phút để không bỏ sót.
7. Khi đơn hoàn tất, lấy danh sách tệp kết quả, tải về từng tệp và kiểm tra sha256. Tải cả các tệp không thành công.

Ví dụ curl

Thay các phần giữ chỗ bằng giá trị thật. Tham số đầy đủ cho báo giá và đặt đơn có trong tài liệu tích hợp bạn nhận được khi được cấp quyền truy cập.

1. Đặt khóa và lấy danh sách dịch vụ

   Sao chép

   export CHECKIM_TOKEN='thay bằng khóa API do bộ phận hỗ trợ cấp'
   export CHECKIM_BASE='https://api.checkim.ai/openapi/v1'
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/products"

2. Tải tệp số điện thoại lên

   Sao chép

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -F 'file=@./numbers.csv;type=text/csv' \
     "$CHECKIM_BASE/files"

3. Nhận báo giá

   Sao chép

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"productId":"<productId>","name":"batch-001","fileId":"<fileId>"}' \
     "$CHECKIM_BASE/orders/check"

4. Đặt đơn

   Sao chép

   # Bước này trừ tiền trong số dư. Giữ nguyên khóa và nội dung yêu cầu khi thử lại.
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: partner-request-001' \
     -d '{"quoteId":"<quoteId>","clientOrderId":"partner-batch-001"}' \
     "$CHECKIM_BASE/orders"

5. Xem đơn hàng, hoặc đối soát theo thời gian thay đổi

   Sao chép

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     "$CHECKIM_BASE/orders?updatedSince=<UTC ms>&size=100"

6. Liệt kê, tải kết quả và kiểm tra sha256

   Sao chép

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>/results"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" -o result.csv \
     "$CHECKIM_BASE/orders/<orderId>/results/<fileId>/download"
   shasum -a 256 result.csv

Danh sách endpoint

Liệt kê và đối soát đơn hàng

• Đơn hàng được liệt kê từ mới đến cũ. Khi trang có nextCursor, hãy gửi lại nó dưới dạng cursor để lấy trang kế tiếp; phân trang bằng con trỏ không bỏ sót hay lặp lại đơn nào dù có đơn mới.
• Lọc theo status và thời gian tạo (createdFrom, createdTo, mili giây UTC), hoặc tra cứu một đơn bằng clientOrderId.
• updatedSince chỉ trả về các đơn có trạng thái thay đổi sau thời điểm đó, theo thứ tự thay đổi cũ nhất trước. Lấy dữ liệu định kỳ bằng tham số này để không mất trạng thái dù bỏ lỡ webhook.

Tải kết quả

• Mỗi tệp trong danh sách kết quả đều có sha256. ETag khi tải về cũng là giá trị đó, hãy đối chiếu sau khi tải.
• Yêu cầu Range giúp tải tiếp. Trước tiên hãy kiểm tra sha256 không đổi; nếu đã đổi nghĩa là tệp được tạo lại và cần tải lại toàn bộ.
• Khi đã có tệp đầy đủ, hãy gửi If-None-Match: tệp không đổi sẽ trả về 304 không có nội dung.
• Đơn lớn có giao theo đợt sẽ liệt kê các đợt đã xong khi vẫn đang chạy; tệp cuối cùng sau khi hoàn tất là bản chính thức.
• Với các dịch vụ có ảnh đại diện (kiểm tra mở rộng hoặc kiểm tra giới tính và độ tuổi của Telegram và WhatsApp), cột avatar trong CSV kết quả chứa liên kết ảnh có chữ ký, có thể truy cập trực tiếp bằng GET trong thời gian lưu kết quả (không gửi kèm header Authorization; hỗ trợ If-None-Match).

Webhook

• Khi trạng thái của đơn đặt qua API thay đổi, chúng tôi gửi một sự kiện bằng POST tới URL HTTPS của bạn. Cần quyền webhook:manage.
• Mỗi sự kiện có header CheckIM-Signature (t=dấu thời gian,v1=chữ ký). Hãy xác minh bằng HMAC-SHA256 của "t.nội dung yêu cầu gốc" với khóa ký của bạn.
• Mọi phản hồi 2xx được coi là đã nhận; nếu lỗi sẽ thử lại 9 lần trong khoảng 2 ngày. Bạn có thể nhận một sự kiện nhiều lần, hãy loại trùng theo id.
• Yêu cầu đến từ IP đầu ra cố định 34.21.195.36, bạn có thể chỉ cho phép địa chỉ này.

Trạng thái đơn hàng

Giới hạn và lưu ý

• Mặc định, tối đa 1.200 yêu cầu mỗi phút cho mỗi IP đầu ra, 240 cho mỗi tài khoản và 120 cho mỗi khóa. Các header RateLimit-Limit, RateLimit-Remaining và RateLimit-Reset cho biết còn bao nhiêu lượt trong phút này.
• Báo giá và tải lên chạy chậm, nên mỗi tài khoản chỉ được chạy đồng thời tối đa 3 yêu cầu loại này. Vượt quá sẽ nhận 429 TOO_MANY_CONCURRENT_REQUESTS.
• Khi nhận 429 hoặc 503, hãy chờ đủ số giây trong Retry-After rồi gửi lại đúng yêu cầu đó.
• Không có môi trường thử nghiệm. Mọi đơn hàng đều bị tính phí thật.
• Truy vấn bị quá thời gian chờ không có nghĩa là đặt đơn thất bại. Hãy tra cứu đơn hàng bằng orderId hoặc clientOrderId trước khi đặt lại.

Lỗi thường gặp

Lỗi gồm code, requestId, message và detail.field (tùy chọn). Hãy xử lý theo code; message trả về một trong 9 ngôn ngữ theo Accept-Language và chỉ để hiển thị.