Mandanten- und quellsystembezogene External IDs
External IDs sind nach Mandant und Quellsystem scoped. Dieselbe External ID kann in unterschiedlichen Mandanten existieren, ohne geteilt zu werden.
Grenzen des Customer Mapping
External IDs sind sicherer als Freitext-Matching, weil sie eine deterministische Beziehung zwischen Quellsystemen und Ordinavo-Kundendatensätzen erhalten.
Kundenbezogene Importe
Ordinavo Connect kann Kunden-, Standort- und Kontaktdaten aus externen Systemen empfangen und importierte Jobs dem richtigen Kundenkontext zuordnen.
Mapping-Warnungen
Mapping-Warnungen werden genutzt, wenn ein automatisches Match unsicher oder mehrdeutig ist, statt stillschweigend den falschen Kunden zu verknüpfen.
Kontrolliertes Create-/Update-Verhalten
Auto-Create- und Update-Verhalten hängt von Integrationseinstellungen, Feature-Gates und kundenbezogenen Scopes ab.
CustomerNumber gehört zum Ordinavo-Kundendatensatz. Sie ist keine separate operative Target-Kennung.
API-Keys und Scopes
Integrationsclients sollten den kleinsten Scope-Satz nutzen, der für ihren Workflow erforderlich ist. Customer Mapping und Auto-Create-Verhalten benötigen explizite kundenbezogene Scopes.
| Scope | Zweck |
|---|---|
targets.write |
Erforderlich, um Targets zu importieren. |
customers.map |
Erforderlich, um eingehende Datensätze mit bestehenden Ordinavo-Kundenreferenzen zu verknüpfen. |
customers.write |
Erforderlich für Auto-Create- oder Auto-Update-Verhalten. |
customers.read |
Erforderlich, um detaillierte Mapping-Objekte und Customer-Mapping-Ergebnisse zu erhalten. |
Sicherheitshinweise für Integrationen
- API-Keys sollten als Secrets behandelt werden.
- Scopes begrenzen, was ein Integrationsclient tun kann.
- Customer Mapping und Auto-Create erfordern explizite kundenbezogene Scopes.
- Consumer sollten Webhook-Signaturen prüfen, bevor sie Events verarbeiten.
- Webhook-Empfänger sollten nur die Daten speichern, die sie benötigen.
Import-Transparenz
ImportJobs und ImportItems können Mapping-Status, Warnungen und Fehler speichern, damit Operations- und Partnerteams nachvollziehen können, was passiert ist, ohne breiten internen Zugriff zu benötigen.
| Bereich | Beschreibung |
|---|---|
| ImportJobs | Speichern Accepted-, Processing-, Failed- oder Completed-Status für Batches und Einzelimporte. |
| ImportItems | Halten Status je Item, External IDs, Validierungsfehler und Mapping-Diagnosen. |
| Mapping-Status | Zeigt, ob Kunden-, Standort- oder Kontaktkontext gemappt, erstellt, aktualisiert, übersprungen oder fehlgeschlagen ist. |
| Mapping-Warnungen | Machen nicht-fatale Probleme sichtbar, etwa mehrdeutige Treffer, fehlende Koordinaten oder deaktivierte Auto-Create-Regeln. |
| Webhook-Zustellungen | Protokollieren Zustellversuche, Antwortcodes und technische Metadaten für operative Transparenz. |
CustomerContext in ausgehenden Events
Wenn ein gemappter Job zu Besuchsbericht-, Follow-up- oder Billing-Trigger-Events führt, können Webhook-Payloads CustomerContext enthalten, damit externe Systeme Ordinavo-Events wieder mit eigenen Kunden-, Standort- und Kontaktstammdaten verbinden können.
Kontaktdetails, Zusammenfassungsvorschauen und Billing-Details sollten nur für Endpoints aktiviert werden, die sie benötigen.
Billing-Trigger-Events sind strukturierte Signale
Ordinavo kann freigegebene, abrechnungsrelevante Besuchsberichte als Billing-Trigger-Events markieren. Diese Events sollen externe ERP-, Accounting- oder Billing-Systeme informieren, dass ein abgeschlossener Besuch für nachgelagerte Abrechnung relevant sein kann.
Ordinavo erstellt in diesem Workflow keine Rechnungen. Billing-Details in Webhook-Payloads sollten nur für Endpoints aktiviert werden, die sie benötigen.
Importe testbar und nachvollziehbar machen
Externe Entwickler sollten einen kundenbezogenen Job importieren, das Mapping-Ergebnis prüfen, eine Route Suggestion anfordern und signierte Webhook-Events empfangen können.