Um ein Fax über die API zu senden, müssen Sie zunächst die erforderlichen Dateien hochladen, anschließend diese Dateien für den Faxversand vorbereiten und deren Übertragung planen.
Sobald Ihr Fax geplant ist, können Sie einen HTTP-Server implementieren und einen Webhook-Mechanismus nutzen. Dieser Ansatz stellt sicher, dass sowohl bei erfolgreicher Faxübertragung als auch im Falle eines Übertragungsfehlers eine HTTP-Nachricht gesendet wird.
Hinweis: Stellen Sie sicher, dass Sie den ersten Authentifizierungsprozess abgeschlossen haben und erfolgreich bei der API angemeldet sind. Weitere Anweisungen finden Sie in unserer Anleitung hier.
Um eine Datei hochzuladen, senden Sie eine HTTP-POST-Anfrage an die folgende URL: https://restapi.fax.plus/v3/accounts/[user ID]/files?format=[file format, 'pdf' or 'tiff']
Achten Sie darauf, die folgenden Header in Ihre Anfrage aufzunehmen:
-
Content-Type:
multipart/form-data
-
Authorization:
Bearer [access token]
-
x-fax-clientid:
[client ID]
Für den Body:
{
"fax_file": [file]
}
Im folgenden Beispiel wird „self“ als Benutzer-ID verwendet, um die eindeutige Kennung des aktuell angemeldeten Benutzerkontos darzustellen:
Sobald die Datei erfolgreich hochgeladen wurde, erhalten Sie einen Pfad zum temporären Speicherort der Datei auf Fax.Plus.
Sobald die Uploads abgeschlossen sind, können Sie damit beginnen, Ihr Fax für den Versand vorzubereiten. Um den Vorgang zu starten, senden Sie eine HTTP-POST-Anfrage an die folgende URL:
https://restapi.fax.plus/v3/accounts/[user ID]/outbox
Achten Sie darauf, die folgenden Header in Ihre Anfrage aufzunehmen:
-
Authorization:
Bearer [access token] -
x-fax-clientid:
[client ID]
Für den Request-Body:
{
"from": "",
"to": [
""
],
"files": [
""
],
"comment": {
"text": ""
},
"send_time": "",
}
Nach erfolgreicher Planung des Fax erhalten Sie eine Outbox-ID. Mit dieser ID können Sie das Fax ändern oder löschen, bevor es tatsächlich gesendet wird.
Hinweis: Bei unserer API sind Faxe mehreren IDs zugeordnet. Das liegt daran, dass die Faxübertragung asynchron erfolgt. Konkret wird ein ausgehendes Fax durch zwei verschiedene IDs identifiziert: die Outbox-ID, die gilt, bis das Fax erfolgreich gesendet wurde, und die Fax-ID, die nach erfolgreicher Übertragung zur endgültigen Kennung des Fax wird.
Nachdem Sie das Fax geplant haben, können Sie dessen Status überwachen, indem Sie die Liste der Faxe in der Outbox oder in der Kategorie „Gesendet“ einsehen.
Alternativ können Sie einen HTTP-Server einrichten und einen Webhook verwenden. Dadurch wird eine HTTP-Nachricht gesendet, sobald das Fax erfolgreich gesendet wurde oder der Versand fehlgeschlagen ist.
Gehen Sie wie folgt vor, um den Webhook einzurichten:
- Melden Sie sich bei Ihrem Fax.Plus-Konto an und gehen Sie zum Bereich Einstellungen in Ihrem Dashboard.
- Suchen Sie auf der Registerkarte Integrationen das Feld für Webhooks.
- Suchen Sie Eingehende Faxe und Eingehende Faxe. Klicken Sie auf Verwalten, um den Webhook zu ändern.
Nachdem Sie den Webhook eingerichtet haben, erhalten Sie die folgende Benachrichtigung, sobald ein ausgehendes Fax verarbeitet wurde:
{
"hook": {
"id": "",
"event": "fax_sent",
"event_time": "2022-12-09 15:50:00",
"target": "http://www.example.com/callback/fax_sent"
},
"data": {
"id": "",
"pages": 1,
"from": "",
"to": "",
"start_time": "2022-12-09 15:50:00",
"file": "",
"file_name": "fax-from-1xxxxxxxxxxxx",
"cost": 1,
"status": "success"
}
}Diese Nachricht enthält den Übertragungszeitpunkt, zeigt den Erfolg der Faxübertragung an (über das Feld „status“) und liefert Ihnen die eindeutige Fax-ID. Mit dieser Fax-ID können Sie die Faxdatei abrufen oder einen Faxbestätigungsbericht erhalten.