So richten Sie die Dropbox Fax-API ein

Dieser Artikel enthält Informationen darüber, wie Sie die Dropbox Fax API mit den v1-Endpunkten einrichten, wie Sie sicherstellen, dass sie funktioniert und wie Sie überprüfen können, ob Sie zusätzliche Faxleitungen bei Bedarf kaufen müssen.

So richten Sie die Dropbox Fax API mit v1-Endpunkten ein

So starten Sie, wenn Sie v1-Endpunkte verwenden:

1. Senden Sie eine E-Mail an support@hellosign.com mit der E-Mail-Adresse, die Sie für Ihr Dropbox Fax-Konto verwenden möchten. Sie erhalten eine Antwort, sobald Ihr Dropbox Fax API-Zugriff aktiviert ist. Erfahren Sie mehr über die Preise für die Dropbox Fax API.
2. Melden Sie sich bei Ihrem Dropbox Fax-Konto an. Notieren Sie sich Ihre Account GUID, da Sie diese für die meisten API-Anfragen (oder Endpunkte) benötigen.
3. Senden Sie Ihre erste API-Anfrage und erhalten Sie die Konfigurationsinformationen für Ihr Konto:

Ein Beispiel hierfür wäre:

Ein weiteres Beispiel (URL-Kodierung nicht vergessen):

Die Antwort ist eine JSON-Darstellung Ihrer Kontoeinstellungen.

4. So fügen Sie Rückruf-URLs für Ihre eingehenden und ausgehenden Faxe erneut mit einem POST-Befehl hinzu:

5. So überprüfen Sie die verfügbaren Faxleitungen:

Die Antwort enthält die FaxLine, die Sie bei der Anmeldung für ein Premium-Abo ausgewählt haben.

6. Um eine Faxnummer zu kaufen, müssen wir mit einem GET-Befehl prüfen, welche Vorwahlen verfügbar sind (nicht alle Vorwahlen sind verfügbar):

7. Kaufen Sie eine Faxnummer mit einer der verfügbaren Vorwahlen aus Schritt 6:

8. So senden Sie ein Fax:

Damit wird der Faxversand gestartet. Wenn Sie die HTTP-Antwort 200 erhalten, bedeutet das nicht, dass das Fax auch gesendet wird. Es kann immer noch ein Fehler bei der Dateikonvertierung auftreten. Sobald der StatusCode des Faxes jedoch E (für Fehler) oder S (für Erfolg) lautet, erhalten Sie einen POST an die Rückruf-URL, die Sie in Schritt 4 angegeben haben. Erfahren Sie mehr über Rückrufereignisse.

Mögliche Werte beim StatusCode:

• T = Übertragung läuft/wird gesendet.
• P = ausstehend/wird umgewandelt.
• S = erfolgreich gesendet.
• E = Fehler. Konvertierung oder vollständiger Versand fehlgeschlagen
• H = Warteschleife. Dieser Fehler tritt auf, wenn Sie ein nicht bestätigtes Konto haben oder wenn Sie kein monatliches Abo haben und keine Faxseiten mehr versenden können.

Mögliche ErrorCode-Werte (nur als Referenz, wenn der StatusCode „E“ ist):

• B = Besetztzeichen erhalten.
• N = keine Antwort.
• A = nicht zugewiesene Nummer (normalerweise bedeutet dies, dass die Verbindung getrennt wurde).
• D = die Leitung ist unterbrochen oder nicht erreichbar.
• L = diese Nummer steht auf der Sperrliste (sollte bei keiner US-Nummer der Fall sein).
• U = unbekannter Fehler. Dies tritt normalerweise auf, wenn eine Person den Hörer abhebt oder während der Faxübertragung ein Fehler aufgetreten ist.
  

Hinweise:

