Fax senden | MultiTEL

Vor dem Senden

Verwenden Sie eine Absendernummer, zu deren Anzeige Sie berechtigt sind, und senden Sie nur an einen Empfänger, der Ihr Fax erwartet. Diese Anfrage löst eine tatsächliche, möglicherweise kostenpflichtige Übertragung aus. Verwenden Sie für eine möglichst zuverlässige Seitenerkennung ein vorbereitetes Dokument im Format PDF oder TIFF. Eine Antwort, die die Aufnahme in die Warteschlange meldet, bestätigt die Annahme, nicht die Zustellung.

Verwenden Sie ein freigeschaltetes MultiTEL-Konto für die API. Übermitteln Sie bei einem passwortbasierten Konto Zugangsdaten für HTTP Basic oder bei einem tokenbasierten Konto ein Bearer-Token. Kontoberechtigungen und IP-Beschränkungen gelten weiterhin. Verwenden Sie keine internen Zugangsdaten der Hintergrundverarbeitung.

Dokument hochladen

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

Anfragefelder
Feld	Erforderlich	Bedeutung
`from_number`	Ja	Ihre berechtigte Absendernummer. Verwenden Sie das internationale Format mit + und Ländervorwahl am Anfang.
`to_number`	Ja	Die Faxnummer des Empfängers im internationalen Format.
`fax_file`	Ja, bei mehrteiligen Anfragen	Das hochgeladene Dokument. Lassen Sie curl den Content-Type und die Trennzeichenfolge der mehrteiligen Anfrage festlegen.
`webhook_url`	Nein	Optionale Rückruf-URL über HTTP oder HTTPS; HTTPS wird empfohlen. Die Nutzdaten der Rückrufe und die Zustellgarantien werden noch geprüft: Fragen Sie fax_status regelmäßig ab, um den dokumentierten Ablauf zur Statusprüfung zu nutzen.

JSON wird ebenfalls akzeptiert, mit Content-Type: application/json, denselben Nummernfeldern und optional webhook_url sowie file_name und file_b64. file_b64 enthält die Dokumentbytes in strikt gültiger Base64-Kodierung, ohne das Präfix data:. Ein gültiges fax_file in einer mehrteiligen Anfrage hat Vorrang. Diese API ruft keine Dateien über URLs ab.

Grenzen für Dokumente und Übermittlungen

Die Anwendung akzeptiert höchstens 15,728,640 dekodierte Dokumentbytes (15 MiB) mit den Dateiendungen pdf, tif, tiff, jpg, jpeg, png, doc, docx oder txt. Eine zulässige Dateiendung garantiert nicht, dass der Dienst die Seiten zählen oder konvertieren kann. Die Größenbegrenzungen der Infrastruktur für Anfragen können niedriger sein, und Base64 vergrößert die Anfrage.

Die aktuelle Anwendung erlaubt pro Konto einen Auftrag für dasselbe Ziel, der sich in der Warteschlange oder im Versand befindet, höchstens fünf Übermittlungen an dieses Ziel innerhalb der zurückliegenden Stunde und insgesamt höchstens 50 Übermittlungen innerhalb der zurückliegenden Stunde. Eine Antwort wegen Überschreitung der Häufigkeitsbegrenzung verwendet den API-Code 429. Warten Sie vor einem erneuten Versuch; versuchen Sie nicht, die Begrenzungen zu umgehen.

Auftrags-ID aufbewahren

Prüfen Sie sowohl das HTTP-Ergebnis als auch status.code in JSON. Fehlermeldungen in JSON können mit HTTP 200 eintreffen. Eine erfolgreiche JSON-Antwort enthält status und response; die Beispiele verwenden fiktive Daten.

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

Fragen Sie regelmäßig fax_status mit response.job_id ab. Wenn die Antwort auf die Sendeanfrage verloren geht, prüfen Sie vor einem erneuten Senden den Postausgang im Portal: Wiederholte Anfragen können separate Übertragungen auslösen. Dieser Handler stellt keinen clientseitigen Idempotenzparameter bereit.

Fehler und Guthabenprüfungen

Zu den API-Codes gehören 400 bei fehlenden Feldern, ungültiger Rückruf-URL, abgelehntem Dokument oder fehlgeschlagener Seitenerkennung; 401 bei fehlender Authentifizierung; 402, wenn die geschätzten Faxkosten zuzüglich der Kostenschätzungen für Aufträge in der Warteschlange oder im Versand das verfügbare Kontoguthaben übersteigen; 429 bei Überschreitung der Häufigkeitsbegrenzungen; und 500 bei einem Fehler in der Bereitstellung zur Verarbeitung. Den genauen Grund finden Sie in status.msg.

Die Warteschlange erfasst vor der Übertragung eine Kostenschätzung. Verstehen Sie weder die Annahme noch die Guthabenprüfung oder diese Schätzung als Bestätigung einer erfolgten Abbuchung. Die endgültigen Abrechnungs- und Rückrufdetails müssen noch überprüft werden.