Fax-API Sandbox

Die Sandbox unterstützt Entwickler bei der Integration von Funktionen der Fax-API in betriebliche Anwendungen. Die Anbindung der Fax-API erfolgt in einer gekapselten Entwicklungsumgebung: der Sandbox, bevor im Zuge der Inbetriebnahme reale Faxaufträge über das Produktivsystem generiert werden.

Die Sandbox stellt einen reduzierten Funktionsumfang zur Verfügung. Dieser verfügt über Entwicklungshilfen wie Fehlersimulatoren.

Entwicklungssystem

Login: Sandbox

Faxsuite Sandbox: https://sandbox.faxsuite.de

Fax-API SOAP 2.0

Service-Endpunkt Sendfax: https://sandbox.fax-api.de/2.0/sendfax.php?WSDL
Service-Endpunkt Job: https://sandbox.fax-api.de/2.0/job.php?WSDL

Produktivsystem

Login: Produktivsystem

Faxsuite: https://www.faxsuite.de

Fax-API SOAP 2.0

Service-Endpunkt Sendfax: https://soap.fax-api.de/2.0/sendfax.php?WSDL
Service-Endpunkt Job: https://soap.fax-api.de/2.0/job.php?WSDL

In der Sandbox erfolgt das Verwalten von Fax-API-Konten und Konfigurationsparametern vollkommen unabhängig vom Datenstand des Produktivsystems der Faxsuite. Die hermetische Trennung der Datenkreise und Servicesysteme von Entwicklungs- und Produktivumgebung macht einen intensiven Testbetreib möglich.

Die zwei zentralen Aspekte der Sandbox sind die Kontrolle der Kommunikation zwischen den zu entwickelnden Anwendungen und den Systemen der Fax-API und die Prüfung der aus den Faxvorlagen erstellten Faxdokumente.

Über die Sandbox eingeplante Auftragssimulationen verursachen keine Versandkosten.

Wenn Sie einen Testzugang zur Faxsuite haben oder das Produkt „Faxsuite“ nutzen, steht Ihnen die Sandbox zur Verfügung. Dafür loggen Sie sich auf der Webseite https://sandbox.faxsuite.de mit Ihren Zugangsdaten ein.

Der Erstzugang zur Sandbox kann frühestens ca. 30 Minuten nach der Aktivierung des Faxsuite-Kundenkontos erfolgen. Es ist keine gesonderte Beantragung oder Freischaltung der Sandbox notwendig.

Analog zur Faxsuite ist die Sandbox zugriffsgeschützt. Der Login erfolgt unter Angabe der
gleichen Zugangsdaten wie in der Faxsuite.

Loggen Sie sich in die Faxsuite Sandbox ein. Unter dem Menüpunkt „Fax-API“ finden Sie den Punkt „Konto verwalten“. Hier können Sie neue Fax-API-Konten erstellen oder bereits vorhandene Fax-API-Konten bearbeiten.

Die Vorgehensweise ist identisch mit der Kontoverwaltung im Produktivsyststem. Die Anleitung zum Anlegen und Bearbeiten von Fax-API-Konten finden Sie hier.

Die in der Sandbox angelegten Fax-API-Konten sind unabhängig von den API-Konten im Produktivsystem
(separate Datenkreise).

Anwendungen, die mit einem Autorisierungs-Schlüssel eines Sandbox-API-Kontos arbeiten, können nicht im
Produktivsystem der Faxsuite verwendet werden.

In der Faxsuite Sandbox gibt es bei der Anlage bzw. Bearbeitung des Fax-API-Kontos zusätzlich einen Reiter „Sandbox“.
Eingabefeld Beschreibung
Test-Empfänger An die hier hinterlegte E-Mail-Adresse erhalten Sie nach der Bearbeitung des Testauftrags eine E-Mail mit dem aus der Faxvorlage erstellten Faxdokument.
Versand-Simulation

Versand erfolgreich und fehlerhaft

Bei dieser Einstellung werden sowohl erfolgreiche als auch fehlerhalfte Zustellungen simuliert.

Versand fehlerhaft

Wählen Sie bei der Versand-Simulation „Versand fehlerhaft“, werden nur fehlerhafte Zustellungen simuliert.

Versand erfolgreich

Bei der Auswahl „Versand erfolgreich“ werden nur erfolgreiche Zustellungen simuliert.

Innerhalb der Sandbox werden Faxaufträge nicht real ausgeführt, das heißt es werden keine Faxe versendet. Die Sandbox simuliert jedoch alle Teilphasen des Faxversands:

  • Prüfroutinen beim Auftragseingang (inkl. Autorisierung, Analyse von Faxvorlagen und Faxempfängerdaten mit Berücksichtigung von Länderfreigaben und Sperrlisteneinträgen des Sandbox-Kundenprofils)
  • Abfrage von Auftragsdaten aktiver Faxaufträge (Status-Polling)
  • Steuern von Faxaufträgen (anhalten und Auftrag neu starten)
  • Versand von Benachrichtigungen nach abgeschlossenen Faxaufträgen

