Fax-API

Dokument hochladen

POST /api/v1/documents

Fordere einen Upload-Slot an und sende die Dateidaten per PUT an upload_url. Sie gehen direkt an den Speicher. Diese Anfrage prüft nur deine Angaben zur Datei. Danach erstellst du mit id des Slots ein Fax. Es gibt keine Anfrage zum Herunterladen oder Auflisten von Dokumenten.

checksum ist der Base64-kodierte MD5-Wert der Datei, wie im Content-MD5-Header. byte_size ist die genaue Größe in Bytes. content_type ist application/pdf, image/jpeg, image/png, image/webp, image/heic oder image/heif. Die Slot-ID gilt 1 Stunde, die Upload-URL 5 Minuten. Der Speicher lehnt Dateien ab, deren Größe oder MD5 nicht zum Slot passt.

openssl dgst -md5 -binary referral.pdf | openssl base64
wc -c referral.pdf | awk '{print $1}'

curl -s https://eu.faxette.com/api/v1/documents \
  -H "Content-Type: application/json" \
  -d '{"filename":"referral.pdf","byte_size":248113,"checksum":"gbgEgwqIGW9JMTqqgYW+xw==","content_type":"application/pdf"}'

201 mit dem Slot.

{
  "data": {
    "type": "Document",
    "id": "SIGNED_ID",
    "upload_url": "https://example.r2.cloudflarestorage.com/faxette/...",
    "upload_headers": {
      "Content-Type": "application/pdf",
      "Content-MD5": "gbgEgwqIGW9JMTqqgYW+xw==",
      "Content-Disposition": "inline; filename=\"referral.pdf\"; filename*=UTF-8''referral.pdf"
    }
  }
}

Sende die unveränderten Dateidaten per PUT an upload_url und verwende alle Header aus upload_headers. Übernimm die Werte aus der Antwort. $UPLOAD_URL steht unten für upload_url.

curl -X PUT --data-binary @referral.pdf \
  -H "Content-Type: application/pdf" \
  -H "Content-MD5: gbgEgwqIGW9JMTqqgYW+xw==" \
  -H "Content-Disposition: inline; filename=\"referral.pdf\"; filename*=UTF-8''referral.pdf" \
  "$UPLOAD_URL"

Fax erstellen

POST /api/v1/faxes

Beim Erstellen eines Faxes wird keine Karte belastet. Die Antwort enthält token einmalig. Speichere den Wert. Er wird später nicht erneut ausgegeben. Frage GET /api/v1/faxes/:id ab, bis status gleich documents_ready und checkout_available gleich true ist. Leite die Person dann zu status_url. Dort prüft sie Faxnummer, Dokumente und Preis und bezahlt. Die Zahlung beginnt über die Schaltfläche auf dieser Seite. Ein Link, der Checkout startet, würde von Linkvorschauen in Chat-Apps geöffnet. Deshalb gibt es keinen Checkout-Endpunkt.

Zwei gleiche Anfragen erstellen zwei Faxe. Es gibt keinen Idempotenzschlüssel.

Mit Dokument-IDs

documents enthält die Slot-IDs in der gewünschten Faxreihenfolge. Eine bereits einem Fax zugeordnete ID kann nicht für ein anderes Fax verwendet werden. Lade die Datei erneut hoch.

curl -s https://eu.faxette.com/api/v1/faxes \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","fax_number":"+442079460958","documents":["SIGNED_ID"]}'

Mit Dateien in einer Anfrage

Sende documents[] als Multipart-Dateien in Faxreihenfolge. Die Daten laufen über diesen Server. Große Dateien solltest du über einen Upload-Slot senden. Der Inhaltstyp muss einem der oben genannten entsprechen. type= setzt ihn, falls er sich nicht aus dem Dateinamen ergibt.

curl -s https://eu.faxette.com/api/v1/faxes \
  -F "[email protected]" \
  -F "fax_number=+442079460958" \
  -F "documents[][email protected];type=application/pdf" \
  -F "documents[][email protected];type=image/jpeg"

Leerer Entwurf

Lasse documents weg. In der Antwort ist status gleich draft. Die Person fügt ihre Dateien auf der Statusseite hinzu.

curl -s https://eu.faxette.com/api/v1/faxes \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","fax_number":"+442079460958"}'

Felder

201 mit Fax und Token. Andere Felder bleiben null, bis das Fax weiterverarbeitet wird.

{
  "data": {
    "type": "Fax",
    "id": "k3n8q0w1x4y7",
    "status": "processing_documents",
    "fax_number": "+442079460958",
    "page_count": null,
    "retries_remaining": 2,
    "next_attempt_at": null,
    "resend_by": null,
    "updated_at": "2026-10-27T16:04:00.000Z",
    "status_url": "https://eu.faxette.com/f/k3n8q0w1x4y7?token=exampletoken",
    "checkout_available": false,
    "price": null,
    "payment": null,
    "attempt": 1,
    "max_attempts": 3,
    "document_errors": [],
    "failure_reason": null,
    "token": "exampletoken"
  }
}

