Küldés előtt
Olyan feladói számot használjon, amelynek megjelenítésére jogosult, és olyan címzettnek küldjön, aki várja a faxát. Ez a kérés valódi, esetlegesen díjköteles átvitelt indít. Az oldalak lehető legkiszámíthatóbb felismeréséhez használjon előkészített PDF vagy TIFF dokumentumot. A sorba állítást jelző válasz a kérés elfogadását igazolja, nem a kézbesítést.
Használjon engedélyezett MultiTEL API-fiókot. Jelszavas fiókhoz HTTP Basic hitelesítési adatokat, tokenes fiókhoz pedig Bearer tokent küldjön. A fiókjogosultságok és az IP-korlátozások továbbra is érvényesek. Ne használja a belső háttérfeldolgozó hitelesítési adatait.
A dokumentum feltöltése
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| Mező | Kötelező | Jelentés |
|---|---|---|
from_number | Igen | Az Ön által jogosultan használt feladói szám. Használjon + jellel és országkóddal kezdődő nemzetközi formátumot. |
to_number | Igen | A címzett faxszáma nemzetközi formátumban. |
fax_file | Többrészes kérésnél igen | A feltöltött dokumentum. Bízza a curl programra a többrészes kérés Content-Type fejlécének és részelválasztójának beállítását. |
webhook_url | Nem | Nem kötelező HTTP vagy HTTPS visszahívási URL; a HTTPS használata ajánlott. A visszahívás adattartalma és kézbesítési garanciái még felülvizsgálat alatt állnak: a dokumentált állapotkövetési munkafolyamathoz rendszeresen kérdezze le a fax_status végpontot. |
JSON formátumú kérés is elfogadott a következő beállítással: Content-Type: application/json, ugyanazokkal a számmezőkkel és a nem kötelező webhook_url mezővel, továbbá a következő mezőkkel: file_name és file_b64. A file_b64 a dokumentum bájtjait tartalmazza szigorúan szabályos Base64 kódolással, data: előtag nélkül. Az érvényes többrészes fax_file elsőbbséget élvez. Ez nem fájlok URL alapján történő lekérésére szolgáló API.
Dokumentum- és beküldési korlátok
Az alkalmazás legfeljebb 15,728,640 bájtnyi dekódolt dokumentumadatot (15 MiB) fogad el, pdf, tif, tiff, jpg, jpeg, png, doc, docx vagy txt kiterjesztéssel. Az engedélyezett kiterjesztés nem garantálja, hogy a szolgáltatás meg tudja számolni vagy át tudja alakítani az oldalakat. Az infrastruktúra kérésméret-korlátai alacsonyabbak lehetnek, a Base64 pedig növeli a kérés méretét.
A jelenlegi alkalmazás fiókonként ugyanahhoz a címzetthez egy sorban álló vagy küldés alatt álló feladatot, az előző órában ugyanahhoz a címzetthez legfeljebb öt beküldést, az előző órában összesen pedig legfeljebb 50 beküldést engedélyez. A gyakorisági korlátozást jelző válasz API-kódja 429. Újrapróbálkozás előtt várjon; ne próbálja megkerülni a korlátokat.
Őrizze meg a feladatazonosítót
Ellenőrizze mind a HTTP eredményt, mind a JSON válasz status.code mezőjét. A JSON hibaválaszok HTTP 200 kóddal is érkezhetnek. A sikeres JSON válasz status és response mezőt tartalmaz; a példák kitalált adatokat használnak.
{
"status": {
"code": 200,
"msg": "Fax queued"
},
"response": {
"job_id": "0123456789abcdef0123456789abcdef"
}
}Rendszeresen kérdezze le a következő végpontot: fax_status a response.job_id használatával. Ha a küldésre adott válasz elvész, az újbóli küldés előtt ellenőrizze a portál kimenő üzeneteit: az ismételt kérések külön átviteleket hozhatnak létre. Ez a kéréskezelő nem tesz elérhetővé kliensoldali idempotenciaparamétert.
Hibák és egyenlegellenőrzések
Az API-kódok között szerepel a 400 hiányzó mezők, érvénytelen visszahívási URL, elutasított dokumentum vagy sikertelen oldalfelismerés esetén; a 401 hiányzó hitelesítés esetén; a 402, ha a fax becsült költsége a sorban álló és küldés alatt álló feladatok becsült költségeivel együtt meghaladja a fiók rendelkezésre álló egyenlegét; a 429 gyakorisági korlátozás esetén; és az 500 az átviteli előkészítés hibája esetén. A konkrét okot a status.msg mezőben olvashatja.
A várólista az átvitel előtt rögzíti a becsült költséget. Sem az elfogadást, sem az egyenlegellenőrzést, sem ezt a becslést ne tekintse a díj tényleges terhelését igazoló visszaigazolásnak. A végleges számlázás és a visszahívások részletei még ellenőrzésre várnak.