Integrationen

Überblick

Nutzen Sie diesen Leitfaden, wenn Sie externe Systeme über Webhooks, Batch-Jobs oder eigene Middleware mit Numezis verbinden. Browser-Apps starten mit der Authentifizierung; Maschinen-Clients kombinieren Auth, die API-Referenz und die folgenden Regeln.

Webhooks

Eingehende Kanal-Webhooks (z. B. Telegram oder WhatsApp) werden auf der API registriert und mit Provider-Signaturen validiert. Ausgehende Benachrichtigungen an Ihre Systeme sollten als at-least-once behandelt werden: Implementieren Sie idempotente Handler mit Schlüssel auf der Event-ID.

Typischer Ablauf:

1. Registrieren Sie Endpunkt-URL und Secret in den Unternehmens- oder Mandanteneinstellungen.
2. Empfangen Sie JSON-Payloads mit Event-Typ, Mandanten-/Unternehmens-Scope und Entitäts-IDs.
3. Prüfen Sie Signatur oder Shared Secret vor der Verarbeitung.
4. Antworten Sie schnell mit 2xx; verlagern Sie schwere Arbeit in Ihre eigene Queue.

Ratenbegrenzungen

Öffentliche und Portal-APIs wenden mandantenbezogene Ratenbegrenzungen an. Antworten enthalten ggf. Standard-Rate-Limit-Header. Integrationen sollten bei 429 exponentielles Backoff nutzen und enge Polling-Schleifen vermeiden — bevorzugen Sie Webhooks oder dokumentierte Sync-Endpunkte.

Idempotenz

Senden Sie bei POST-Operationen, die Geschäftsdatensätze erstellen (Rechnungen, Lieferantenrechnungen, Zahlungen), einen stabilen Idempotency-Key-Header, sofern Ihre Client-Bibliothek dies unterstützt. Die Wiederholung desselben Schlüssels mit demselben Body liefert das ursprüngliche Ergebnis statt eines doppelten Dokuments.

Strukturierte Fehler

API-Fehler verwenden einen einheitlichen JSON-Umschlag: maschinenlesbarer code, lokalisierte message zur Anzeige und optionale details für Validierungsfelder. Mappen Sie die Codes in Ihrer Integrationsschicht; parsen Sie keinen englischen Meldungstext.

Verwandte Seiten

• Authentifizierung
• API-Referenz
• MCP-Tools
• Entwickler-Überblick