Widde API para parceiros

01 Como funciona

A integração da Widde com parceiros depende de uma liberação prévia do nosso time. Cada parceiro recebe acesso a uma ou mais lojas autorizadas e a uma chave de API exclusiva — ambos gerados pela Widde.

Fluxo de onboarding

1. Solicitação de acesso — o parceiro abre contato com o time da Widde indicando qual loja deseja integrar.
2. Liberação dos identificadores — o time libera o acesso à loja no painel. A partir desse momento o collectionAppId de cada coleção daquela loja passa a aparecer na listagem de coleções, viabilizando a leitura via API.
3. Geração da chave de API — o time gera a x-partner-key exclusiva do parceiro. É essa chave que autentica todas as chamadas (veja autenticação).
4. Entrega — o parceiro recebe da Widde dois itens para começar: o domínio da loja autorizada (no formato charth.com.br — sem https:// e sem www.) e a chave de API.

02 Conceito

A integração divide a experiência em duas camadas com responsabilidades claras: o parceiro entrega a casca visual dentro do app, e a Widde entrega o conteúdo que vai dentro de cada widget.

Termos visuais

Antes de seguir, vale alinhar os termos que aparecem o tempo todo na documentação e na API. A coleção é o container; cada vídeo dentro dela é um story, que pode ser renderizado como GIF (preview nos widgets) ou em fullscreen (player completo). E o produto é o item da loja vinculado ao story.

O que o parceiro desenvolve

A aplicação do parceiro implementa os widgets visuais dos formatos das soluções (veja os formatos) — a bolinha flutuante na tela da loja, as miniaturas dentro da página de produto (PDP), os ícones em listas de categorias ou produtos, o carrossel de coleções. Cada widget é desenhado e renderizado pelo próprio app, seguindo a identidade visual da loja.

O que a Widde entrega

Para popular esses widgets, a Widde fornece três peças. Todas são acessadas a partir do collectionAppId — o identificador público de cada coleção, liberado pelo time conforme descrito em Como funciona.

1. Listagem de coleções por página — via API REST (Pages Partner V1 / V2) o app sabe quais coleções aparecem em cada URL da loja e recupera o collectionAppId correspondente.
2. Preview em GIF — para cada widget renderizado, o app chama o CDN de GIFs passando o collectionAppId e recebe a imagem inicial daquela coleção. É esse GIF que o usuário vê dentro da bolinha flutuante, do destaque na PDP ou em cada card do carrossel.
3. Player em fullscreen — quando o usuário toca em um widget, o app abre cdn.widde.io/app num WebView (veja Coleção fullscreen). A Widde renderiza a experiência completa — vídeos, navegação entre coleções, drawer de produto e CTA de compra — com as características padrão configuradas pelo lojista no painel.

03 Video Commerce · Formatos

A Widde disponibiliza quatro formatos de widget de vídeo que podem ser distribuídos pela loja. Cada formato tem um papel diferente — bolinha flutuante, fileira de destaques na home, miniaturas dentro da PDP e carrossel de coleções — e pode ser customizado visualmente pelo lojista.

Posicionamento na página

Os formatos aparecem em posições específicas do e-commerce. O Highlight e o Carousel costumam ocupar o topo da home e páginas de categoria; o Story fica flutuando fixo no canto inferior esquerdo, acompanhando o scroll; os destaques de produto ficam embutidos na PDP.

Mapeamento ViewType → Formato

Shape do vídeo · shapper.type

Independente do formato do widget, o lojista escolhe a forma do recorte do vídeo no painel da Widde. Esse valor chega no objeto styles.{ViewType}.shapper.type da API V2 e deve ser aplicado como máscara do preview.

As quatro opções aparecem no painel do lojista sob o título "Escolha o formato". A escolha afeta apenas o preview do vídeo (bolinhas flutuantes, cards, etc.) — o player fullscreen é sempre retangular.

04 Provador AI

A Widde também oferece o Provador AI — uma solução que permite ao cliente visualizar como a peça fica em seu próprio corpo antes da compra. O fluxo abre direto na página de produto, com upload de foto e geração da imagem com IA.

05 Live Commerce

Transmissões ao vivo dentro do e-commerce com chat em tempo real, cupons de desconto, destaque de produto sincronizado e contagem de espectadores. A live ocupa o banner principal da loja e se transforma em mini-player flutuante ao scroll.

Componentes da experiência

06 Explorar

Página completa cheia de vídeos no estilo explore do Instagram. Estimula a descoberta de produtos e funciona em duas variantes: um preview compacto embutido na home (ou em qualquer categoria) e a página dedicada com busca e abas de categoria.

Variantes

Componentes da experiência

07 Autenticação

Todas as chamadas para a API exigem o header x-partner-key. O token é emitido pela Widde durante o onboarding e identifica unicamente cada parceiro autorizado.

 x-partner-key: <SUA_PARTNER_KEY> Content-Type: application/json 

Retorna as coleções de uma loja em formato flat (apenas IDs, sem configurações visuais). Mantido por compatibilidade com integrações antigas — para qualquer integração nova, vá direto para a V2.

 curl -X GET "https://api-admin.widde.io/api/v1/partner/pages?domain=charth.com.br" \
  -H "x-partner-key: <SUA_PARTNER_KEY>" \
  -H "Content-Type: application/json" 

 const response = await fetch(
'https://api-admin.widde.io/api/v1/partner/pages?domain=charth.com.br',
{method: 'GET',
headers: {'x-partner-key': '<SUA_PARTNER_KEY>',
'Content-Type': 'application/json',
},
}
);
if (!response.ok) {throw new Error('HTTP error ' + response.status);
}const data = await response.json();

{
  "collections": {
    "bata-dalia-amarelo-angu-1/p": {
      "Story": "H6sCpJ1tDyW"
    },
    "bata-rebeca-off-1/p": {
      "Story": "M7vXqA4kZsB"
    }
  }
}

Versão recomendada. Além das collections, retorna o objeto styles com configurações visuais por tipo de widget (Carousel, Highlight, Story…) — assim você renderiza no app exatamente o que o lojista configurou no painel.

Exemplo de resposta completa

{
  "collections": {
    "legging-atletika-bolso-cos-1/p": {
      "Highlight": { "id": "K9aZb3NcRfH", "title": "Destaques da página" },
      "Carousel":  { "id": "Q4dGhV7uPxL", "title": "Mais vendidos" }
    },
    "charth.com.br": {
      "Carousel": { "id": "T2rBwY8eMnK", "title": "Home — campanhas" }
    }
  },
  "styles": {
    "Carousel": {
      "colors":  { "primary": null, "secondary": null },
      "shapper": { "type": "rectangle", "style": "default", "rounded": 15, "borderWidth": 0 },
      "wrapper": { "type": "product", "variant": "default", "position": "bottom", "redirectTo": "none" },
      "playRule": { "type": "PlayCenter" },
      "carouselTitle": {
        "font": "Arial", "show": false, "size": 20,
        "color": "#000000", "isBold": false
      },
      "block": {
        "mobile": {
          "gap": 16, "size": 250, "type": "carousel",
          "align": "safe center", "marginTop": 16
        }
      }
    },
    "Highlight": {
      "colors":  { "primary": null, "secondary": null },
      "shapper": { "type": "circle", "style": "border", "rounded": 8, "borderWidth": 3 },
      "playRule": { "type": "PlayAll" },
      "block": {
        "mobile": { "gap": 16, "size": 100, "type": "highlight", "marginTop": 16 }
      }
    }
  }
}

Referência · collections

Referência · styles

10 V1 vs V2

Mesma autenticação, mesma URL base — a V2 só estende o payload com styles. A migração geralmente é trocar o path e desserializar a resposta como objeto em vez de string.

Retorna o conteúdo completo de uma coleção: título, lista de stories ordenadas (mesma ordem do app oficial) e os produtos vinculados a cada story. Útil quando o parceiro quer renderizar a experiência fora do cdn.widde.io/app — em apps mobile nativos ou em UIs próprias.

Exemplo de chamada

curl -H "x-partner-key: <SUA_PARTNER_KEY>" \
https://api-admin.widde.io/api/v2/partner/collections/charth.com.br/ZgfM4pSWdR0 

Exemplo de resposta

{
  "title": "Lookbook Verão",
  "stories": [
    {
      "key": "cd813cec-71a8-4dc0-8d45-1e7f9e914c8b",
      "gif": "https://videos.widde.io/widde-bucket-sp/.../gif.mp4",
      "products": [
        {
          "title": "Camisa Linho Areia",
          "mainImage": "https://cdn.loja.com.br/images/camisa-linho.jpg",
          "price": 199.9,
          "comparePrice": 249.9,
          "url": "https://charth.com.br/produto/camisa-linho-areia",
          "handler": "camisa-linho-areia"
        }
      ]
    },
    {
      "key": "9f7c0f8e-3a72-4f3b-90d1-2b1f2d2b8a55",
      "gif": "https://videos.widde.io/widde-bucket-sp/.../gif.mp4",
      "products": []
    }
  ]
}

Exemplo de uso

Com a resposta acima o parceiro consegue montar a visualização completa da coleção dentro do próprio app, com identidade visual própria — sem precisar abrir o WebView de cdn.widde.io/app. Os mesmos dados do exemplo (Lookbook Verão) renderizados como uma tela de seleção de stories num app fictício:

Referência · raiz

Referência · stories[]

Referência · stories[].products[]

Erros mais comuns

12 GIFs / Previews

Vídeos otimizados que alimentam os widgets de qualquer solução (Story, Highlight, Carousel e demais formatos). A Widde serve cada preview pronto para o player nativo — você só precisa do domain e do collectionAppId, junto com o header x-partner-key.

Primeiro GIF da coleção

curl -H "x-partner-key: <SUA_PARTNER_KEY>" \
https://api-admin.widde.io/api/v2/partner/gif/charth.com.br/N5fLgU2wPyD 

Listar todos os GIFs da coleção

curl -H "x-partner-key: <SUA_PARTNER_KEY>" \
https://api-admin.widde.io/api/v2/partner/gif/charth.com.br/N5fLgU2wPyD/list 

13 Coleção em fullscreen

Para carregar a experiência completa da Widde dentro do app parceiro, abra a URL do CDN num WebView passando domain, collectionAppId e partnerPublicKey.

 https://cdn.widde.io/app?domain=charth.com.br&collectionAppId=N5fLgU2wPyD&partnerPublicKey=R8mKjT3xQbV 

Abrindo em um story específico

Por padrão, a URL acima abre a coleção no primeiro story. Isso funciona bem quando o widget que originou o clique tem apenas um preview (a bolinha flutuante, por exemplo). Mas quando o app já mostra vários previews ao mesmo tempo — carrosséis, grids, listas — o usuário escolhe qual quer assistir tocando em um card específico, e abrir sempre no primeiro vídeo quebra a expectativa: ele toca no terceiro card e vê o primeiro story.

Para resolver isso, basta acrescentar o parâmetro storyKey ao final da URL — com o valor do campo key retornado para cada item de stories[] no Collection Partner V2:

 https://cdn.widde.io/app?domain=charth.com.br&collectionAppId=N5fLgU2wPyD&partnerPublicKey=R8mKjT3xQbV&storyKey=9f7c0f8e-3a72-4f3b-90d1-2b1f2d2b8a55 

Como é a experiência renderizada

Quando o usuário clica em qualquer widget (Story, Highlight, Carousel…), essa URL é aberta em fullscreen e renderiza o player completo da Widde — com barra de progresso, controles laterais, legenda do vídeo e drawer de produto com CTA de compra.

Drawer de compra

Ao tocar em Adicionar produto, a Widde abre dentro do mesmo WebView um drawer com a versão completa do produto: galeria, variações disponíveis, quantidade, descrição e CTA de adicionar ao carrinho. As variações sem estoque aparecem com tarja diagonal e ficam não selecionáveis. Quando o cliente confirma, dispara o postMessage add_to_cart para o app nativo com o SKU selecionado e a quantidade.

Para integrar o Provador AI dentro do app parceiro, o fluxo tem dois passos: (1) consultar o endpoint de configuração para saber se a loja tem o Provador AI ativo e receber a iframeUrl pronta; (2) abrir essa URL num WebView quando o usuário tocar no botão "Como fica em mim?". Toda a experiência — upload da foto, geração com IA, drawer de produto e CTA de compra — é renderizada pela Widde.

Visão geral do fluxo

1. App consulta GET /api/v2/partner/tryon/config passando o domain da loja e a product-image da PDP atual.
2. Se a resposta vier com allowed: false, o app não exibe o botão. Não tente abrir a WebView nesse caso — o acesso é bloqueado e a tela fica em branco.
3. Se allowed: true, o app exibe o botão e, ao tocar, abre a iframeUrl retornada diretamente num WebView (sem montá-la manualmente).
4. Quando o usuário toca em Adicionar ao carrinho dentro do provador, a Widde dispara o postMessage add_to_cart para a bridge nativa do app — o mesmo contrato usado pelo player de coleção.

Query params

Exemplo de chamada

curl -H "x-partner-key: <SUA_PARTNER_KEY>" \
"https://api-admin.widde.io/api/v2/partner/tryon/config?domain=iorane.com.br&product-image=https%3A%2F%2Fiorane.com.br%2Farquivos%2Fcamisa-01.jpg&product-name=Camisa%20Kenia%20-%20On%C3%A7a" 

Cenários de resposta

{
  "allowed": true,
  "config": {
    "buttonText": "Como fica em mim?",
    "primaryColor": "#000000"
  },
  "iframeUrl": "https://cdn.widde.io/app?mode=tryon&domain=iorane.com.br&product-image=https%3A%2F%2Fiorane.com.br%2Farquivos%2Fcamisa-01.jpg&product-name=Camisa%20Kenia%20-%20On%C3%A7a"
}

{
  "allowed": false,
  "reason": "no_subscription",
  "config": null,
  "iframeUrl": null
}

{
  "allowed": false,
  "reason": "subscription_canceled",
  "config": null,
  "iframeUrl": null
}

{
  "allowed": true,
  "config": null,
  "iframeUrl": "https://cdn.widde.io/app?mode=tryon&domain=iorane.com.br&product-image=https%3A%2F%2Fiorane.com.br%2Farquivos%2Fcamisa-01.jpg&product-name=Camisa%20Kenia%20-%20On%C3%A7a"
}

Referência · resposta

Motivos para allowed: false

Erros HTTP

Comportamento recomendado no app

 const response = await fetch(
'/api/v2/partner/tryon/config' +
'?domain=' + domain +
'&product-image=' + encodeURIComponent(productImage) +
'&product-name=' + encodeURIComponent(productName),
{headers: {'x-partner-key': PARTNER_KEY }}
);
const data = await response.json();
if (!data.allowed) { return;
} openWebView(data.iframeUrl);

WebView · referência informativa

A WebView do Provador AI é servida em https://cdn.widde.io/app. Não monte essa URL manualmente — use sempre a iframeUrl retornada pelo endpoint, que já vem com os parâmetros corretos. Os campos abaixo aparecem apenas para fins de debug ou inspeção.

Configurações da WebView

15 Carrinho · postMessage

Ao clicar em "adicionar ao carrinho" dentro do player, o evento atravessa a ponte WebView → nativo. O app parceiro recebe o payload e fica responsável por concluir a operação no ambiente da loja.

 app.callback({action: 'add_to_cart',
items: [
{sku: "12345",  productId: "ABC123",  sellerId: "1",  variants:  ["P", "Azul"],  quantity: 2  }
]
});

 webkit.messageHandlers.callback.postMessage({action: 'add_to_cart',
items: [
{sku: "12345",
productId: "ABC123",
sellerId: "1",
variants:  ["P", "Azul"],
quantity: 2 }
]
});

Parâmetros do payload

16 Fluxo resumido

Da abertura da coleção ao checkout, o ciclo de vida da experiência Widde no app parceiro tem quatro etapas — cada uma usa um endpoint ou ponte documentado nas seções anteriores.

1. 01

   App parceiro solicita a coleção

   Via URL cdn.widde.io/app?domain=&collectionAppId= aberta num WebView.

2. 02

   Widde carrega o componente

   O componente busca os dados da coleção pela API interna usando o collectionAppId.

3. 03

   Bolinhas flutuantes renderizadas

   Com base na resposta de /gif/.../list — o usuário vê o carrossel de previews.

4. 04

   Interação e adição ao carrinho

   O player completo abre. Ao adicionar ao carrinho, o postMessage add_to_cart é disparado para o app nativo.

17 Status codes

Todas as respostas seguem semântica HTTP padrão. Erros vêm em JSON com statusCode, message e error.

401 · token ausente ou inválido

{
  "statusCode": 401,
  "message": "Token is required for partner requests",
  "error": "Unauthorized"
}

404 · empresa não encontrada

{
  "statusCode": 404,
  "message": "Company not found",
  "error": "Not Found"
}

500 · erro interno do servidor

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

18 Ambientes

A Widde opera em ambiente único de produção. Para testes pré-go-live, a equipe emite uma x-partner-key de homologação que aponta para uma loja de exemplo.

19 Contato

Time dedicado a parceiros: dúvidas técnicas, emissão de partner-key e homologação de novas integrações. Resposta em até um dia útil.