Guarde endereços. Use só o necessário.

Como começar

Assine o plano DEV, entre no portal com a Microsoft e vincule a compra. Solicite a preparação. Confirme organização, contrato, Vault, aplicativos, permissões e retenção antes da aprovação e ativação; teste com dados fictícios. A compra não cria automaticamente um ambiente nem concede acesso a dados. Combine separadamente as condições de produção.

Antes de conectar

Combine com a OneNym o contrato, a organização, o tenant do Vault, IDs dos aplicativos comercial e de entrega, finalidade, campos e retenção. Obtenha a origem HTTPS da API, API application ID e directory tenant ID. O site e o portal de compra não são a API. Configuração e aprovação são necessárias após a compra.

Use tokens Bearer de aplicativo do Microsoft Entra: Managed Identity no Azure ou chave privada de certificado para obter o token. Não é autenticação de transporte mTLS. O Vault atual confia em um diretório Entra; outra organização não é aceita automaticamente. Mantenha as credenciais no 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>

Executar o exemplo local

Solicite à OneNym o pacote com o código-fonte do SDK e o exemplo, extraindo-o em uma pasta nova. São necessários .NET 10 SDK, PowerShell 7 e acesso ao NuGet. Os comandos verificam 18 operações com dados fictícios sem conta Azure. Autenticação, SQLite e chaves locais são apenas para demonstração, não para contornar contratos ou autenticação do serviço. Use o SDK incluído; não se pressupõe distribuição pública no 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

Do pedido à entrega

1. 01 / REGISTER

   Cadastre o endereço pela API autenticada. O Vault o criptografa e retorna um ID imprevisível. Evite também cópias em servidores e logs da aplicação.

2. 02 / REFERENCE

   Guarde o pedido e o ID proxy na sua base. O ID não é o endereço nem uma autorização. Integrar a API não apaga cópias existentes; planeje migração e exclusão.

3. 03 / AUTHORIZE

   Vincule pedido, ID, aplicativo destinatário, campos e validade. Emita um token com limite de uso. Possuir o token não basta para acessar.

4. 04 / RETRIEVE

   Autentique o aplicativo e verifique organização, pedido, finalidade, campos, validade, uso e contrato. Os campos autorizados retornam em texto claro; o destinatário também deve controlar armazenamento e logs.

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

Estes exemplos explicam o projeto. Nomes de campos e valores são ilustrativos, não uma referência executável de API.

A implementação descriptografa o endereço inteiro na memória e retorna somente os campos permitidos. Não é criptografia por campo. Destinatários devem proteger o texto recebido; clientes também devem gerenciar logs e armazenamento anteriores ao cadastro.

Operações da API e do SDK

Toda operação exige Bearer de aplicativo e permissões. O resgate exige também X-OneNym-Retrieval-Token. Use JSON UTF-8 e finalidade shipping. GET, revogação e DELETE não têm corpo. O trecho pressupõe merchant e carrier autenticados, persistedKey salva antes do cadastro e orderReference sem dados pessoais. O pacote contém o aplicativo executável.

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, validade e usos

Os sete campos estão abaixo. countryCode contém duas letras maiúsculas; o corpo JSON admite 16.384 bytes. A retenção máxima inicial é de 30 dias, conforme a configuração. Tokens vencem até a validade do endereço e pedido, no máximo 15 minutos após a emissão. API maxUses: 1–5; SDK padrão: um. A validade usa segundos UTC e exclui o instante final. Não se verifica existência nem possibilidade de entrega do endereço.

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

Correções, pedidos e revogação

Cadastre outro endereço em vez de editar o existente. Consulte o vínculo, passe sua Version como expectedVersion, altere o pedido e emita um token para a nova versão. A mudança bloqueia todos os tokens das versões anteriores. Emitir mais tokens na mesma versão não revoga os existentes. Verifique outros pedidos e a retenção antes de excluir o endereço antigo. Texto já entregue não pode ser recolhido.

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.

Erros e resultados desconhecidos

O SDK não repete automaticamente. Timeout, cancelamento ou 503 podem ocorrer após gravação ou consumo do token. Confira o resultado de cada operação antes de repetir.

400 / 413 / 415

Verifique dados, campos JSON duplicados ou desconhecidos, tipos e datas. 400: entrada inválida; 413: corpo excessivo; 415: formato não aceito. Não altere os valores silenciosamente para reenviar.

401 / 403 / 404

Confira identidade, audience, permissões, campos, finalidade e contrato. 404 também pode ocultar dados de outro proprietário ou recursos revogados ou excluídos; não comprova existência nem ausência.

409

Confira validade, usos, versão e conflito de chave de idempotência. Consulte o vínculo e resolva alterações concorrentes. Não troque chaves nem emita tokens automaticamente.

429 / Retry-After

Um limite configurado foi atingido. Respeite Retry-After, limite a concorrência e avalie se pode repetir a operação. Não garante tempo de espera ou capacidade.

SDK / 503

SDK 408/timeout_outcome_unknown, 0/transport_unavailable, 502/invalid_response, cancelamento e API 503 podem deixar resultado desconhecido. Recupere o cadastro apenas com a mesma chave salva, corpo e validade originais. O comprovante dura até 24 horas ou até o fim da retenção, o que ocorrer primeiro. Consulte o binding do pedido. O token original não pode ser recuperado; confira a entrega antes de reemitir ou revogar.

Informe status HTTP, horário e trace ID se disponível. Não envie endereços, Bearer, chaves privadas de certificado ou tokens de entrega ao suporte.

Escopo implementado e verificado

Cadastro, consulta por campos, pedidos versionados, emissão e usos de tokens, revogação, exclusão e limpeza por validade estão implementados. SDK, SQL isolado e Azure real com MI, Key Vault, Azure SQL e histórico verificam operação normal, recusas, concorrência e recuperação. Compra e consentimento reais de outra organização e notificações Microsoft reais de suspensão/reativação ainda precisam de aceite. Os testes não estabelecem SLA nem capacidade para todas as configurações.

FAQ

Projetos técnicos relacionados