ARIANA ENTERPRISE
Portal Swagger SDK

Documentação Interativa

Guia oficial para fabricantes, distribuidores e ERPs integrarem catálogo, estoque, preço, pedidos, NF-e, XML, DANFE, rastreio e webhooks na Ariana Enterprise.

v1 estável v2 preview

Comece por aqui

A integração pode ser feita por API Key, OAuth 2.0 Client Credentials, SDK oficial ou chamadas HTTP diretas. Para produção, o fabricante precisa concluir a homologação real no Sandbox: o Ariana Enterprise valida evidências das chamadas executadas de verdade antes de permitir a liberação no Admin Enterprise.

Sandbox

Coleções fisicamente separadas de produtos e pedidos. Testes não aparecem na operação real.

Produção

Operação real após aprovação.

SDK

Bibliotecas JavaScript, Node.js, PHP, Python e Java prontas para ERP.

Autenticação

Use x-ariana-key ou Authorization: Bearer.

curl -H "x-ariana-key: ari_live_xxxxx" \ https://ariana-backend.onrender.com/api/v1/enterprise/health

OAuth 2.0

POST /api/v1/enterprise/oauth/token { "grant_type":"client_credentials", "client_id":"ari_client_xxxxx", "client_secret":"ari_secret_xxxxx" }

Ambientes e versionamento

Base estável: /api/v1/enterprise

Próxima versão: /api/v2/enterprise

Use v1 em produção. Use v2 apenas para testes e recursos futuros.

Fluxo recomendado

  1. Solicitar homologação.
  2. Receber API Key Sandbox.
  3. Testar catálogo, estoque, preço, pedido, NF-e e rastreio.
  4. Solicitar a verificação da homologação real; o sistema calcula o score pelas evidências registradas no Sandbox.
  5. Receber liberação de produção.
  6. Ativar webhooks e monitorar consumo.

Endpoints principais

Idempotência de pedidos

Para impedir pedidos duplicados quando o ERP repete uma chamada após timeout, envie sempre externalOrderId único ou o header Idempotency-Key. A mesma chave com o mesmo payload devolve o pedido já criado; a mesma chave com payload diferente retorna conflito.

Idempotency-Key: pedido-erp-2026-000123 { "externalOrderId": "ERP-000123", "items": [...] }

Payloads essenciais

Catálogo

{ "manufacturer":"ariana_moveis", "products":[{"sku":"ARI-0001","name":"Produto Teste","price":2299,"stock":10}] }

Pedido

{ "manufacturer":"ariana_moveis", "externalOrderId":"PED-0001", "customerName":"Cliente Teste", "items":[{"sku":"ARI-0001","qty":1,"unitPrice":2299}] }

Webhooks

Eventos enviados ao ERP do fabricante com HTTPS, assinatura HMAC, delivery ID e timestamp. Em Produção, pedidos pagos podem ser entregues automaticamente ao webhook configurado no Portal. Falhas entram em fila persistente com retry automático e dead-letter após esgotar as tentativas.

Eventos: order_created, payment_approved, invoice_received, tracking_updated, order_cancelled Headers de segurança: X-Ariana-Delivery: evt_... X-Ariana-Timestamp: 1720000000 X-Ariana-Signature-V2: sha256=... Assinatura V2: HMAC-SHA256(secret, timestamp + "." + deliveryId + "." + rawBody) Retry automático: 1 min → 5 min → 15 min → 1 h → 3 h → 6 h

Testador rápido

Clique em Executar para testar.

SDK PHP

Baixe o pacote ZIP oficial e adicione o SDK ao seu projeto. A publicação em registry público deve ser considerada disponível somente quando indicada oficialmente pela Ariana Enterprise.

use ArianaEnterprise\\Client;
$api = new Client(['apiKey' => 'ari_live_xxxxx', 'environment' => 'production']);
$api->catalog()->push([['sku'=>'ARI-0001','name'=>'Produto Teste','price'=>2299,'stock'=>10]]);

Baixar SDK PHP Manifest PHP

SDK Python

Baixe o pacote ZIP oficial e adicione o SDK ao seu projeto Python. A publicação em PyPI será informada oficialmente quando estiver disponível.

from ariana_enterprise import ArianaEnterpriseClient

api = ArianaEnterpriseClient(api_key='ari_live_xxxxx', environment='production')
api.catalog.push([{'sku':'ARI-0001','name':'Produto Teste','price':2299,'stock':10}])

Baixar SDK Python Manifest Python

SDK Java

Baixe o ZIP oficial para integrar ERPs corporativos, Spring Boot, Jakarta EE e aplicações JVM. A publicação em Maven Central será informada oficialmente quando estiver disponível.

ArianaEnterpriseClient ariana = ArianaEnterpriseClient.builder() .apiKey("ari_live_xxxxx") .environment("production") .build(); ariana.catalog().push(List.of( Map.of("sku", "ARI-0001", "name", "Produto Teste", "price", 2299, "stock", 10) ));

Baixar SDK Java Manifest Java

SDK .NET

Baixe o ZIP oficial para integrações C#, ASP.NET Core, Windows Service e ERPs corporativos Microsoft. A publicação em NuGet será informada oficialmente quando estiver disponível.

using ArianaEnterprise; var ariana = new ArianaEnterpriseClient(new ArianaEnterpriseOptions { ApiKey = "ari_live_xxxxx", Environment = "production" }); await ariana.Catalog.PushAsync(products);

Baixar SDK .NET Manifest .NET

Códigos de erro

401Chave ausente ou inválida
429Rate limit excedido
500Erro interno ou falha temporária

Checklist de homologação

Antes da produção, validar:

Catálogo Estoque Preço Pedido NF-e XML DANFE Rastreio Webhook Cancelamento Devolução/RMA

A produção só é liberada com score 100%, calculado a partir de evidências reais da integração do parceiro.