So prüfen Sie Property-Werte in Orbit: Muster-, Längen- und Bereichsregeln, Sperren eines Werts nach der ersten Eingabe, Pflichtwerte und die externe Prüfung, die die Entscheidung an einen HTTPS-Endpunkt in Ihrem Betrieb übergibt, mit dem vollständigen Anfrage- und Antwortvertrag für Integratoren.
War dieser Artikel hilfreich?
Keine Antwort gefunden?
Fragen Sie Luna oder schreiben Sie unserem Support-Team.
Note
Wertregeln prüfen einen Property-Wert in dem Moment, in dem er gespeichert wird: gegen ein Muster, eine Länge, einen Bereich oder per HTTPS gegen Ihr eigenes System. Sie weisen den Wert ab, bevor der Datensatz geschrieben wird.
Eine Property enthält Informationen, die für Ihre Organisation wichtig sind: eine interne Referenz, eine Zertifikatsnummer, eine Liefer-ID aus einem anderen System. Orbit prüft schon jetzt, ob ein Wert zum Typ des Felds passt; eine numerische Property nimmt also keine Buchstaben an. Wertregeln gehen weiter. Sie beschreiben, wie ein korrekter Wert aussieht, und Orbit setzt sie bei jedem Schreibvorgang durch: aus Orbit MissionControl, aus Orbit Hub, aus dem CSV-Import und aus der Orbit API gleichermaßen.
Die mächtigste Regel ist die externe Prüfung. Sie übergibt den Wert an einen HTTPS-Endpunkt in Ihrem Betrieb und lässt Ihr eigenes System entscheiden. So bleibt eine ID, die ein Drittsystem verwaltet, maßgeblich: Orbit fragt Ihr System, ob die ID zulässig ist, und legt den Datensatz nicht an, wenn sie es nicht ist.
Wenn Properties für Sie neu sind, beginnen Sie mit Orbit Properties (benutzerdefinierte Felder).
Das Wichtigste:
Regeln liegen auf der Definition der Property, nicht auf einem Formular. Jeder Datensatz mit dieser Property muss also denselben Maßstab erfüllen. Drei Verhaltensweisen sollten Sie kennen, bevor Sie etwas einrichten.
Geprüft werden nur Werte, die sich ändern. Orbit vergleicht, was geschrieben wird, mit dem, was gespeichert ist. Wenn Sie das Zustelldatum eines Shipments ändern, wird seine Referenznummer nicht erneut geprüft, denn dieser Wert hat sich nicht bewegt.
Regeln gelten ab jetzt. Werte, die vor der neuen Regel gespeichert wurden, bleiben genau so, wie sie sind. Geprüft werden sie erst, wenn jemand sie das nächste Mal ändert. Eine strenge Regel auf einer viel genutzten Property kann bestehende Datensätze also nicht kaputt machen. Es heißt aber auch, dass alte Werte die neue Regel womöglich nicht erfüllen.
Prüfungen laufen der Reihe nach und enden beim ersten Fehler. Zuerst kommen die Sperre und die Regel Pflichtfeld, dann die Muster-, Längen- und Bereichsregeln, zuletzt die externe Prüfung. Fällt ein Wert schon an einer einfachen Regel durch, wird Ihr Endpunkt nie aufgerufen. So bleiben offensichtlich fehlerhafte Eingaben von Ihrem System fern.
Regeln gibt es für Properties vom Typ Text und Numerisch. Alle anderen Typen (Checkbox, Auswahl, Mehrfachauswahl, Dokument, Tags) haben keine Wertregeln, lassen sich aber trotzdem sperren. Properties vom Typ Auswahl, Mehrfachauswahl und Tags lassen sich zudem als Pflichtfeld markieren.
| Regel | Gilt für | Was sie tut |
|---|---|---|
| Muster | Text | Der Wert muss vollständig einem regulären Ausdruck entsprechen. Groß- und Kleinschreibung wird unterschieden, keine Flags; Rückwärtsverweise und Lookaround werden nicht unterstützt. |
| Länge | Text | Die Zahl der Zeichen muss zwischen einem Minimum und einem Maximum liegen. Eine der beiden Grenzen genügt. |
| Bereich | Numerisch | Die Zahl muss zwischen einem niedrigsten und einem höchsten Wert liegen. Eine der beiden Grenzen genügt. |
| Externe Prüfung | Text, Numerisch | Der Wert geht an einen HTTPS-Endpunkt in Ihrem Betrieb, der antwortet, ob er angenommen wird. |
Eine Definition kann bis zu zehn Regeln haben, davon höchstens eine externe Prüfung. Ein Muster muss den ganzen Wert treffen: ^INV-\d{4}$ nimmt also INV-0042 an und lehnt Ref INV-0042/b ab.
Nach erster Eingabe sperren macht einen Wert dauerhaft. Sobald er gesetzt ist, lässt er sich auf keinem Weg mehr ändern oder leeren. Um einen gesperrten Wert zu korrigieren, löschen Sie den Datensatz und legen ihn neu an. Das ist Absicht: Bei einer Kennung, die ein anderes System schon erfasst hat, ist eine stille Korrektur in Orbit schlimmer als eine Ablehnung. Die Sperre gibt es für jeden Property-Typ.
Pflichtfeld macht einen Wert verpflichtend. Orbit setzt das auf jedem Weg durch, unabhängig von allen anderen Regeln der Property:
Wie bei jeder Regel bleiben bestehende Datensätze unberührt: Ein Datensatz, der ohne den Wert gespeichert wurde, wird nicht abgelehnt, wenn sich andere Felder darauf ändern.
Die Regel gilt für jeden Datensatz der Typen, an denen die Property hängt, egal wie der Datensatz entsteht. Drei Abläufe legen Datensätze an, ohne ein Eingabefeld für Property-Werte zu bieten; eine Pflicht-Property lehnt sie deshalb ab: das Übernehmen eines Plans aus Orbit Plan, wenn die Property an Touren hängt, das Anlegen eines Return-Shipments, wenn sie an Shipments hängt, und Zeilen eines Structured Data Import, die der Property keine Spalte zuordnen. Ordnen Sie die Property im Import einer Spalte zu. Und bevor Sie eine Property auf Touren oder Shipments, die Orbit für Sie anlegt, zur Pflicht machen, prüfen Sie, ob jeder Ablauf, auf den Sie sich verlassen, den Wert liefern kann.
Pflichtfeld gibt es für Properties vom Typ Text, Numerisch, Auswahl, Mehrfachauswahl und Tags. Für Checkbox- und Dokument-Properties wird es nicht angeboten.
Ein Administrator richtet Regeln in Orbit MissionControl unter Einstellungen → Properties ein. Die Spalte Wertregeln fasst zusammen, was jede Definition durchsetzt. So sehen Sie auf einen Blick, welche Felder geregelt und welche offen sind.
Öffnen Sie die Zelle, um die Regeln zu bearbeiten, oder legen Sie sie gleich beim Anlegen der Property fest. Wählen Sie Regel hinzufügen und dann einen Typ. Angeboten werden nur Regeln, die zum Typ der Property passen; eine ungültige Kombination lässt sich also gar nicht bauen. Der Schalter Pflichtfeld sitzt neben Nach erster Eingabe sperren und erscheint nur bei Property-Typen, die ihn tragen können. Jede Regel hat eine optionale Ablehnungsmeldung, die sieht, wer einen abgelehnten Wert eingibt. Schreiben Sie sie in den Sprachen, die Ihre Operator nutzen, und sagen Sie, wie ein korrekter Wert aussieht. Eine Meldung, die das Format erklärt, erspart eine Supportanfrage.
Ein abgelehnter Wert wird direkt am Feld gemeldet. Wer ihn eingibt, sieht so, welcher Wert falsch ist, und kann ihn an Ort und Stelle korrigieren. Angezeigt wird die Meldung, die Ihr Endpunkt zurückgegeben hat. Gab er keine zurück, nimmt Orbit die Ablehnungsmeldung der Regel und sonst eine Standardmeldung. Ein leer gelassener Pflichtwert wird an seinem Feld als Wert ist erforderlich gemeldet.
Warning
Die Vorprüfung im Transport Composer vor dem Abschicken fragt Ihren Endpunkt nicht. Sie deckt nur die Sperre, die Regel Pflichtfeld und die Muster-, Längen- und Bereichsregeln ab. Ein Wert, den eine externe Prüfung ablehnen wird, besteht sie also trotzdem. Der Endpunkt wird aufgerufen, wenn die Buchung abgeschickt wird.
Das Abschicken läuft im Hintergrund weiter. Die Ablehnung kommt deshalb einen Moment nach dem Klick, nicht sofort. Der Entwurf öffnet sich wieder, mit der Meldung am Feld.
Mit einer externen Prüfung entscheidet Ihr eigenes System über einen Wert. Orbit schickt den Wert beim Speichern an Ihren Endpunkt und setzt die Antwort durch. Dieser Abschnitt beschreibt den Vertrag vollständig. Er richtet sich an alle, die den Endpunkt bauen.
Der Aufruf liegt im Speicherpfad, unmittelbar bevor der Datensatz geschrieben wird. Orbit ruft Ihren Endpunkt auf, wenn ein Wert angelegt oder wirklich geändert wird, und sonst nie. Einen Entwurf anlegen, ihn bearbeiten, die Vorprüfung im Transport Composer und das Auslesen eines Dokuments mit Decode erreichen Ihren Endpunkt nie. Das sind Arbeitsstände; ein Wert dort ist noch an nichts gebunden.
Eine Pflicht-Property, die beim Anlegen leer bleibt, lehnt Orbit schon vor dem Aufruf ab. Ihr Endpunkt erhält für einen neu angelegten Datensatz also nie einen leeren Wert.
Innerhalb eines Speichervorgangs ruft Orbit Ihren Endpunkt einmal pro Wert auf. Landet ein Wert in derselben Buchung auf mehreren Datensätzen, gibt es einen einzigen Aufruf, nicht einen pro Datensatz. Höchstens vier Aufrufe laufen gleichzeitig.
Orbit sendet einen POST mit Content-Type: application/json und diesem Body:
{
"value": "L-2024-118234",
"entityType": "shipment",
"propertyId": "9c1f8e42-5c7a-4a1e-9c0b-2f3d5a7e1b44",
"tenantId": "3a7d1c60-8f42-4c19-b0a5-6e2f9d41c7ab",
"requestId": "0b9d2f83-1a64-4e77-9c31-5d8a0f2b6e14",
"draftId": "f42a7e19-3c85-4b60-a7d2-91e5c0b83d67",
"occurredAt": "2026-09-02T10:15:00.000Z"
}| Feld | Bedeutung |
|---|---|
value | Der Wert genau so, wie er eingegeben wurde, als String oder Zahl. Orbit normalisiert nichts: kein Trimmen, keine Angleichung von Groß- und Kleinschreibung. Ob zwei Werte gleich sind, entscheidet allein Ihr Endpunkt. |
entityType | Der Datensatztyp, auf dem der Wert landet, zum Beispiel shipment, order, tour oder carrier. Nützlich, wenn Sie getrennte Nummernkreise pro Typ führen. |
propertyId | Die ID der Property-Definition. Das ist der stabile Schlüssel für Ihre Regeln. |
tenantId | Die Orbit-Organisation, zu der der Schreibvorgang gehört. |
requestId | Die Kennung dieses Speicherversuchs und Ihr Idempotenzschlüssel. Bleibt über die internen Wiederholungen von Orbit innerhalb eines Versuchs gleich; ist bei jedem erneuten Abschicken neu. |
draftId | Optional. Der Buchungsentwurf, aus dem der Schreibvorgang kommt. Vorhanden beim üblichen manuellen Buchungsweg, fehlt bei direkten API-Schreibvorgängen. Anders als requestId überdauert er ein erneutes Abschicken desselben Entwurfs. |
entityId | Optional. Die ID des geänderten Datensatzes. Fehlt, wenn ein Datensatz angelegt wird, weil es ihn dann noch nicht gibt. Ihre Logik darf nicht davon abhängen. |
occurredAt | ISO-8601-Zeitstempel des Speicherversuchs, in UTC. |
Antworten Sie mit HTTP 200 und einem Urteil. Einen Wert annehmen:
{ "valid": true }Einen ablehnen, optional mit eigener Meldung:
{
"valid": false,
"message": {
"de": "Liefer-ID bereits am 12.05. vergeben (System XY).",
"en": "Delivery id already assigned on 12 May (system XY)."
}
}message ist optional und nach Sprachcode geschlüsselt (de und en). Jede Meldung darf höchstens 500 Zeichen lang sein. Ist sie vorhanden, sieht sie die Person, die den Wert eingibt, statt der in Orbit eingerichteten Ablehnungsmeldung. Es lohnt sich also zu sagen, was schiefging und was zu tun ist. Unbekannte Schlüssel im Body werden ignoriert.
Warning
Das Urteil steckt immer in einer Antwort mit HTTP 200. Ein HTTP-Fehlerstatus ist keine Ablehnung: Er gilt als nicht erreichbarer Endpunkt. Auch das blockiert den Schreibvorgang, meldet dem Nutzer aber einen anderen Grund. Lehnen Sie einen Wert mit 200 und "valid": false ab.
Der Endpunkt muss HTTPS nutzen, und Zugangsdaten dürfen nicht in der URL stehen. Vier Methoden stehen zur Wahl, dieselben wie bei der Zustellung von Webhooks:
| Methode | Was Orbit sendet |
|---|---|
| Keine | Keine Zugangsdaten. Geeignet für einen Endpunkt, der durch eine Netzwerk-Freigabeliste oder Client-Zertifikate geschützt ist. |
| HTTP-Basic-Authentifizierung | Authorization: Basic <base64 of user:password> |
| Bearer-Token | Authorization: Bearer <token> |
| HMAC-Signatur | Der Anfrage-Body wird mit einem gemeinsamen Geheimnis signiert. Orbit sendet die Signatur in X-Signature, zusammen mit X-Signature-Algorithm und X-Signature-Timestamp. Details zur Signatur finden Sie in der Orbit API Reference. |
Geheimnisse lassen sich nur schreiben. Nach dem Speichern liefert jedes Lesen der Definition den Platzhalter __MASKED__ statt des Werts, auch über die Orbit API. Schicken Sie diesen Platzhalter beim Bearbeiten der Definition zurück, bleibt das gespeicherte Geheimnis unverändert. So können Sie die URL oder die Ablehnungsmeldung anpassen, ohne die Zugangsdaten neu einzugeben. Um ein Geheimnis zu wechseln, speichern Sie ein neues und ziehen das alte auf Ihrer Seite zurück.
Orbit gibt Ihrem Endpunkt 5 Sekunden und macht einen Versuch. Es gibt keine Wiederholung. Bleiben Sie deutlich unter diesem Limit, denn die buchende Person wartet auf die Antwort.
Alles außer einer Antwort mit HTTP 200 und einem wohlgeformten Urteil gilt als nicht erreichbarer Endpunkt, und der Schreibvorgang wird abgelehnt. Dazu zählen ein Timeout, ein Netzwerk- oder TLS-Fehler, jeder andere Statuscode, ein Body, der kein JSON ist, ein Urteil in falscher Form, eine Meldung über 500 Zeichen und ein Antwort-Body über 64 KB.
Warning
Weil ein nicht erreichbarer Endpunkt den Schreibvorgang blockiert, entscheidet seine Verfügbarkeit, ob sich diese Buchungen in Orbit überhaupt anlegen lassen. Betreiben und überwachen Sie ihn wie einen produktionskritischen Dienst.
Wenn Ihr Endpunkt Eindeutigkeit durchsetzt, reicht ein einfaches Nachschlagen nicht. Zwischen Ihrer Antwort und dem Schreiben in Orbit liegt eine Lücke, in der Ihr eigenes System dieselbe ID an jemand anderen vergeben könnte. Der Endpunkt muss den Wert in einem einzigen atomaren Schritt prüfen und für sich beanspruchen:
-- holder = draftId when present, otherwise requestId
INSERT INTO claimed_ids (value, holder) VALUES (:value, :holder)
ON CONFLICT DO NOTHING"valid": true."valid": true. So schaden die internen Wiederholungen von Orbit nicht, und mit draftId als Halter schadet auch ein erneutes Abschicken desselben Entwurfs nicht."valid": false, mit einer Meldung.Genauso wichtig: Auch Ihre eigene ID-Vergabe muss über denselben Anspruch laufen. Vergibt ein anderer Teil Ihres Systems IDs, ohne diese Tabelle zu berühren, kann keine Prüfung in Orbit Eindeutigkeit garantieren.
Nehmen Sie draftId als Halter, wo immer er vorhanden ist. Scheitert ein Speichervorgang, nachdem Ihr Endpunkt den Wert schon beansprucht hat, hält der Anspruch eine ID fest, die kein Datensatz nutzt. Mit draftId bringt ein erneutes Abschicken desselben Entwurfs denselben Halter mit und erhält die Antwort „gehört schon Ihnen“. Die Lage löst sich so von selbst. Orbit ruft Ihren Endpunkt nie auf, um einen Anspruch freizugeben. Verwaiste Ansprüche aufzuräumen ist also Sache Ihrer Seite.
Regeln gelten für Schreibvorgänge über die Orbit API genau wie in der Oberfläche. Ein abgelehnter Schreibvorgang antwortet mit HTTP 400 und einem Array issues; jeder Eintrag nennt die betroffene propertyId und einen Code:
| Code | Bedeutung |
|---|---|
validator_failed | Eine Muster-, Längen- oder Bereichsregel wurde nicht erfüllt. |
validator_rejected | Ihr Endpunkt hat "valid": false geantwortet. Derselbe Wert scheitert auch beim nächsten Mal. |
validator_unreachable | Ihr Endpunkt war nicht erreichbar oder hat unbrauchbar geantwortet. Ein neuer Versuch lohnt sich. |
immutable | Der Wert ist gesperrt und bereits gesetzt. |
required | Die Property ist ein Pflichtfeld und blieb beim Anlegen leer, oder der Schreibvorgang wollte ihren gespeicherten Wert leeren. |
Massenanlagen verdienen einen Hinweis. Hat eine Property in einer Massenanfrage für Shipments eine externe Prüfung, stellt Orbit diese Anfrage auf zeilenweise Verarbeitung um: Sie nimmt höchstens 40 Zeilen an, antwortet mit 200 und meldet die Zeilen, die sie nicht anlegen konnte, einzeln, jeweils mit Code und dem Hinweis, ob sich ein neuer Versuch lohnt. Die guten Zeilen werden angelegt. Die Massenanlage von Orders bleibt „alles oder nichts“. Läuft die ganze Anfrage beim Warten auf externe Prüfungen in ein Zeitlimit, antwortet Orbit mit 503, und nichts wird geschrieben.
Orion Industries in Rotterdam bucht seine Lieferungen in Orbit, doch die Liefer-IDs vergibt das Lagersystem, das die Firma seit zehn Jahren betreibt. Dieses System muss die einzige Quelle der Wahrheit bleiben. Ein Administrator legt für Shipments eine Text-Property „Delivery ID“ an und gibt ihr zwei Regeln: ein Muster ^L-\d{4}-\d{6}$, damit ein Tippfehler auffällt, bevor etwas Orbit verlässt, und eine externe Prüfung, die auf https://api.orion-industries.com/orbit/delivery-id zeigt. Die Property ist außerdem nach erster Eingabe gesperrt, denn eine Liefer-ID, die sich ändert, nachdem das Lager sie erfasst hat, würde die Verbindung zwischen beiden Systemen brechen. Und sie ist ein Pflichtfeld, damit kein Shipment ohne ID gebucht wird. Als Julia ein Shipment bucht und L-2024-118234 eintippt, schickt Orbit den Wert an das Lagersystem. Das beansprucht die ID in derselben Transaktion, in der es sie prüft, und antwortet {"valid": true}. Das Shipment wird angelegt. Als eine Kollegin später dieselbe ID erneut verwendet, findet das Lagersystem sie von einer anderen Buchung beansprucht und antwortet {"valid": false} mit „Delivery id already assigned on 12 May“. Julias Kollegin sieht das direkt am Feld.
Note
Die ausführliche API-Referenz von Orbit ist von Orbit Docs getrennt und hier zu finden: Orbit API Reference.
Nein. Regeln gelten für Werte, die ab dem Speichern der Regel geschrieben werden. Bestehende Werte bleiben, wie sie sind, und werden erst geprüft, wenn jemand sie ändert.
Wertregeln gibt es für Properties vom Typ Text und Numerisch. Alle anderen Typen lassen sich trotzdem nach der ersten Eingabe sperren, und Properties vom Typ Auswahl, Mehrfachauswahl und Tags lassen sich als Pflichtfeld markieren.
Ja. Schalten Sie Pflichtfeld auf der Property-Definition unter Einstellungen → Properties in Orbit MissionControl ein. Dann lässt sich kein Datensatz ohne Wert anlegen, und ein gespeicherter Wert lässt sich nicht leeren. Entwürfe können Sie weiterhin ohne ihn speichern.
Beim Anlegen nicht, wenn die Property ein Pflichtfeld ist: Orbit lehnt einen leeren Wert ab, bevor es Ihren Endpunkt aufruft. Ohne den Schalter Pflichtfeld kann ein Datensatz ohne den Wert angelegt werden, und Ihr Endpunkt wird dafür einfach nicht aufgerufen.
Diese Abläufe legen Datensätze an, ohne ein Eingabefeld für Property-Werte zu bieten. Eine Pflicht-Property auf diesem Datensatztyp lehnt sie deshalb ab. Ordnen Sie die Property bei einem Import einer Spalte zu. Bei Plänen und Rücksendungen machen Sie auf diesem Datensatztyp keine Property zur Pflicht.
Der Schreibvorgang wird abgelehnt, und die buchende Person erfährt, dass die externe Prüfung nicht geantwortet hat. Nichts wird angelegt. Das ist Absicht: Einen ungeprüften Wert durchzulassen, würde den Zweck der Prüfung zunichtemachen.
Nein. Er wird beim Abschicken aufgerufen, einmal pro Wert. Entwürfe, Änderungen an Entwürfen, die Vorprüfung im Transport Composer und Werte, die Decode aus einem Dokument liest, erreichen ihn nie.
Diese Prüfung deckt die Sperre, die Regel Pflichtfeld und die Muster-, Längen- und Bereichsregeln ab. Ihren Endpunkt ruft sie nicht auf. Eine externe Prüfung wird erst beim Abschicken der Buchung gefragt. Ein Wert, den sie ablehnt, besteht die frühere Prüfung also.
Nein, eine pro Property-Definition. Sie können sie mit Muster-, Längen- und Bereichsregeln kombinieren, die zuerst laufen.
Nein. Geheimnisse lassen sich nur schreiben, und jedes Lesen liefert __MASKED__. Schicken Sie diesen Platzhalter beim Bearbeiten zurück, um den gespeicherten Wert zu behalten.
Löschen Sie den Datensatz und legen Sie ihn neu an. Ein gesperrter Wert lässt sich auf keinem Weg ändern oder leeren, auch nicht über die Orbit API.