Před odesláním
Použijte číslo odesílatele, které jste oprávněni uvádět, a fax odešlete příjemci, který jej očekává. Tento požadavek vytvoří skutečný přenos, který může být zpoplatněn. Pro co nejpředvídatelnější rozpoznání stránek použijte připravený dokument ve formátu PDF nebo TIFF. Odpověď o zařazení do fronty potvrzuje přijetí, nikoli doručení.
Použijte aktivovaný účet pro API MultiTEL. U účtu s heslem odešlete přihlašovací údaje pro HTTP Basic, u účtu s tokenem pak token typu Bearer. Oprávnění účtu a omezení podle IP adres platí i nadále. Nepoužívejte interní přihlašovací údaje pracovních procesů.
Nahrání dokumentu
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| Pole | Povinné | Význam |
|---|---|---|
from_number | Ano | Číslo odesílatele, které jste oprávněni používat. Použijte mezinárodní formát začínající znakem + a předvolbou země. |
to_number | Ano | Faxové číslo příjemce v mezinárodním formátu. |
fax_file | Ano pro vícedílný požadavek | Nahrávaný dokument. Nastavení hlavičky Content-Type a oddělovače částí vícedílného požadavku ponechte nástroji curl. |
webhook_url | Ne | Volitelná adresa URL pro zpětné volání přes HTTP nebo HTTPS; doporučuje se HTTPS. Obsah zpětného volání a záruky jeho doručení se stále prověřují: stav sledujte pravidelnými dotazy na fax_status podle zdokumentovaného postupu. |
Přijímá se také formát JSON s hlavičkou Content-Type: application/json, stejnými poli pro telefonní čísla a volitelným polem webhook_url, navíc s poli file_name a file_b64. Pole file_b64 obsahuje bajty dokumentu zakódované striktně podle Base64, bez předpony data:. Platné pole fax_file ve vícedílném požadavku má přednost. Toto API neslouží k načítání souborů z adres URL.
Limity dokumentů a odesílání
Aplikace přijímá dokumenty o velikosti nejvýše 15,728,640 bajtů po dekódování (15 MiB) s příponami pdf, tif, tiff, jpg, jpeg, png, doc, docx nebo txt. Povolená přípona nezaručuje, že služba dokáže spočítat nebo převést stránky. Limity velikosti požadavků na úrovni infrastruktury mohou být nižší a kódování Base64 velikost požadavku zvětšuje.
Pro každý účet současná aplikace povoluje jednu úlohu ve frontě nebo právě odesílanou na stejné cílové číslo, nejvýše pět požadavků na odeslání na toto číslo za předchozí hodinu a nejvýše 50 požadavků na odeslání celkem za předchozí hodinu. Odpověď při překročení limitu četnosti používá kód API 429. Před dalším pokusem vyčkejte; nepokoušejte se limity obcházet.
Uschování ID úlohy
Zkontrolujte výsledek HTTP i hodnotu status.code v odpovědi JSON. Chyby ve formátu JSON mohou přijít se stavem HTTP 200. Úspěšná odpověď ve formátu JSON obsahuje status a response; příklady používají smyšlené údaje.
{
"status": {
"code": 200,
"msg": "Fax queued"
},
"response": {
"job_id": "0123456789abcdef0123456789abcdef"
}
}Pravidelně se dotazujte na fax_status pomocí response.job_id. Pokud se odpověď na odeslání ztratí, před opětovným odesláním zkontrolujte odeslané faxy v portálu: opakované požadavky mohou vytvořit samostatné přenosy. Tato obslužná rutina neposkytuje klientský parametr pro zajištění idempotence.
Chyby a kontroly zůstatku
Kódy API zahrnují 400 pro chybějící pole, neplatnou adresu URL zpětného volání, odmítnutý dokument nebo selhání rozpoznání stránek; 401 pro chybějící autentizaci; 402, pokud odhadovaná cena faxu spolu s odhady cen úloh ve frontě a právě odesílaných úloh překročí dostupný zůstatek účtu; 429 pro překročení limitů četnosti; a 500 pro selhání přípravy k odeslání. Konkrétní důvod najdete v status.msg.
Fronta před přenosem zaznamená odhadovanou cenu. Přijetí požadavku, kontrolu zůstatku ani tento odhad nepovažujte za potvrzení provedeného zaúčtování. Konečné účtování a podrobnosti zpětných volání je stále nutné ověřit.