• Wenn Sie ein Fax senden und das Faxgerät des Empfängers die Anruferidentifizierung unterstützt, wird die Anruferkennung mit Ihrer primären Faxnummer oder der Faxnummer angezeigt, die Sie im „Von“-Parameter angegeben haben. Ihre primäre Faxnummer wird auf dem Fax selbst angezeigt. Wenn Sie mehrere Dropbox Fax-Leitungen haben, können Sie auswählen, welche Sie als sendendes Faxgerät verwenden möchten, indem Sie den Parameter „Von“ in die URL einfügen:

Das Format des Wertes „Von“ entnehmen Sie bitte dem Feld „Number“, das durch den Aufruf/FaxLines zurückgegeben wird (siehe Schritt 5 oben).

• Sie können mehrere Dateien hochladen und mehrere Faxe in einem Anruf senden – erstellen Sie einfach die Parameter-Arrays „Datei“ und/oder „An“:

oder

• Sie können ein von Dropbox Fax generiertes Deckblatt hinzufügen, indem Sie einen oder mehrere der folgenden Parameter angeben: „CoverPageTo“, „CoverPageFrom“ und „CoverPageMessage“.
• Von der API gesendete Faxe werden nicht auf unseren Servern gespeichert, sobald das Fax erfolgreich gesendet wurde – sie werden entfernt. Daher können Sie diese nicht in der Benutzeroberfläche anzeigen. Eingehende Faxe, die erfolgreich mit POST an Ihre Rückruf-Adresse weitergeleitet wurden, werden jedoch auf unseren Servern gespeichert und Sie können diese im Bildschirm „Dokumente“ einsehen.
• Es gibt ein Limit von 200 ausstehenden Faxen pro Tag. Wenn Sie dieses Limit erreichen, erhalten Sie den Fehler 429:

Wie überprüfe ich den Status von Faxen?

1. Sie finden die Übertragungs-GUID in der JSON-Antwort, die vom API-Aufruf in Schritt 8 zurückgegeben wird. Außerdem können Sie den Status aller Ihrer Übertragungen überprüfen, indem Sie die Übertragungs-GUID weglassen:

Diese Ergebnisse werden paginiert. Sie können verschiedene Seiten abrufen, indem Sie die URL-Parameter „Page“ und „PageSize“ angeben. Informationen zur Funktion von Seitenaufruden finden Sie in den Antwortelementen „FirstPageUri“, „NextPageUri“, „PreviousPageUri“ und „LastPageUri“.

2. Sobald der Statuscode des Faxes „S“ oder „E“ lautet, überprüfen Sie, ob Ihre Rückruf-URL für ausgehende Faxe ausgelöst wurde. Diese sollte einen POST-Befehl erhalten, der einen Parameter mit der Bezeichnung „json“ enthält. Hierbei ist alles enthalten, was Sie in der Antwort auf einen Aufruf erhalten würden (siehe Schritt 1).

Wenn ein erfolgreicher POST-Rückruf durch ein Server- oder Netzwerkproblem verhindert wird, versucht Dropbox es in diesen Intervallen erneut:

• 15 Minuten
• 45 Minuten
• 1 Stunde und 30 Minuten
• 2 Stunden und 45 Minuten
• 4 Stunden
• 8 Stunden und 15 Minuten
• 16 Stunden und 30 Minuten

In jedem Intervall kann Dropbox mehrmals versuchen, den POST-Befehl auszuführen, wenn der Antwortcode 200 nicht empfangen wird.

3. Wenn Sie das Fax an Ihre eigene Dropbox Fax-Nummer gesendet haben (nützlich zum Testen), überprüfen Sie, ob auch Ihre Rückruf-URL für eingehende Faxe ausgelöst wurde.
4. Listen Sie Ihre gekauften FaxLines auf:

5. Um eine FaxLine zu löschen, rufen Sie DELETE mit dem URI dieser FaxLine auf (diese ist in der Antwort des vorherigen Schritts angegeben):

Wenn der Vorgang erfolgreich ist, erhalten Sie die Antwort 200.