Die EZDocu-API für Entwickler

Mit der EZDocu-API (v1) verbinden Sie Ihr eigenes System (CRM, ERP, Bestellwebsite) mit EZDocu. Ihr System lädt das Dokument hoch, erstellt den Übersetzungs- oder Layout-Auftrag, erfährt, wann er fertig ist, und lädt das Ergebnis herunter, ohne das Dashboard zu öffnen. Es sind dieselben Aufträge und dasselbe Credit-Guthaben, die Sie in der Web-App verwenden.

Wer Schlüssel erstellen darf

Das hängt nicht vom Tarif ab, sondern von der Berechtigung API-Schlüssel. Der Eigentümer hat sie immer, Manager haben sie standardmäßig. Bei Prüfer und Mitglied ist sie ausgeschaltet; der Eigentümer kann sie unter Team pro Person einschalten.

Mit Zugriff „Nur Lesen“ können Sie keine Schlüssel ansehen, erstellen oder widerrufen. Jeder Schlüssel arbeitet mit dem Zugriff der Person, die ihn erstellt hat, und kann nie mehr als diese Person. Wird diese Person im Team deaktiviert, erscheint ihr Schlüssel als Ausgesetzt.

Einen Schlüssel erstellen

1. Gehen Sie zu Einstellungen › API-Schlüssel.
2. Klicken Sie auf Schlüssel erstellen.
3. Geben Sie unter Name einen Namen ein, an dem Sie den Schlüssel erkennen, zum Beispiel ERP-Integration.
4. Wählen Sie die Umgebung: Staging zum Testen oder Produktion für die echte Arbeit.
5. Markieren Sie die Dienste: Übersetzung, Layout oder beide. Ohne Dienste kann der Schlüssel nur lesen.
6. Markieren Sie unter Zugriff nach Bereich Lesen oder Schreiben. Sie können nur Zugriffe vergeben, die Sie selbst haben; Aufträge und Webhooks erfordern die Berechtigung „Alle Dokumente ansehen und zuweisen“.
7. Wenn Sie möchten, legen Sie ein Tägliches Seitenlimit fest (leer = kein Limit; höchstens 5000).
8. Klicken Sie auf Schlüssel erstellen, kopieren Sie ihn mit Kopieren und klicken Sie auf Ich habe ihn gespeichert. Der vollständige Schlüssel wird nur dieses eine Mal angezeigt.

Sie können bis zu 20 aktive Schlüssel haben. Widerrufen schaltet einen Schlüssel sofort ab und lässt sich nicht rückgängig machen. Behandeln Sie ihn wie ein Passwort.

Staging und Produktion: wohin jeder Schlüssel zeigt

Beide werden hier erstellt, auf www.ezdocu.ai, unter Einstellungen › API-Schlüssel. Sie brauchen kein weiteres Konto.

Jeder Schlüssel funktioniert nur mit seiner URL. Beginnen Sie mit Staging; wenn alles funktioniert, wechseln Sie URL und Schlüssel: Die Routen sind dieselben.

Wo Sie die Dokumentation finden

In der Seitenleiste unter API-Dokumentation. Dort finden Sie den Schnellstart, die Anleitungen Ein Dokument übersetzen, Layout ohne Übersetzung und Menschliche Prüfung, Webhooks und Signaturprüfung sowie die Referenz jeder Route mit Beispielen.

• Unter Umgebungen wählen Sie Staging oder Produktion: Damit ändern sich die Basis-URL, die Beispiele und die Downloads (Postman herunterladen und OpenAPI herunterladen).
• In Swagger testen ruft den Server der Website auf, auf der Sie sich befinden: Auf www ist das Produktion, und das Erstellen eines Auftrags verbraucht Credits. Für den Staging-Schlüssel verwenden Sie Postman oder Ihren Code.

Der grundlegende Ablauf

Jede Anfrage trägt den Header Authorization: Bearer <Ihr Schlüssel>. Jeder POST, PATCH, PUT und DELETE trägt außerdem einen Idempotency-Key: Wiederholen Sie die Anfrage mit demselben Wert, werden nie zwei Aufträge erstellt und nie doppelt abgerechnet.

