保存地址，按需使用。

如何開始

訂閱 DEV 方案，以 Microsoft 帳戶登入入口網站並連結購買，接著申請準備。確認組織、合約、Vault、應用權限與保留期限，核准並啟用後使用虛擬資料測試。購買不會自動建立環境或授予資料權限。正式環境使用條件另行確認。

連線前的準備

與 OneNym 確認購買合約、使用組織、Vault 租用戶、商家與配送應用程式 ID、用途、允許欄位及保留期限。取得 API HTTPS origin、API application ID 與 directory tenant ID。網站和購買入口不是 API 位址。購買後仍需設定與核准。

使用 Microsoft Entra 應用程式 Bearer token。Azure 可用 Managed Identity，憑證方式以私密金鑰驗證應用程式並取得權杖，並非傳輸層 mTLS。目前 Vault 信任一個 Entra 目錄，不會自動支援其他組織。認證資料僅置於後端。

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

   訂單資料庫保存訂單編號與代理 ID。ID 不是地址，也不是查詢權限。串接不會自動刪除現有副本，仍需遷移與清理。

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。使用 UTF-8 JSON，目的為 shipping。GET、撤銷與 DELETE 不帶主體。範例假設 merchant 與 carrier 已驗證、persistedKey 已於註冊前儲存、orderReference 不含個人資料。可執行程式請使用範例套件。

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

欄位、到期與使用次數

支援下列七個地址欄位。countryCode 為兩個大寫字母；JSON 主體上限 16,384 位元組。初始最長保留期限為 30 天，以部署設定為準。配送權杖不得晚於地址或訂單到期，核發後最長 15 分鐘。API maxUses 為 1–5，標準 SDK 為一次。依 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。已核發的原始權杖無法再次讀取；先核對配送處理，再決定重發或撤銷。

聯絡支援時提供 HTTP 狀態、時間及可用的 trace ID。不要傳送地址主體、Bearer、憑證私密金鑰或配送權杖。

已實作與驗證的範圍

已實作註冊、限定欄位擷取、版本化訂單變更、配送權杖核發與次數限制、撤銷、刪除及到期清理。SDK、隔離 SQL 及真實 Azure MI、Key Vault、Azure SQL 與歷程儲存驗證正常流程、拒絕存取、並行與故障復原。其他組織實際購買與同意、Microsoft 實際暫停與恢復通知仍待驗收。這不構成正式 SLA 或所有設定的容量保證。

FAQ

相關技術設計