Guarda direcciones. Usa solo lo necesario.

Cómo empezar

Contrata el plan DEV, inicia sesión con Microsoft en el portal y vincula la compra. Solicita la preparación; confirma organización, contrato, Vault, aplicaciones, permisos y conservación antes de aprobar y activar. Prueba con datos ficticios. La compra no crea automáticamente el entorno ni concede acceso a datos. Acuerda por separado el uso en producción.

Antes de conectar

Acuerde con OneNym el contrato, la organización, el tenant del Vault, los IDs de las aplicaciones comercial y de reparto, la finalidad, los campos y la retención. Obtenga el origen HTTPS de la API, API application ID y directory tenant ID. La web y el portal de compra no son la API. La compra requiere configuración y aprobación posteriores.

Use tokens Bearer de aplicación de Microsoft Entra: Managed Identity en Azure o una clave privada de certificado para obtener el token. Esto no es mTLS. El Vault actual confía en un solo directorio Entra; otras organizaciones no se admiten automáticamente. Mantenga las credenciales en el 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>

Ejecutar el ejemplo local

Solicite a OneNym el paquete con el código del SDK y el ejemplo. Extráigalo en una carpeta nueva. Requiere .NET 10 SDK, PowerShell 7 y acceso a NuGet. Los comandos verifican 18 operaciones con datos ficticios sin cuenta Azure. SQLite, claves y autenticación locales son exclusivos del ejemplo, no sustituyen los controles del servicio. Se usa el SDK incluido, sin suponer una publicación en 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

Del pedido a la entrega

1. 01 / REGISTER

   Registra la dirección mediante la API autenticada. Vault la cifra y devuelve un ID proxy impredecible. Evita conservar copias en servidores y registros de la aplicación.

2. 02 / REFERENCE

   Guarda el pedido y el ID proxy en tu base de datos. El ID no es una dirección ni una autorización. La integración no borra las copias existentes: planifica su migración y eliminación.

3. 03 / AUTHORIZE

   Vincula pedido, ID proxy, aplicación destinataria, campos y vencimiento. Emite un token con límite de usos. Poseerlo no basta para acceder.

4. 04 / RETRIEVE

   Autentica la aplicación y comprueba organización, pedido, finalidad, campos, vencimiento, usos y contrato. Los campos autorizados se devuelven en texto claro; controla también las copias del destinatario.

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

Estos ejemplos explican el diseño. Los nombres y valores de los campos son ilustrativos, no una referencia de API ejecutable.

La implementación descifra la dirección completa en memoria y devuelve solo los campos permitidos. No es cifrado por campo. Gestione el texto recibido y los registros y almacenamiento anteriores al registro.

Operaciones de API y SDK

Todas las operaciones requieren Bearer de aplicación y permisos. El canje también requiere X-OneNym-Retrieval-Token. Use JSON UTF-8 y finalidad shipping. GET, revocación y DELETE no llevan cuerpo. El fragmento supone clientes merchant y carrier autenticados, persistedKey guardada antes del registro y orderReference sin datos personales. Use el paquete para un programa ejecutable.

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

Campos, caducidad y usos

Se admiten los siete campos indicados. countryCode contiene dos letras mayúsculas; el cuerpo JSON admite 16.384 bytes. La retención inicial máxima es de 30 días, según la configuración. El token vence antes que la dirección y el pedido, y como máximo 15 minutos tras emitirse. La API admite maxUses de 1 a 5; el SDK estándar usa uno. La caducidad usa segundos UTC y excluye el instante límite. No se verifica la existencia ni la entregabilidad de la dirección.

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

Correcciones, pedidos y revocación

Registre otra dirección; no se modifica la existente. Consulte el vínculo actual, pase su Version como expectedVersion, cambie el pedido y emita un token para la nueva versión. El cambio bloquea todos los tokens de versiones anteriores. Emitir otro en la misma versión no revoca los anteriores. Compruebe otros pedidos y la retención antes de borrar la dirección antigua. El texto ya recibido no puede recuperarse.

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.

Errores y resultados desconocidos

El SDK no reintenta automáticamente. Un timeout, cancelación o 503 puede producirse tras guardar o consumir el token. Confirme el resultado de cada operación antes de repetirla.

400 / 413 / 415

Revise datos, propiedades JSON duplicadas o desconocidas, tipos y fechas. 400 indica entrada inválida; 413, cuerpo excesivo; 415, formato no admitido. No cambie los valores silenciosamente para reenviar.

401 / 403 / 404

Revise identidad, audience, permisos, campos, finalidad y contrato. 404 también oculta recursos ajenos, revocados o borrados; no demuestra su existencia ni ausencia.

409

Revise caducidad, usos, versión y conflicto de clave de idempotencia. Consulte el vínculo y resuelva la concurrencia. No sustituya claves ni emita tokens nuevos automáticamente.

429 / Retry-After

Se alcanzó un límite configurado. Respete Retry-After, limite la concurrencia y decida si puede repetir la operación. No garantiza capacidad ni tiempo de espera.

SDK / 503

SDK 408/timeout_outcome_unknown, 0/transport_unavailable, 502/invalid_response, cancelación y API 503 pueden dejar el resultado desconocido. Recupere un registro solo con la misma clave guardada, cuerpo y caducidad originales. El comprobante dura como máximo 24 horas o hasta la retención de la dirección. Consulte el binding del pedido. No se puede recuperar el token original; compruebe el reparto antes de reemitir o revocar.

Indique estado HTTP, hora y trace ID si dispone de él. No envíe direcciones, Bearer, claves privadas ni tokens de reparto al soporte.

Alcance implementado y verificado

Se implementan registro, consulta limitada por campos, pedidos versionados, emisión, usos, revocación, eliminación y limpieza por caducidad. Las pruebas del SDK, SQL aislado y Azure real con MI, Key Vault, Azure SQL e historial cubren casos normales, denegaciones, concurrencia y recuperación. Quedan la compra y consentimiento reales de otra organización y las notificaciones reales de suspensión/reactivación de Microsoft. No constituyen un SLA ni garantizan todas las capacidades.

FAQ

Diseños técnicos relacionados