Integre o provador de joias ao seu e-commerce, ERP ou plataforma

O Provador de Joias deixa o cliente final experimentar a joia em si mesmo, direto na página do produto — sem instalar app. A integração vai de 1 tag de script (sem cadastrar produtos) até uma API REST completa com sincronização de catálogo para ERPs.

1. Conceitos e autenticação

Cada joalheria (loja) é um tenant com um par de chaves, disponível no painel em Integração & API:

Base da API: https://api.provadordejoias.com.br. Cada prova consome 1 unidade da cota mensal do plano da loja. Se estiver integrando várias lojas (ERP/plataforma), cada loja tem o próprio par de chaves.

2. Widget — início rápido (sem cadastrar produtos)

O caminho recomendado: o botão envia a foto do produto do próprio e-commerce. Na primeira prova, o produto é registrado automaticamente na plataforma (find-or-create idempotente) — zero sincronização de catálogo. Cole no template da página de produto:

<script src="https://provadordejoias.com.br/widget.js"></script>

<button data-pvj-api-key="pk_SUA_CHAVE"
        data-pvj-image="URL_DA_FOTO_DO_PRODUTO"
        data-pvj-name="NOME_DO_PRODUTO"
        data-pvj-type="ring">
  Prove em você ✨
</button>

Atributos suportados

* use data-pvj-image OU data-pvj-product-ref.

3. Personalização (cores da loja)

O provador veste as cores da joalheria: accent pinta botões, tags e barras; bg muda o fundo da interface. O contraste do texto é calculado automaticamente (cores escuras recebem texto claro e vice-versa). O topo exibe o nome da joalheria, e um selo discreto “Tecnologia Provador de Joias” identifica a plataforma.

<!-- por atributos -->
<button data-pvj-api-key="pk_..." data-pvj-image="..."
        data-pvj-accent="#1C3F78" data-pvj-bg="#0A1428">Prove em você</button>

// ou pelo SDK
PVJWidget.init({ apiKey: "pk_...", theme: { accentColor: "#1C3F78", bgColor: "#0A1428" } });

4. SDK JavaScript

O widget.js (11 KB, zero dependências) expõe window.PVJWidget:

PVJWidget.init({
  apiKey: "pk_...",
  theme: { accentColor: "#1C3F78", bgColor: "#0A1428" },
  onTryOn: (data) => {            // prova concluída → mande pro seu analytics
    gtag('event', 'try_on', { product: data.product_id });
  },
  onOpen: () => {}, onClose: () => {}, onError: (e) => {},
});

// Abrir SEM cadastro (a foto do e-commerce vira produto automaticamente):
PVJWidget.open({ imageUrl: fotoDoSku, name: nomeDoProduto, jewelryType: "necklace" });

// Ou por referência de produto já sincronizado:
PVJWidget.open("REF-DO-PRODUTO");

PVJWidget.close();

// Cota da loja (esconda o botão quando esgotar):
const { available, used, limit } = await PVJWidget.availability();

// Eventos globais: pvj:open · pvj:tryon · pvj:close
window.addEventListener('pvj:tryon', (ev) => console.log(ev.detail));

5. Para ERPs e plataformas — API REST

Tudo o que o widget faz também está disponível como REST — para integrações server-side, apps próprios ou catálogos white-label.

5.1 Sincronizar o catálogo (webhook de produtos)

Dispare a cada created / updated / inactive de produto no seu sistema. Upsert idempotente por reference (o SKU do seu ERP). Requer a chave secreta — somente server-side.

POST https://api.provadordejoias.com.br/widget/products/sync
Authorization: Bearer pk_SUA_CHAVE
X-Api-Secret: sk_SUA_CHAVE_SECRETA
Content-Type: application/json

{
  "event": "updated",                  // created | updated | inactive
  "reference": "COL-RIV-001",          // SKU (chave do upsert)
  "name": "Colar Riviera Ouro 18k",
  "jewelry_type": "necklace",          // opcional
  "image_url": "https://cdn.sualoja.com.br/col-riv-001.jpg"
}

→ 200 { "success": true, "reference": "COL-RIV-001", ... }

Depois disso, o botão do widget pode usar só data-pvj-product-ref="COL-RIV-001".

5.2 Registrar produto pela foto (find-or-create)

Alternativa sem sincronização: troque a URL da foto por um product_id. Idempotente por URL — pode chamar a cada pageview e cachear o resultado.

POST /widget/products/resolve
Authorization: Bearer pk_SUA_CHAVE
Content-Type: application/json

{ "image_url": "https://cdn.sualoja.com.br/anel.jpg",
  "name": "Anel Solitário", "jewelry_type": "ring" }

→ 201 { "success": true, "product_id": "uuid", "created": true }
→ 200 { "success": true, "product_id": "uuid", "created": false }   // já existia

5.3 Executar uma prova (fluxo completo)

# 1) Foto do cliente (multipart) — ou use uma URL http(s) que você já tenha
POST /widget/tryon/upload            (campo "photo": jpg/png/webp, máx 12MB)
→ { "success": true, "url": "https://..." }

# 2) Criar a prova
POST /widget/products/{product_id}/tryon
Content-Type: application/json
{ "person_image_url": "https://...",
  "product_image_url": "https://..." }   // opcional: foto da variação exibida
→ 201 { "success": true, "tryon_id": "uuid", "status": "processing" }

# 3) Acompanhar (poll a cada 2,5s — resultado típico em 30–60s, via webhook)
GET /widget/tryons/{tryon_id}
→ { "status": "completed", "result_image_url": "https://..." }

# Cota da loja (para esconder o botão quando esgotar)
GET /widget/availability
Authorization: Bearer pk_SUA_CHAVE
→ { "available": true, "used": 12, "limit": 300 }

5.4 Página de prova embedável

Cada produto tem uma página de prova autocontida — use como link (WhatsApp, catálogo) ou em iframe (o widget faz exatamente isso):

GET https://api.provadordejoias.com.br/widget/try-on/{product_id}
  ?embed=1            // modo iframe (postMessage pvj:* pro pai)
  &accent=1C3F78      // cor de destaque (hex sem #)
  &bg=0A1428          // cor de fundo (hex sem #)
  &img=https%3A%2F%2F...   // opcional: foto da variação exibida

Tipos de peça (jewelry_type)

Valores aceitos:

Quando omitido, o tipo é detectado por palavras-chave no nome (“Colar…”, “Anel…”, “Brinco…” — PT e EN).

6. Erros, limites e boas práticas

• Webhook-first: o resultado chega em ~30–60s; o poll de 2,5s só reflete o estado.
• Cacheie o product_id do resolve (é estável por URL de imagem).
• Fotos de produto com fundo limpo e peça visível geram os melhores resultados.
• Use availability para esconder o botão quando a cota esgotar (o widget também mostra aviso amigável).
• Multi-loja (ERP): armazene o par pk_/sk_ por loja; nunca compartilhe o sk_ com o navegador.