Zum Inhalt

Fax versenden

Mit dem Service Task „Fax versenden“ wird ein Dokument direkt aus einem Pantarey-Prozess als Fax zugestellt. So können z. B. Rechnungen, Lieferscheine oder Bestätigungen automatisiert an eine oder mehrere Faxnummern gesendet werden – ohne eigene Fax-Hardware und ohne zusätzlichen Vertrag mit einem Fax-Anbieter.

Funktion freischalten

Der Faxversand ist eine kostenpflichtige Zusatzfunktion und muss für den Mandanten freigeschaltet werden. Bei Bedarf bitte Pantarey kontaktieren. Anschließend steht der Service Task im Prozess-Designer zur Verfügung.

Input-Parameter

{
  "document": {
    "referenceId": "ref-rechnung-2026-04711"
  },
  "recipients": "0049530000000",
  "options": {
    "title": "Rechnung 4711"
  },
  "test": false,
  "waitForResult": true,
  "pollMaxAttempts": 24,
  "pollIntervalMs": 30000,
  "skipGrayscaleConversion": false
}

Erläuterung:

  • document: Das zu versendende Dokument. Zwei Varianten werden unterstützt:
    • { "referenceId": "..." } – Verweis auf eine in Pantarey gespeicherte Datei.
    • { "content": "<base64>", "contentType": "application/pdf", "filename": "rechnung.pdf" } – inline übergebenes Dokument.
  • recipients: Empfänger-Faxnummer(n). Möglich sind:
    • eine einzelne Nummer als String: "0049530000000"
    • ein einzelnes Objekt: { "faxNumber": "0049...", "name": "...", "recipientReference": "..." }
    • ein Array beider Varianten (gemischt erlaubt). Maximal 10 Empfänger pro Auftrag.
  • options (optional): Zusätzliche Optionen für den Faxauftrag wie title, faxHeader, stationID.
  • test (optional, Standard false): Bei true wird das Sandbox-System verwendet. Es entstehen keine Kosten und es wird kein reales Fax versendet. Empfohlen für Tests und Entwicklungs-Prozesse.
  • waitForResult (optional, Standard true): Bei true wartet der Task bis der Fax-Auftrag einen Endstatus (finished, error, canceled) erreicht hat. Bei false wird sofort nach dem Anlegen zurückgekehrt.
  • pollMaxAttempts / pollIntervalMs (optional): Steuern Anzahl und Abstand der Statusabfragen während des Wartens.
  • skipGrayscaleConversion (optional, Standard false): Steuert die automatische Graustufen-Konvertierung für PDFs (siehe nächster Abschnitt). Bei true wird das Original-PDF unverändert an den Fax-Dienst übergeben.

Unterstützte Dokumenttypen

Typ MIME-Type
PDF application/pdf
TIFF image/tiff
PNG image/png
GIF image/gif
HTML text/html
Klartext text/plain

Automatische Graustufen-Konvertierung

Farb-PDFs werden von vielen Fax-Diensten nicht korrekt verarbeitet – es entstehen schwarze oder leere Seiten beim Empfänger. Um das zu vermeiden, wird jedes PDF vor dem Versand automatisch in eine Graustufen-Version konvertiert.

Die automatische Konvertierung greift nur, wenn alle folgenden Bedingungen erfüllt sind:

  • der contentType des Dokuments ist application/pdf
  • das Dokument wird per referenceId übergeben (nicht als inline Base64-Inhalt)
  • skipGrayscaleConversion ist nicht gesetzt oder false

Die konvertierte Datei wird ausschließlich für den Faxversand verwendet. Das Original bleibt unverändert in der Dateiablage. Bilder, HTML und Klartext werden nicht konvertiert.

Wann sollte skipGrayscaleConversion: true verwendet werden?