Nach dem Zählen der Seiten sehen die Felder so aus. currency ist auf dieser Website eur.

{
  "status": "documents_ready",
  "page_count": 3,
  "checkout_available": true,
  "price": { "amount_cents": 500, "currency": "eur" }
}

Fax abrufen

GET /api/v1/faxes/:id?token=

Liefert dasselbe Objekt wie beim Erstellen, ohne token. Die Antwort enthält niemals Dokumente oder Dateinamen. Frage den Status ab, solange status gleich processing_documents ist. document_errors nennt die zu korrigierende Datei anhand ihrer Position im Fax, beginnend bei 1.

curl -s "https://eu.faxette.com/api/v1/faxes/k3n8q0w1x4y7?token=exampletoken"

{
  "document_errors": [
    {
      "reason": "password_protected",
      "position": 2,
      "message": "Document 2 is locked with a password. Open it, save or print it as a new PDF without the password, then upload that copy."
    }
  ]
}

Dokumente ersetzen

PATCH /api/v1/faxes/:id/documents?token=

documents enthält die vollständige Liste in Faxreihenfolge. Um eine Datei zu behalten, sende ihre Slot-ID erneut. Um sie zu entfernen, lasse sie weg. Entfernte Dateien werden gelöscht und die Seiten erneut gezählt. Das ist möglich, solange status gleich draft, processing_documents oder documents_ready ist. Nach Beginn der Zahlung sind die Dateien gesperrt. Erstelle ein neues Fax, um sie zu ändern. Slot-IDs gelten 1 Stunde und erscheinen nie in der Fax-Antwort. Bewahre sie daher nach dem Upload auf.

curl -s -X PATCH "https://eu.faxette.com/api/v1/faxes/k3n8q0w1x4y7/documents?token=exampletoken" \
  -H "Content-Type: application/json" \
  -d '{"documents":["SIGNED_ID","ANOTHER_ID"]}'

200 mit dem Fax. status wird wieder processing_documents.

Erneut senden

POST /api/v1/faxes/:id/resend?token=

Ein fehlgeschlagenes Fax kann kostenlos erneut gesendet werden, solange der Betrag auf der Karte reserviert ist. resend_by nennt das Ende dieser Frist. retries_remaining muss größer als 0 sein und beginnt bei 2. Faxe mit failure_reason gleich our_side können nicht erneut gesendet werden. Die Reservierung wird sofort aufgehoben.

fax_number ist optional. Ohne Wert oder mit leerem Wert wird dieselbe Nummer verwendet. Eine Nummer ohne Ländervorwahl wird dem Land der aktuellen Faxnummer zugeordnet.

curl -s -X POST "https://eu.faxette.com/api/v1/faxes/k3n8q0w1x4y7/resend?token=exampletoken" \
  -H "Content-Type: application/json" \
  -d '{"fax_number":"+442079460018"}'

200 mit dem Fax. status ist scheduled.

{
  "status": "failed",
  "failure_reason": "temporary",
  "retries_remaining": 2,
  "resend_by": "2026-10-29T16:04:00.000Z",
  "payment": { "status": "authorized", "amount_cents": 605, "tax_cents": 105, "currency": "eur" }
}

Das Fax-Objekt

status

Bei besetzter Leitung wird später erneut gewählt. Diese Anrufe sind attempt von max_attempts. Sie sind unabhängig von einer Neuversendung durch den Kunden.

payment

payment.status ist authorized während der Kartenbetrag reserviert ist, paid nach Zustellung des Faxes und Abbuchung des reservierten Betrags, canceled wenn der reservierte Betrag freigegeben wurde, oder refunded wenn die Zahlung erstattet wurde. amount_cents ist der reservierte oder abgebuchte Betrag einschließlich Steuern. Auf dieser Website wird bei der Zahlung MwSt. hinzugefügt. tax_cents ist diese MwSt. Die Beträge im Beispiel zeigen einen einzelnen Fall. Die MwSt. hängt vom Land des Absenders ab. price bleibt der Betrag vor Steuern.

failure_reason

Null, außer status ist failed.

document_errors

Jeder Eintrag enthält reason, position und message. position ist die Dokumentnummer im Fax oder null bei einem Problem mit dem gesamten Fax. message ist die anzuzeigende Meldung. Dieselben Probleme können schon beim Erstellen als validation_failed zurückgegeben werden, bevor ein Fax existiert.

Fehler

message ist ein Satz. Verwende code für Programmlogik. Dieser Wert bleibt stabil.

{
  "code": "validation_failed",
  "message": "Fax number is in a country we can't fax to yet."
}

Grenzen

• 10 Dokumente, jeweils 20 MB, 200 Seiten, 50 Megapixel pro Bild.

Für Claude, ChatGPT und andere Assistenten: Zum MCP-Server →