Trước khi gửi
Sử dụng số gửi mà bạn được phép hiển thị và chỉ gửi cho người nhận đang chờ fax của bạn. Yêu cầu này tạo ra một lần truyền fax thực tế và có thể phát sinh cước. Dùng tài liệu PDF hoặc TIFF đã chuẩn bị sẵn để việc xác định trang có kết quả ổn định nhất. Phản hồi cho biết fax đã vào hàng đợi chỉ xác nhận yêu cầu đã được tiếp nhận, không xác nhận đã gửi đến nơi.
Sử dụng tài khoản API MultiTEL đã được kích hoạt. Gửi thông tin xác thực HTTP Basic nếu tài khoản dùng mật khẩu, hoặc mã thông báo Bearer nếu tài khoản dùng mã thông báo. Quyền của tài khoản và các hạn chế về địa chỉ IP vẫn được áp dụng. Không sử dụng thông tin xác thực nội bộ của tiến trình xử lý nền.
Tải tài liệu lên
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--form-string from_number=+12125550123 \
--form-string to_number=+12125550124 \
--form fax_file=@./document.pdf \
https://api.multitel.net/v3/send_fax| Trường | Bắt buộc | Ý nghĩa |
|---|---|---|
from_number | Có | Số gửi mà bạn được phép sử dụng. Dùng định dạng quốc tế, bắt đầu bằng + và mã quốc gia. |
to_number | Có | Số fax đích, ở định dạng quốc tế. |
fax_file | Có, đối với yêu cầu nhiều phần | Tài liệu được tải lên. Hãy để curl tự đặt Content-Type và dấu phân cách giữa các phần cho yêu cầu nhiều phần. |
webhook_url | Không | Địa chỉ URL nhận thông báo gọi lại qua HTTP hoặc HTTPS, không bắt buộc; nên ưu tiên HTTPS. Nội dung thông báo gọi lại và các cam kết về việc chuyển thông báo vẫn đang được rà soát: hãy truy vấn định kỳ fax_status để theo dõi trạng thái theo quy trình được mô tả trong tài liệu. |
Cũng có thể gửi JSON với Content-Type: application/json, các trường số điện thoại giống như trên và trường webhook_url không bắt buộc, cùng với file_name và file_b64. file_b64 chứa các byte của tài liệu được mã hóa đúng chuẩn Base64, không có tiền tố data:. Nếu có fax_file hợp lệ trong yêu cầu nhiều phần thì trường đó được ưu tiên sử dụng. Đây không phải là API tải tệp từ URL.
Giới hạn tài liệu và số lần gửi yêu cầu
Ứng dụng chấp nhận tài liệu có dung lượng sau khi giải mã tối đa 15,728,640 byte (15 MiB), với phần mở rộng pdf, tif, tiff, jpg, jpeg, png, doc, docx hoặc txt. Phần mở rộng được cho phép không bảo đảm dịch vụ có thể đếm hoặc chuyển đổi các trang. Giới hạn yêu cầu của hạ tầng có thể thấp hơn, và Base64 làm tăng kích thước yêu cầu.
Với mỗi tài khoản, ứng dụng hiện cho phép một tác vụ đang chờ hoặc đang gửi tới cùng một đích, tối đa năm lần gửi yêu cầu tới đích đó trong một giờ vừa qua và tổng cộng tối đa 50 lần gửi yêu cầu trong một giờ vừa qua. Phản hồi khi vượt giới hạn tần suất dùng mã API 429. Hãy chờ trước khi thử lại; không tìm cách vượt qua các giới hạn.
Lưu mã tác vụ
Đọc cả kết quả HTTP và giá trị status.code trong JSON. Lỗi trong JSON có thể được trả về cùng với HTTP 200. Phản hồi JSON thành công có status và response; các ví dụ sử dụng dữ liệu hư cấu.
{
"status": {
"code": 200,
"msg": "Fax queued"
},
"response": {
"job_id": "0123456789abcdef0123456789abcdef"
}
}Truy vấn định kỳ fax_status bằng response.job_id. Nếu phản hồi gửi bị mất, hãy kiểm tra hộp fax đi trên cổng thông tin trước khi gửi lại: các yêu cầu lặp lại có thể tạo ra những lần truyền fax riêng biệt. Trình xử lý này không cung cấp tham số để phía máy khách bảo đảm các yêu cầu lặp lại chỉ được thực hiện một lần.
Lỗi và kiểm tra số dư
Các mã API bao gồm 400 khi thiếu trường, URL nhận thông báo gọi lại không hợp lệ, tài liệu bị từ chối hoặc không xác định được trang; 401 khi thiếu thông tin xác thực; 402 khi chi phí fax ước tính cộng với chi phí ước tính của các tác vụ đang chờ hoặc đang gửi vượt quá số dư khả dụng của tài khoản; 429 khi vượt giới hạn tần suất; và 500 khi xảy ra lỗi ở bước chuẩn bị dữ liệu để gửi. Đọc status.msg để biết nguyên nhân cụ thể.
Hàng đợi ghi nhận chi phí ước tính trước khi truyền fax. Không coi việc tiếp nhận yêu cầu, kiểm tra số dư hoặc khoản ước tính này là xác nhận đã thu cước. Chi tiết tính cước cuối cùng và thông báo gọi lại vẫn cần được xác minh.