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 anfänglichen Authentifizierungsprozess abgeschlossen haben und sich erfolgreich bei der API angemeldet haben. Für weitere Anweisungen lesen Sie bitte unseren Leitfaden 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']
Stellen Sie sicher, dass Sie folgende Header in Ihrer Anfrage angeben:
-
- Content-Type:
multipart/form-data
- Content-Type:
-
- Authorization:
Bearer [access token]
- Authorization:
-
- x-fax-clientid:
[client ID]
- x-fax-clientid:
Für den Body:
{
"fax_file": [file]
}
Im folgenden Beispiel wird „self“ als Benutzer-ID verwendet, um die eindeutige Kennung des aktuell angemeldeten Benutzers darzustellen:
Nach erfolgreichem Hochladen der Datei erhalten Sie einen Pfad, der auf den temporären Speicherort der Datei bei Fax.Plus verweist.
Sobald die Uploads abgeschlossen sind, können Sie mit der Vorbereitung Ihres Faxes zum Senden beginnen. Um den Vorgang zu starten, führen Sie eine HTTP-POST-Anfrage an die folgende URL aus:
https://restapi.fax.plus/v3/accounts/[user ID]/outbox
Stellen Sie sicher, dass Sie folgende Header in Ihrer Anfrage angeben:
-
- Authorization:
Bearer [access token]
- x-fax-clientid:
[client ID]
- Authorization:
Für den Anfrage-Body:
{
"from": "",
"to": [
""
],
"files": [
""
],
"comment": {
"text": ""
},
"send_time": "",
}
Nach erfolgreicher Planung des Faxes erhalten Sie eine Outbox-ID. Diese ID kann verwendet werden, um Änderungen vorzunehmen oder das Fax zu löschen, bevor es tatsächlich gesendet wird.
Hinweis: Bei unserer API sind Faxe mit mehreren IDs verknüpft. Dieses Design wurde gewählt, weil die Faxübertragung asynchron erfolgt. Genauer gesagt wird ein ausgehendes Fax durch zwei unterschiedliche IDs identifiziert: die Outbox-ID, die ihren Zweck bis zum erfolgreichen Senden des Faxes erfüllt, und die Fax-ID, die zur endgültigen Kennung des Faxes wird, sobald es erfolgreich übertragen wurde.
Nachdem das Fax geplant wurde, können Sie dessen Status überwachen, indem Sie die Liste der Faxe in der Outbox oder in der Kategorie „Gesendet“ überprüfen.
Alternativ haben Sie die Möglichkeit, einen HTTP-Server einzurichten und einen Webhook zu verwenden. Dadurch wird eine HTTP-Nachricht ausgelöst, wenn das Fax erfolgreich gesendet wurde oder wenn beim Senden ein Fehler aufgetreten ist.
Führen Sie diese Schritte aus, um den Webhook einzurichten:
- Melden Sie sich bei Ihrem Fax.Plus-Konto an und gehen Sie zum Bereich Einstellungen auf Ihrem Dashboard.
- Suchen Sie unter der Registerkarte Integrationen das Feld für WebHooks.
- Suchen Sie nach den Webhook-Einstellungen für ausgehende Faxbenachrichtigungen. Klicken Sie auf Verwalten, um den Webhook zu ändern.
Sobald Sie den Webhook eingerichtet haben, erhalten Sie folgende Benachrichtigung, nachdem 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 liefert Ihnen die Übertragungszeit, gibt den Erfolg der Faxübertragung an (über das Feld „status“) und stellt Ihnen die eindeutige Fax-ID zur Verfügung. Diese Fax-ID kann verwendet werden, um die Faxdatei abzurufen oder einen Faxbestätigungsbericht zu erhalten.