Adressen speichern. Gezielt verwenden.

So starten Sie

Buchen Sie den DEV-Plan, melden Sie sich mit Microsoft im Portal an und verknüpfen Sie den Kauf. Beantragen Sie die Einrichtung. Prüfen Sie Organisation, Vertrag, Vault, Anwendungen, Rechte und Aufbewahrung vor Freigabe und Aktivierung. Testen Sie mit Testdaten. Der Kauf erstellt weder automatisch eine Umgebung noch Datenrechte. Produktionsbedingungen werden gesondert vereinbart.

Vor dem Verbinden

Stimmen Sie Vertrag, Organisation, Vault-Mandant, Händler- und Zustell-App-IDs, Zweck, Felder und Aufbewahrung mit OneNym ab. Sie erhalten den HTTPS-Ursprung der API, API application ID und directory tenant ID. Website und Kaufportal sind keine API-Endpunkte. Nach dem Kauf sind Einrichtung und Freigabe erforderlich.

Verwenden Sie Microsoft-Entra-Anwendungs-Bearer-Token: Managed Identity in Azure oder einen privaten Zertifikatsschlüssel zur Tokenanforderung. Das ist keine mTLS-Authentifizierung. Der aktuelle Vault vertraut einem Entra-Verzeichnis; andere Organisationen sind nicht automatisch zugelassen. Zugangsdaten bleiben im Backend.

ONENYM_API_URL=<API HTTPS origin>
ONENYM_API_APPLICATION_ID=<API application ID>
directory tenant ID / merchant client ID / carrier client ID

Authorization: Bearer <application-access-token>

Lokales Integrationsbeispiel ausführen

Fordern Sie SDK-Quellcode und Beispielpaket bei OneNym an und entpacken Sie es in einen neuen Ordner. Benötigt werden .NET 10 SDK, PowerShell 7 und NuGet-Zugriff. Die Befehle prüfen 18 Vorgänge mit Testdaten ohne Azure-Konto. Lokale Authentifizierung, SQLite und Schlüssel dienen nur der Demo und umgehen keine Dienstkontrollen. Der mitgelieferte SDK-Quellcode wird verwendet; ein öffentliches NuGet-Paket wird nicht vorausgesetzt.

dotnet --version
pwsh --version
pwsh -NoProfile -File ./samples/OneNym.Vault.Pilot/run-local.ps1

RESULT passed=True; steps=18; elapsedMs=…; cleanup=True
PASS isolated customer quickstart

Von der Bestellung zur Lieferung

1. 01 / REGISTER

   Registrieren Sie die Adresse über die authentifizierte API. Vault speichert sie verschlüsselt und liefert eine nicht vorhersagbare Proxy-ID. Vermeiden Sie zusätzliche Kopien in Servern und Anwendungslogs.

2. 02 / REFERENCE

   Speichern Sie Bestellung und Proxy-ID in Ihrer Datenbank. Die ID ist weder die Adresse noch eine Abrufberechtigung. Bestehende Kopien werden durch die Integration nicht gelöscht; planen Sie Migration und Löschung.

3. 03 / AUTHORIZE

   Verknüpfen Sie Bestellung, Proxy-ID, Empfängeranwendung, Felder und Ablaufzeit. Stellen Sie ein Token mit Nutzungslimit aus. Das Token allein gewährt keinen Zugriff.

4. 04 / RETRIEVE

   Authentifizieren Sie die Anwendung und prüfen Sie Mandant, Bestellung, Zweck, Felder, Ablauf, Nutzung und Vertrag. Erlaubte Felder werden im Klartext zurückgegeben; auch der Empfänger muss Speicherung und Logs kontrollieren.

POST /v1/addresses
  → proxyId: nym_…

PUT /v1/shipping-orders
  proxyId + orderReference + recipientClientId + fields + expiresAt
  → orderId + version

POST /v1/shipping-orders/{orderId}/grants
  orderVersion + expiresAt + maxUses
  → token: nrt_…

POST /v1/retrieval-grants/redeem
  Authorization: Bearer <application-access-token>
  X-OneNym-Retrieval-Token: <retrieval-token>
  orderId + orderReference + purpose + fields
  → permitted fields

Diese Beispiele erläutern das Konzept. Feldnamen und Werte dienen der Veranschaulichung und sind keine ausführbare API-Referenz.

Die gesamte Adresse wird im Speicher entschlüsselt; nur erlaubte Felder gelangen in die Antwort. Es ist keine Verschlüsselung je Feld. Empfänger müssen Klartext schützen, Kunden auch Protokolle und Speicher vor der Registrierung.

API- und SDK-Vorgänge

Jeder Vorgang benötigt ein Anwendungs-Bearer-Token und Berechtigungen. Zum Einlösen ist zusätzlich X-OneNym-Retrieval-Token erforderlich. Verwenden Sie UTF-8-JSON und den Zweck shipping. GET, Widerruf und DELETE haben keinen Body. Das Fragment setzt authentifizierte merchant- und carrier-Clients, einen vorab gespeicherten persistedKey und eine orderReference ohne personenbezogene Daten voraus. Das Paket enthält das ausführbare Beispiel.

using OneNym.Vault.Client;

