Перед надсиланням
Використовуйте номер відправника, який маєте право вказувати, і надсилайте факс одержувачу, який на нього очікує. Цей запит створює реальне передавання, за яке може стягуватися плата. Для найбільш передбачуваного визначення сторінок використовуйте підготовлений документ PDF або TIFF. Відповідь про додавання до черги підтверджує прийняття, а не доставлення.
Використовуйте активований обліковий запис MultiTEL API. Для облікового запису з паролем передавайте облікові дані HTTP Basic, а для облікового запису з токеном — токен Bearer. Права доступу облікового запису та обмеження за IP залишаються чинними. Не використовуйте внутрішні облікові дані фонового виконавця.
Завантажте документ
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| Поле | Обов’язкове | Значення |
|---|---|---|
from_number | Так | Номер відправника, який ви маєте право використовувати. Використовуйте міжнародний формат, що починається з + та коду країни. |
to_number | Так | Номер факсу одержувача в міжнародному форматі. |
fax_file | Так, для запитів із кількох частин | Документ, що завантажується. Дозвольте curl встановити Content-Type і роздільник частин для запиту з кількох частин. |
webhook_url | Ні | Необов’язкова URL-адреса для зворотних сповіщень через HTTP або HTTPS; бажано використовувати HTTPS. Вміст зворотних сповіщень і гарантії їх доставлення ще переглядаються: періодично опитуйте fax_status відповідно до задокументованого процесу перевірки стану. |
Також приймається JSON із Content-Type: application/json, тими самими полями номерів і необов’язковим webhook_url, а також file_name та file_b64. Поле file_b64 містить байти документа, закодовані із суворим дотриманням формату Base64, без префікса data:. Коректне поле fax_file у запиті з кількох частин має пріоритет. Цей API не призначений для отримання файлів за URL-адресою.
Обмеження документів і подань
Застосунок приймає щонайбільше 15,728,640 декодованих байтів документа (15 MiB) з розширеннями pdf, tif, tiff, jpg, jpeg, png, doc, docx або txt. Дозволене розширення не гарантує, що сервіс зможе підрахувати або перетворити сторінки. Інфраструктурні обмеження розміру запитів можуть бути нижчими, а Base64 збільшує розмір запиту.
Наразі застосунок дозволяє для кожного облікового запису одне завдання в черзі або в процесі надсилання тому самому одержувачу, щонайбільше п’ять подань цьому одержувачу за попередню годину та щонайбільше 50 подань загалом за попередню годину. У відповіді про обмеження частоти використовується код API 429. Зачекайте перед повторною спробою; не намагайтеся обійти обмеження.
Збережіть ідентифікатор завдання
Перевіряйте і результат HTTP, і поле status.code у JSON. Повідомлення про помилки у JSON можуть надходити з HTTP 200. Успішна відповідь JSON містить status і response; у прикладах використано вигадані дані.
{
"status": {
"code": 200,
"msg": "Fax queued"
},
"response": {
"job_id": "0123456789abcdef0123456789abcdef"
}
}Періодично опитуйте fax_status за допомогою response.job_id. Якщо відповідь на запит надсилання втрачено, перевірте вихідні повідомлення на порталі, перш ніж надсилати знову: повторні запити можуть створювати окремі передавання. Цей обробник не надає клієнту параметра ідемпотентності.
Помилки та перевірки балансу
Коди API включають 400, якщо бракує полів, URL-адреса для зворотних сповіщень некоректна, документ відхилено або не вдалося визначити сторінки; 401 за відсутності автентифікації; 402, коли попередньо оцінена вартість факсу разом з оцінками вартості факсів у черзі або в процесі надсилання перевищує доступний баланс облікового запису; 429 у разі обмеження частоти; та 500 у разі збою підготовки документа до надсилання. Конкретну причину дивіться в status.msg.
Перед передаванням у черзі фіксується попередня оцінка вартості. Не сприймайте прийняття, перевірку балансу чи цю оцінку як підтвердження здійсненого списання коштів. Остаточні відомості про тарифікацію та зворотні сповіщення ще потребують перевірки.