Wenn das PDF bereits in einem vorgelagerten Schritt (z. B. mit PDF in Graustufen umwandeln) konvertiert wurde oder von vornherein in reiner Schwarz-Weiß- Form vorliegt. In diesen Fällen spart das Überspringen der erneuten Konvertierung Verarbeitungszeit.

Output

Bei waitForResult: true enthält das Ergebnis sowohl die Auftrags-ID als auch den Endstatus inklusive Empfängerdetails:

{
  "jobId": "0d139d2c-4a10-11f1-b04d-001851328a39",
  "status": "finished",
  "errorCode": null,
  "statistics": {
    "pages": 1,
    "recipientCount": 1,
    "recipientCountSuccessful": 1,
    "recipientCountError": 0
  },
  "recipients": [
    {
      "faxNumber": "0049530000000",
      "resultCode": 0,
      "resultText": "OK"
    }
  ]
}

Erläuterung:

  • jobId: Eindeutige ID des Faxauftrags. Diese ID wird benötigt, um den Status später erneut abzufragen (siehe Fax-Status abfragen).
  • status: Endstatus des Auftrags – finished, error oder canceled. Bei waitForResult: false kann hier auch scheduling, scheduled oder processing stehen.
  • errorCode: null bei Erfolg, andernfalls ein Fehlercode des Versanddienstes.
  • statistics: Anzahl Seiten und Empfänger (gesamt, erfolgreich, fehlgeschlagen).
  • recipients: Pro Empfänger das Detail-Ergebnis. resultCode 0 und resultText "OK" zeigen einen erfolgreichen Einzelversand. Achtung: Ein Auftragsstatus finished bedeutet nicht automatisch, dass jeder Einzelversand erfolgreich war – die recipients-Liste muss zusätzlich geprüft werden.

JSONata-Beispiele

Einzelner Empfänger aus Prozessdaten

{
  "document": {
    "referenceId": $.invoice.pdfRef.referenceId
  },
  "recipients": $.customer.faxNumber,
  "options": {
    "title": "Rechnung " & $.invoice.number
  },
  "test": false
}

Mehrere Empfänger mit Namen

{
  "document": {
    "referenceId": $.dispatchNote.pdfRef.referenceId
  },
  "recipients": [
    { "faxNumber": $.customer.faxNumber,    "name": $.customer.name },
    { "faxNumber": $.warehouse.faxNumber,   "name": $.warehouse.name }
  ],
  "options": {
    "title": "Lieferschein " & $.dispatchNote.number,
    "faxHeader": true
  }
}

Hinweise

  • Freischaltung erforderlich: Damit der Service Task im Prozess verfügbar ist, muss der Faxversand für den Mandanten aktiviert werden. Bei Bedarf bitte Pantarey kontaktieren.
  • Sandbox vs. Live: Mit test: true wird ein Testversand ohne Zustellkosten ausgelöst. Testaufträge werden in der Auswertung getrennt vom Echtbetrieb geführt und nicht real zugestellt.
  • Fax-Nummern: Es werden nationale (0530…) und internationale Schreibweisen (0049530…, +49530…) akzeptiert. Wird keine Ländervorwahl angegeben, wird automatisch die Standard-Vorwahl ergänzt.
  • Maximal 10 Empfänger pro Auftrag. Für größere Verteiler werden mehrere Aufträge gesendet.
  • Wartezeit: Bei waitForResult: true wartet der Task bis zu rund 12 Minuten auf den Endstatus (Standard: 24 Versuche × 30 Sekunden). Reicht das nicht aus, wird der zuletzt bekannte Status zurückgegeben und der Auftrag kann später per Fax-Status abfragen erneut geprüft werden.

Tipp

Häufige Kombination im Prozess:

  1. PDF aus Handlebars-Template erstellen – generiert das Versanddokument.
  2. Fax versenden – schickt das PDF an die Empfänger-Faxnummer.
  3. (Optional) Fax-Status abfragen – wenn der Versand zeitversetzt geprüft werden soll, z. B. nach einer Wartezeit oder einem Timer-Event.