Mit diesen Funktionen können Entwickler die Validität der Kommunikation zwischen der Fax-API und den eigenen Anwendungen testen.

Simulation von erfolgreichen und fehlerhaften Zustellungen

Damit auch die Roubustheit der Anwendungen mit Hilfe der Sandbox getestet werden kann, streut das System per Zufallsgenerator Fehler in die Ergebnisse der Auftragsverarbeitung. Folgende Ergebnisse werden dabei von der Sandbox verwendet.

Code Meldung   Code Meldung
0 Erfolgreich zugestellt 5 Verbindungsaufbau fehlgeschlagen
1 Ungültige Faxnummer   6 Übertragung fehlgeschlagen
2 Gegenstelle antwortet nicht   7 Interner Fehler beim Faxversand
3 Gegenstelle besetzt   8 Temporärer Fehler beim Faxversand
4 Gegenstelle kein G3-Faxgerät   9 Faxversand abgebrochen

Liefert ein Faxauftrag darüber hinaus andere Ergebniscodes zurück, sind diese in jedem Fall unmittelbar durch Eigenschaften des Faxauftrags bedingt und nicht simuliert. Eine Auflistung der Analyse-Codes und Fax-API Analyse-Codes finden Sie hier.

Für Ihre Faxaufträge können Sie folgende Faxvorlagentypen verwenden:

Dateityp
application/pdf
image/tiff
image/gif
image/png
text/html
text/plain

Diese Faxvorlagetypen werden von den Systemen unseres Webdiensts entgegen genommen und in das zu verschickende Faxdokument umgewandelt. Dabei kann sich der Inhalt der ursprünglichen Faxvorlage optisch verändern, z. B. wenn der angegebene HTML-Code nicht wohlgeformt ist oder die Bildmaße von PNG-Dateien nicht geeignet sind. Daher ist neben dem Testen der Faxauftragsverarbeitung auch das Prüfen der Faxvorlagentransformation für Enwickler relevant.

So prüfen Sie das aus der Faxvorlage erstellte Faxdokument:

Beim Anlegen bzw. Bearbeiten des Fax-API-Kontos rufen Sie den Reiter „Sandbox“ auf. Beim Eingabefeld „Test-Empfänger“ hinterlegen Sie die E-Mail-Adresse, an die das erstellte Faxdokument per E-Mail gesendet werden soll. Nach der Bearbeitung Ihres Testauftrags erhalten Sie eine E-Mail mit dem aus der Faxvorlage erstellten Faxdokument.

Alternativ können Sie sich die Faxvorschau auch in der Faxsuite Sandbox ansehen. Gehen Sie dazu in den Menüpunkt Fax-API unter Auftragsübersicht. Wählen Sie den gewünschten Faxauftrag aus und gehen Sie auf Auftrag bearbeiten. Im Bereich Faxvorlage sehen Sie die Faxvorschau als PDF. Weitere Informationen zur Auftragsübersicht – Auswertung finden Sie hier.

Die Erstellung des Faxdokuments aus der Faxvorlage des Fax-API-Auftrags ist keiner Fehlersimulation unterworfen.
Die Transformation erfolgt analog zum späteren Vorgang im Produktivsystem.

Das Faxsuite Produktivsystem und die Faxsuite Sandbox sind zwei voneinander unabhängige Systeme. Daher müssen bei der Inbetriebnahme von Anwendungen einige Anpassungen an den Konfigurationseinstellungen vorgenommen werden.

Zu jedem Fax-API-Konto gehört ein eindeutiger Autorisierungs-Schlüssel. Innerhalb einer Anwendung kann nur eine Kombination aus Autorisierungs-Schlüssel und Service-Endpunkt der gleichen Systemumgebung verwendet werden.

Faxsuite-System API-Konto Service Endpukte
Entwicklungssystem Sandbox API-Konto der Sandbox Service-Endpunkt Sendfax: https://sandbox.fax-api.de/2.0/sendfax.php?WSDL
Service-Endpunkt Job: https://sandbox.fax-api.de/2.0/job.php?WSDL
Produktivsystem Faxsuite API-Konto des Produktivsysstems Service-Endpunkt Sendfax: https://soap.fax-api.de/2.0/sendfax.php?WSDL
Service-Endpunkt Job: https://soap.fax-api.de/2.0/job.php?WSDL

Wird eine andere Kombination von Autorisierungs-Schlüssel und Endpunkt verwendet, verweigert das System die Auftragsverarbeitung und liefert beim Versuch einer Auftragseinsteuerung umgehend einen Fax-API Fehlercode zurück.

Achten Sie bei der Inbetriebnahme von Anwendungen unbedingt darauf, dass Sie vorher alle notwendigen Fax-API-Konten innerhalb der Produktivumgebung erstellt haben. Übernehmen Sie die in der Sandbox vorgenommenen Optionseinstellungen manuell in die Produktivumgebung. Nur wenn die Einstellungen der Fax-API-Konten von der Faxsuite Sandbox und der Faxsuite im Produktivsystem einheitlich sind, können Sie von einem gleichartigen Verhalten beider Systeme bei der Verarbeitung von Faxaufträgen ausgehen.