Đặt đơn hàng
Một đơn hàng chạy một trình kiểm tra trên một danh sách. Các bước giống nhau cho mọi trình kiểm tra.
1. Chọn trình kiểm tra
GET /checkers liệt kê những gì tài khoản của bạn có thể đặt, theo giá của bạn. Mỗi trình kiểm tra có một id, ví dụ whatsapp_status_detection, và nhận số điện thoại, email hoặc tên người dùng. Xem Trình kiểm tra.
curl "https://api.talismanleads.io/v1/checkers" \
-H "Authorization: Bearer tl_live_your_key_here"2. Gửi danh sách
Đặt tối đa 100.000 mục và 4 MB trong yêu cầu dưới dạng entries. Với danh sách lớn hơn, hãy yêu cầu POST /uploads cấp một liên kết, gửi tệp đến liên kết đó bằng PUT, rồi dùng upload_id của nó. Liên kết có hiệu lực trong 2 giờ. Đừng gửi khóa API của bạn đến liên kết đó.
- Tệp là
.txtvới mỗi dòng một mục, tối đa 200 MB và 10.000.000 mục. - Viết số điện thoại kèm mã quốc gia, ví dụ
+14155550142. - Số điện thoại trong một tệp nên thuộc một quốc gia: ít nhất 90% trong số đó. Hãy tách danh sách lẫn lộn thành mỗi quốc gia một tệp.
- Một dòng không hợp lệ sẽ khiến toàn bộ danh sách bị từ chối, và phản hồi sẽ hiển thị ví dụ.
- Tệp đã tải lên chờ đơn hàng trong 24 giờ, sau đó bị xóa.
- Bạn có thể có 20 tệp hoặc 100 MB đang chờ cùng lúc, bất kể dùng bao nhiêu khóa API, và thực hiện 500 lần tải lên mỗi ngày. Khi chưa đạt các mức đó, bạn có thể thêm một tệp với kích thước bất kỳ được phép.
Yêu cầu liên kết
curl -X POST "https://api.talismanleads.io/v1/uploads" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"file_name":"list.txt","size_bytes":1048576}'Gửi tệp đến liên kết
UPLOAD_URL="PASTE_upload_url_FROM_THE_ANSWER_ABOVE"
curl --upload-file list.txt "$UPLOAD_URL" \
-H "Content-Type: text/plain" \
-w "%{http_code}\n"3. Xem giá
POST /estimates đếm các mục và tính giá, không tính phí. billed_entries có thể lớn hơn entries, vì mỗi tệp được tính phí ít nhất 2.000 mục.
curl -X POST "https://api.talismanleads.io/v1/estimates" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'4. Đặt đơn hàng
POST /orders trừ tiền vào số dư của bạn và đưa công việc vào hàng đợi. Hãy gửi Idempotency-Key để việc thử lại không thể tính phí bạn hai lần: xem Thử lại an toàn. Để chắc chắn về giá, hãy gửi expected_charge, và đơn hàng sẽ bị từ chối với price_changed nếu chi phí khác đi dù chỉ một chút. Hãy chờ tối đa 5 phút cho phản hồi, vì đọc danh sách lớn cần thời gian.
curl -X POST "https://api.talismanleads.io/v1/orders" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Idempotency-Key: crm-export-2026-11-05" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'5. Theo dõi trạng thái
Gọi GET /orders/{id} cách nhau từ 30 giây trở lên. Tệp lớn được chia thành nhiều phần ở phía sau, nhưng một đơn hàng chỉ có một trạng thái và một tổng.
queued- Đang chờ bắt đầu.
processing- Đang chạy.
completed- Đã kết thúc, mọi phần đều xong.
partially_completed- Đã kết thúc, một số phần thất bại. Các phần đó được hoàn tiền: `refunded` cho biết số tiền đã trả lại.
failed- Không phần nào có thể thực hiện được. Khoản phí được hoàn tiền: `refunded` cho biết số tiền đã trả lại.
Có thể có thêm trạng thái mới, vì vậy hãy coi trạng thái bạn không biết là vẫn đang chạy.
curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f" \
-H "Authorization: Bearer tl_live_your_key_here"6. Lấy kết quả
GET /orders/{id}/results cung cấp một liên kết tải xuống cho mỗi phần, có hiệu lực trong 15 phút. Bạn có thể yêu cầu liên kết mới bất cứ lúc nào: kết quả được lưu giữ. Tệp thường là một zip chứa all.csv, một bảng tính và các danh sách văn bản, hoặc một CSV duy nhất. Các cột có thể được thêm vào, vì vậy hãy đọc theo tên thay vì theo vị trí. Đừng gửi khóa API của bạn đến các liên kết này.
curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f/results" \
-H "Authorization: Bearer tl_live_your_key_here"Tính phí và hoàn tiền
charge là chi phí của đơn hàng khi bạn đặt, và refunded là phần đã được trả lại. Phần thất bại được hoàn tiền toàn bộ, và phần mà nhà cung cấp đếm thiếu được trả lại khoản chênh lệch, xuống đến mức tối thiểu mà phần đó bị tính phí. Cả hai đều diễn ra tự động.
Cùng một danh sách trên cùng một trình kiểm tra trong vòng khoảng một ngày, với khóa idempotency mới, sẽ bị tính phí lại như một đơn hàng mới, và có thể trả về kết quả trước đó của bạn thay vì một lượt kiểm tra mới.
Đơn hàng từ nơi khác
Các đơn hàng bạn đặt trên trang web cũng được liệt kê. Đơn hàng API xuất hiện trong Tác vụ của tôi trên trang web với huy hiệu API, và không gửi gì đến Telegram trừ khi bạn yêu cầu trên Telegram.