Inviare un fax | MultiTEL

Prima dell’invio

Usa un numero mittente che sei autorizzato a presentare e invia il fax a un destinatario che lo attende. Questa richiesta genera una trasmissione reale, potenzialmente a pagamento. Usa un documento PDF o TIFF già preparato per ottenere un rilevamento delle pagine il più prevedibile possibile. Una risposta di inserimento in coda conferma l’accettazione, non la consegna.

Usa un account API MultiTEL abilitato. Invia le credenziali HTTP Basic per un account con password, oppure un token Bearer per un account con token. Le autorizzazioni dell’account e le restrizioni sugli indirizzi IP continuano ad applicarsi. Non usare le credenziali interne del processo di elaborazione.

Caricare il documento

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

Campi della richiesta
Campo	Obbligatorio	Significato
`from_number`	Sì	Il numero mittente che sei autorizzato a usare. Usa il formato internazionale, iniziando con + e il prefisso del paese.
`to_number`	Sì	Il numero fax del destinatario, in formato internazionale.
`fax_file`	Sì per le richieste in più parti	Il documento caricato. Lascia che curl imposti Content-Type e il delimitatore delle parti per la richiesta in più parti.
`webhook_url`	No	URL facoltativo per le notifiche di richiamo tramite HTTP o HTTPS; è preferibile HTTPS. Il contenuto delle notifiche e le garanzie di consegna sono ancora in fase di verifica: interroga periodicamente fax_status per seguire il flusso di controllo dello stato documentato.

È accettato anche JSON con Content-Type: application/json, gli stessi campi dei numeri e il campo facoltativo webhook_url, oltre a file_name e file_b64. file_b64 contiene i byte del documento codificati rigorosamente in Base64, senza il prefisso data:. Un campo fax_file valido in una richiesta in più parti ha la precedenza. Questa API non recupera file tramite URL.

Limiti per i documenti e le richieste di invio

L’applicazione accetta al massimo 15,728,640 byte di documento decodificati (15 MiB), con estensioni pdf, tif, tiff, jpg, jpeg, png, doc, docx o txt. Un’estensione consentita non garantisce che il servizio riesca a contare o convertire le pagine. I limiti dell’infrastruttura per le richieste possono essere inferiori e Base64 aumenta le dimensioni della richiesta.

Per ciascun account, l’applicazione attuale consente una sola operazione in coda o in corso di invio verso la stessa destinazione, al massimo cinque richieste di invio verso tale destinazione nell’ora precedente e al massimo 50 richieste di invio complessive nell’ora precedente. Una risposta per il superamento dei limiti di frequenza usa il codice API 429. Attendi prima di riprovare; non tentare di aggirare i limiti.

Conservare l’identificativo dell’operazione

Controlla sia il risultato HTTP sia status.code nel contenuto JSON. Gli errori JSON possono essere restituiti con HTTP 200. Una risposta JSON riuscita contiene status e response; gli esempi usano dati fittizi.

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

Interroga periodicamente fax_status usando response.job_id. Se la risposta all’invio va persa, controlla la posta in uscita del portale prima di inviare di nuovo: le richieste ripetute possono generare trasmissioni distinte. Questo gestore non espone alcun parametro di idempotenza per il client.

Errori e controlli del saldo

I codici API includono 400 per campi mancanti, URL di richiamo non valido, documento rifiutato o errore nel rilevamento delle pagine; 401 per autenticazione mancante; 402 quando il costo stimato del fax, sommato alle stime delle operazioni in coda o in corso di invio, supera il saldo disponibile dell’account; 429 per i limiti di frequenza; e 500 per un errore nella preparazione della trasmissione. Leggi status.msg per conoscere il motivo specifico.

La coda registra un costo stimato prima della trasmissione. Non interpretare l’accettazione, il controllo del saldo o questa stima come conferma di un addebito effettuato. I dettagli definitivi della fatturazione e delle notifiche di richiamo restano soggetti a verifica.