var fields = new[] { "recipientName", "postalCode", "addressLine1" };
var registration = await merchant.RegisterAsync(new CreateAddress {
    Address = new AddressData {
        RecipientName = "Demo Recipient", PostalCode = "000-0000",
        CountryCode = "JP", AddressLine1 = "Dummy address",
        Locality = "Demo city"
    },
    RetainUntil = DateTimeOffset.UtcNow.AddDays(1)
}, persistedKey);

var order = await merchant.BindAsync(new BindOrder(
    orderReference, registration.ProxyId, carrierClientId, fields,
    DateTimeOffset.UtcNow.AddHours(1)));
var grant = await merchant.IssueAsync(
    order.OrderId, order.Version, DateTimeOffset.UtcNow.AddMinutes(5));
var address = await carrier.RedeemAsync(
    order.OrderId, orderReference, grant.Token, fields);

Felder, Ablauf und Nutzung

Die sieben Felder stehen unten. countryCode besteht aus zwei Großbuchstaben; JSON ist auf 16.384 Bytes begrenzt. Die anfängliche Aufbewahrungsgrenze beträgt konfigurationsabhängig 30 Tage. Token laufen spätestens mit Adresse und Bestellung sowie binnen 15 Minuten nach Ausstellung ab. API maxUses: 1–5; Standard-SDK: eins. UTC-Sekunden gelten; am Ablaufzeitpunkt wird der Zugriff bereits abgelehnt. Existenz und Zustellbarkeit werden nicht geprüft.

recipientName   1–200
postalCode      1–32
countryCode     [A-Z]{2}
addressLine1    1–300
addressLine2    null / 0–300
locality        1–100
region          null / 0–100

Adresskorrekturen, Bestellungen und Widerruf

Registrieren Sie eine neue Adresse, statt die vorhandene zu bearbeiten. Prüfen Sie die Zuordnung, übergeben Sie deren Version als expectedVersion, ändern Sie die Bestellung und stellen Sie ein Token für die neue Version aus. Alte Versionen werden vollständig gesperrt. Weitere Token derselben Version widerrufen vorhandene Token nicht. Prüfen Sie andere Bestellungen und Aufbewahrung vor dem Löschen. Bereits übermittelter Klartext lässt sich nicht zurückholen.

var current = await merchant.InspectOrderAsync(orderReference);
var changed = await merchant.BindAsync(new BindOrder(
    orderReference, newRegistration.ProxyId, carrierClientId, fields,
    newOrderExpiry, ExpectedVersion: current.Version));
var newGrant = await merchant.IssueAsync(
    changed.OrderId, changed.Version, newGrantExpiry);

// BindOrder = complete desired binding, not a partial patch.
// Keep unknown prior outcomes for reconciliation; never blindly retry.

Fehler und unbekannte Ergebnisse

Das SDK wiederholt nicht automatisch. Timeout, Abbruch oder 503 können nach Speicherung oder Tokenverbrauch auftreten. Prüfen Sie das Ergebnis jedes Vorgangs vor einer Wiederholung.

400 / 413 / 415

Prüfen Sie Eingaben, doppelte oder unbekannte JSON-Felder, Typen und Daten. 400: ungültige Eingabe; 413: zu großer Body; 415: nicht unterstütztes Format. Werte nicht unbemerkt ändern und erneut senden.

401 / 403 / 404

Prüfen Sie Identität, audience, App-Rechte, Felder, Zweck und Vertrag. 404 kann auch fremde, gesperrte oder gelöschte Daten verbergen; es beweist weder Existenz noch Abwesenheit.

409

Prüfen Sie Ablauf, Nutzung, Bestellversion und Idempotenzschlüssel. Lesen Sie die Zuordnung erneut und klären Sie konkurrierende Änderungen. Schlüssel oder Token nicht automatisch ersetzen.

429 / Retry-After

Eine konfigurierte Grenze wurde erreicht. Beachten Sie Retry-After, begrenzen Sie Parallelität und prüfen Sie die Wiederholbarkeit. Wartezeit und Kapazität werden dadurch nicht garantiert.

SDK / 503

SDK 408/timeout_outcome_unknown, 0/transport_unavailable, 502/invalid_response, Abbruch und API 503 können ein unbekanntes Ergebnis hinterlassen. Registrierung nur mit demselben gespeicherten Schlüssel, ursprünglichen Body und Ablauf wiederherstellen. Belege gelten höchstens 24 Stunden oder bis zum früheren Aufbewahrungsende. Bestell-binding prüfen. Rohtoken können nicht erneut gelesen werden; Zustellung vor Neuausstellung oder Widerruf prüfen.

Nennen Sie HTTP-Status, Zeitpunkt und gegebenenfalls trace ID. Keine Adressinhalte, Bearer, privaten Schlüssel oder Zustelltoken an den Support senden.

Implementierter und geprüfter Umfang

Registrierung, begrenzte Feldabfrage, versionierte Bestellungen, Tokenausstellung, Nutzungsgrenzen, Widerruf, Löschung und Ablaufbereinigung sind implementiert. SDK, isoliertes SQL und echtes Azure mit MI, Key Vault, Azure SQL und Historie prüfen Normalfälle, Ablehnung, Konkurrenz und Wiederherstellung. Echter Kauf und Zustimmung einer anderen Organisation sowie echte Microsoft-Sperr-/Fortsetzungsereignisse stehen noch aus. Dies ist kein Produktions-SLA oder Kapazitätsversprechen für jede Konfiguration.

FAQ

Verwandte technische Konzepte