1. Laden Sie die Datei hoch mit POST /uploads (Sie erhalten eine Upload-URL), senden Sie sie an diese URL und bestätigen Sie mit POST /uploads/{id}/complete. Liegt die Datei bereits unter einer öffentlichen https://-URL, senden Sie diese beim Erstellen des Auftrags in file_url.
2. Erstellen Sie den Auftrag mit POST /orders. In mode steht translate (übersetzen) oder layout (Layout in derselben Sprache). Beim Übersetzen geben Sie target_language an, zum Beispiel en-US. Die Sprache des Dokuments wird automatisch erkannt.
3. Warten Sie auf das Ergebnis: mit dem Webhook order.completed (empfohlen) oder indem Sie GET /orders/{id} alle 15 bis 30 Sekunden abfragen.
4. Laden Sie herunter: Steht der Auftrag auf completed, enthält das Detail einen Link pro Datei, der 1 Stunde gültig ist.

Welche Dateien Sie erhalten

PDF, DOCX und HTML (ein HTML pro Seite und eines mit allen Seiten), in der gewünschten Kombination, dazu das Zertifikat und das Original. Der Inhalt des Dokuments steht nie im JSON der Antwort: nur die Links und die Daten des Auftrags. Beim Übersetzen sind das Zertifikat und die digitale Signatur des PDFs standardmäßig dabei; Sie können sie in der Anfrage abwählen.

Webhooks

Sie werden über die API erstellt (POST /webhooks), nicht in den Einstellungen. EZDocu sendet bei jedem Ereignis einen signierten POST an Ihre https://-URL:

Das Signaturgeheimnis (whsec_…) wird nur einmal angezeigt. Ihr Server muss innerhalb von 10 Sekunden mit 2xx antworten; andernfalls wiederholt EZDocu den Versand etwas mehr als anderthalb Tage lang.

Menschliche Prüfung

Mit review_required: true hält der Auftrag bei in_review an und wartet ohne Zeitlimit auf Ihr Team. Die prüfende Person öffnet ihn unter Aufträge, klickt auf Auftrag fortsetzen, prüft ihn und klickt auf Auftrag abschließen. Dann kommt order.completed an. Wer abschließt, wählt Format, Zertifikat und das Siegel „Menschlich verifiziert“: Ein Auftrag ohne Prüfung erhält dieses Siegel nie. Die Freigabe erfolgt in der Web-App, nicht über die API.

Credits und Limits

• Dasselbe Guthaben wie in der Web-App: 1 Credit pro Seite, abgerechnet beim Erstellen des Auftrags.
• Ohne Guthaben antwortet POST /orders mit 402 INSUFFICIENT_CREDITS, und es wird nichts erstellt oder abgerechnet.
• Schlägt ein abgerechneter Auftrag fehl oder stornieren Sie ihn, werden die Credits nicht automatisch erstattet: Schreiben Sie dem Support mit der Auftragsnummer.
• DOCX, HTML, Zertifikat oder Prüfung anzufordern, kostet nichts extra.
• 100 Anfragen pro Minute pro Schlüssel (Standard). Dateien bis 50 MB und 2000 Seiten, als PDF, JPG, PNG, TIFF, WebP, HEIC, DOCX oder ODT.

Häufige Fehler

Nutzungsübersicht

In der Seitenleiste öffnet API die Seite API-Nutzung: Anfragen, Aufträge, Seiten, Fehler, Webhooks und Limits Ihres Kontos, nach Zeitraum, nach Schlüssel und nach Mitglied. Sie sehen alle, die die Berechtigung API-Schlüssel haben.

Häufige Fragen

Brauche ich einen speziellen Tarif, um die API zu nutzen? Nein. Sie brauchen die Berechtigung API-Schlüssel, die der Eigentümer und die Manager haben.

Mein Entwickler erhält mit dem Staging-Schlüssel 401 oder 403. Woran liegt das? Fast immer an der URL: Der Staging-Schlüssel (ezk_test_) funktioniert nur mit https://staging.ezdocu.ai/api/v1, der Produktionsschlüssel (ezk_live_) nur mit https://www.ezdocu.ai/api/v1. Ist der Staging-Schlüssel neu, warten Sie eine Minute, bevor Sie ihn verwenden.

Verbrauchen Tests mit dem Staging-Schlüssel Credits? Nein: Die Aufträge sind simuliert. Nur der Produktionsschlüssel rechnet ab.

Kann ich die Übersetzung als Text im JSON erhalten? Nein. Die API liefert Dateien: PDF, DOCX oder HTML.