住所を預けて、必要なときだけ使う。

利用を始めるには

MarketplaceのDEVプランを申し込み、OneNymポータルへMicrosoftアカウントでログインして購入を連携します。続いて利用準備を申請します。対象組織・契約・Vault・接続アプリ・権限・保持期間を確認し、準備承認と有効化を経てダミーデータでAPI連携を検証します。購入だけで環境や権限が自動作成される仕組みではありません。本番利用の範囲と条件は導入時に確認します。

接続前に用意するもの

OneNymと、購入契約・利用組織・Vault内のテナント・販売者と配送アプリのID・用途・許可項目・保持期限を対応づけます。APIのHTTPS origin、API application ID、directory tenant IDを受け取ってください。このWebサイトや購入ポータルのURLを、APIの接続先には使いません。購入後の設定と承認が必要です。

認証にはMicrosoft Entraのアプリ用Bearer tokenを使います。Azure上ではManaged Identity、証明書方式では秘密鍵でアプリを認証してtokenを取得します。証明書は通信路のmTLS認証ではありません。現行Vaultが信頼するEntraディレクトリは1つで、他組織のIDをそのまま使えるとは限りません。資格情報はバックエンドだけに置きます。

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>

手元で導入サンプルを動かす

OneNymからSDKソースとサンプルのパッケージを受け取り、新しいフォルダーへ展開します。.NET 10 SDK、PowerShell 7、NuGetへの接続が必要です。下のコマンドはAzureアカウントなしでダミーデータの18操作を確認します。ローカル専用の認証・SQLite・鍵を使い、実サービスの契約と認証を省略する手順ではありません。SDKは同梱ソースを参照し、公開NuGetからの配布は前提にしません。

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

注文から配送までのデータの流れ

1. 01 / REGISTER

   住所を認証済みAPIからVaultへ登録します。暗号化して保存し、推測しにくい代理IDを返します。登録元の入力画面・サーバー・ログにも住所が残らないよう、連携経路を設計します。

2. 02 / REFERENCE

   注文DBには注文番号と代理IDを保存します。代理IDは住所そのものでも取得権限でもありません。既存DBの住所は、連携を変えただけでは消えないため、移行・削除も必要です。

3. 03 / AUTHORIZE

   注文と代理ID、取得する配送アプリ、項目、期限を結び付けます。その注文に対して利用回数を制限した取得トークンを発行します。トークンを持つだけでは利用できません。

4. 04 / RETRIEVE

   配送アプリ自身を認証し、組織・注文・用途・項目・期限・利用回数・契約状態を確認して取得します。許可された項目は平文で返るため、配送先での保管やログも管理が必要です。

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

以下は設計を説明するためのサンプルです。フィールド名・値は例示で、実行用のAPIリファレンスではありません。

現行実装は住所レコード全体をメモリー内で復号し、許可された項目だけを応答へ取り出します。項目別暗号化ではありません。取得後の平文と、登録前に通過する顧客システムのログ・保管は別途管理が必要です。

APIとSDKの対応

全操作でアプリ用Bearer tokenと必要な権限を確認します。配送取得には追加でX-OneNym-Retrieval-Tokenが必要です。JSONはUTF-8、用途はshippingです。GET・失効・DELETEには本文を付けません。以下のコードは、認証済みのmerchantとcarrier、登録前に保存したpersistedKey、個人情報を含まないorderReferenceがある前提のSDK呼び出し例です。実行可能な一式は導入サンプルを使ってください。

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);

項目・期限・利用回数

対応する住所項目は以下の7つです。countryCodeは大文字2文字、JSON本文は16,384バイト以下。住所の保持上限は初期30日で、導入先の設定に従います。配送トークンの期限は住所・注文の期限以内かつ発行後15分以内です。APIのmaxUsesは1〜5、標準SDKは1回です。期限はUTCの秒単位で扱い、期限と同時刻から利用できません。住所の実在性や配送可能性は検証しません。

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

住所訂正・注文変更・失効

住所の上書き編集はせず、新しい住所を登録します。現在の注文対応を照会し、そのVersionをexpectedVersionにして注文を変更し、新しい版のトークンを発行します。注文版が変わると旧版の全トークンは使えません。同じ版での追加発行だけでは旧トークンは失効しません。旧住所を使う別注文と保持条件を業務側で確認し、不要な旧住所だけを削除します。変更前に取得済みの平文は回収できません。

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.

エラーと結果が不明なとき

SDKは自動再送しません。タイムアウトやキャンセル、503でも、保存やトークン消費が済んでいる場合があります。失敗応答を「未実行」と決めつけず、操作ごとに結果を確認します。

400 / 413 / 415

入力、JSONの重複・未知項目・型・期限を確認します。400は入力不正、413は本文上限超過、415は非対応の形式です。値を勝手に変更して再送しません。

401 / 403 / 404

認証先・audience・アプリ権限・許可項目・用途・契約を確認します。404には他の利用者のデータや失効・削除済みの対象も含み、存在の証明には使えません。

409

期限・利用回数・注文版・再送キーの不一致などです。注文対応を再照会し、競合を確認します。新しいキーやトークンへの置き換えを自動化しません。

429 / Retry-After

利用上限です。Retry-Afterを尊重して同時処理を抑え、操作を再実行できるか判断します。一定の待ち時間や処理能力を保証する応答ではありません。

SDK / 503

SDKの408/timeout_outcome_unknown、0/transport_unavailable、502/invalid_response、キャンセルとAPIの503は結果不明になり得ます。登録は同じ保存済みキー・元の本文・期限でのみ回収します。登録控えは最大24時間と住所保持期限の早い方までです。注文はbinding照会で確認します。発行済みの生トークンを再取得するAPIはなく、配送処理の重複を確認して再発行・失効を判断します。

問い合わせにはHTTP status・発生時刻・分かる場合はtrace IDを添えてください。住所本文、Bearer、証明書の秘密鍵、配送トークンを送らないでください。

実装・確認済みの範囲

登録・項目を限定した取得・版付き注文変更・配送トークンの発行／利用回数／失効・削除・期限消去を実装しています。SDK、隔離SQL、実AzureのMI・Key Vault・Azure SQL・履歴保存を使い、正常系、権限拒否、競合と障害後の回復を確認しています。実際の別組織による購入・同意と、Microsoftからの実停止／再開通知は受入確認の残件です。これらの検証を本番SLAや全構成の性能保証へ読み替えません。

FAQ

関連する技術設計