Listing
commerce.listingUnifiedEm breveUma página de produto em um marketplace: quanto custa, como se posiciona, o que os compradores dizem e quanto vende, com a loja e a empresa por trás dela.
11 marketplaces5 chamadas planejadas53 camposchave marketplace + ID da página de produtoAmazon e TikTok Shop primeiro
Onde o Listing se encaixa
Variant e Offer- à venda sob uma
Brand - dentro de uma
Category - aparece nas buscas por uma
Keyword - em destaque em um
VideoouLiveStreamde umCreator - pode esbarrar em um
IPRight - loja citada em um
Case
5 chamadas planejadasEm breve
Chamadas do design 0.1.0-draft da API de e-commerce, escritas como caminhos REST. Cada chamada retorna esta entidade em um só formato nas plataformas listadas, e nenhuma está implantada ainda.
- GET
/Uma página de produto com as Variants e Offers que a fonte retornouTikTok Shop · AmazonProjetadav1/ e-commerce/ listings/ {listingId} - GET
/Buscar páginas de produto em um marketplace; cada plataforma tem os próprios filtrosTikTok Shop · AmazonProjetadav1/ e-commerce/ listings/ search - GET
/Encontrar páginas de produto candidatas a partir de uma foto, sem supor que sejam o mesmo itemTikTok Shop · AmazonProjetadav1/ e-commerce/ listings/ search-by-image - GET
/Rankings de mais vendidos por categoria e dataTikTok Shop · AmazonProjetadav1/ e-commerce/ listings/ rankings - GET
/Vídeos que promovem uma página de produtoTikTok ShopProjetadav1/ e-commerce/ tiktok-shop/ listings/ {listingId}/ videos
Campos
Os principais campos por tipo. Os observáveis usam as chaves do contrato; o contrato completo vem a seguir.
Observável
Um snapshot recente; se não houver, uma leitura em tempo real; se não, a próxima fonteCobrança: Quando o valor volta- titlestringQuando o valor volta
- imagesobject[]Quando o valor volta
- related.categoriesuuid[]A categoria mais específica confirmada, na taxonomia do próprio marketplaceQuando o valor volta
- rating.scoredecimal0 pode significar que ainda não há notasQuando o valor volta
- review.countintegerSó avaliações escritas; notas só com estrelas vão para rating.countQuando o valor volta
- lifecycle.launch_datedateA data que a fonte informa, não quando a AIsa viu a página pela primeira vezQuando o valor volta
- relation.shop_iduuidA loja que a publicou. Na Amazon, o vendedor da Oferta em destaque não é considerado o donoQuando o valor volta
- related.offersuuid[]Preço, estoque e entrega ficam em cada OfferQuando o valor volta
- metrics.sales_countdecimalTotal ou de um período, como a fonte conta; duas fontes nunca são somadasQuando o valor volta
- metrics.video_countintegerVídeos que promovem o produto no período, não visualizaçõesQuando o valor volta
Estimado
Um estimador por padrão, até três lado a ladoCobrança: Por consulta- units_sold_30dEstimate[]Últimos 30 dias corridos, só desta variaçãoPor consulta
- gmv_30dEstimate[]Na moeda do marketplace, com a data do câmbioPor consulta
- gmv_7dEstimate[]Pedidos feitos e liquidados contados à partePor consulta
- tiktok.creator_gmv_shareEstimate[]Parcela do GMV que veio por criadoresPor consulta
Verificável
Uma fonte por vez, até que uma resposta passe em uma verificaçãoCobrança: Quando passa na verificaçãoListas e risco
Combinado de várias fontes; um alerta basta para sinalizarCobrança: Por linha45 campos no contrato de camposDesign 0.1.0-draft · listing-contract-v3.2
As chaves dos campos e como cada valor é escrito, conforme o design os define. Só voltam os campos que uma fonte de fato retornou.
Identidade5
O ID da AIsa, a plataforma, o site e o ID da própria plataformaentity.iduuidentity.kindstringentity.platformstringentity.scopestringentity.native_idstring
Página11
Título, link, imagens e o que a página mostratitlestringurlurlimagesobject[]image.cover_urlurldescription.blocksobject[]attributes.listobject[]status.availabilitystringlifecycle.launch_datedatebadgesstring[]affiliate.commission_ratedecimaloption_groupsobject[]
Avaliações5
Número de notas e de avaliações, contados à parterating.scoredecimalrating.countintegerrating.distributionobject[]review.summarystringreview.countinteger
Métricas17
Vendas, GMV e engajamento, cada um no período da sua fontemetrics.sales_countdecimalmetrics.gmvdecimalmetrics.gmv_totaldecimalmetrics.creator_countintegermetrics.video_countintegermetrics.live_countintegermetrics.video_view_countintegermetrics.creator_order_ratedecimalmetrics.gmv_trendobject
Mostrar mais 8 camposMostrar menos
metrics.video_average_views_reporteddecimalmetrics.video_gpm_reporteddecimalmetrics.video_conversion_reporteddecimalmetrics.live_average_viewers_reporteddecimalmetrics.ad_gmv_reporteddecimalmetrics.ad_cost_reporteddecimalmetrics.seller_creator_sales_count_30ddecimalmetrics.seller_creator_gmv_30ddecimal
Vínculos7
IDs da AIsa das entidades para as quais apontarelation.shop_iduuidrelated.variantsuuid[]related.variant_listingsuuid[]related.parent_listingsuuid[]related.child_listingsuuid[]related.offersuuid[]related.categoriesuuid[]
Valores dos tipos decimal e integer chegam como strings para preservar a precisão. Uma chave terminada em _reported é o número da própria fonte, com método de contagem não confirmado; _raw guarda o código bruto da fonte. Campos uuid apontam para outras entidades da AIsa.
Por marketplace
Onde há cinco ou mais estimadores, as vendas voltam lado a lado e passam primeiro pela calibração. Nos demais casos, a cobertura começa com duas fontes comparadas ou com uma fonte identificada como única.
| Marketplace | Chave do Listing | Leituras em tempo real | Estimadores | Estimativas de vendas | Status |
|---|---|---|---|---|---|
| Amazon | amazon:US · ASIN | 4 | 6 | Lado a lado, calibradas | Disponível |
| TikTok Shop | tiktok-shop:US · product_id | 1 | 5 | Lado a lado, calibradas | Disponível |
| Temu | temu:US · goods_id | — | 3 | Lado a lado | Em breve |
| Walmart | walmart:US · item ID | 1 | 2 | Duas comparadas | Em breve |
| Shopee | shopee:SG · item_id | 1 | 2 | Duas comparadas | Em breve |
| Ozon | ozon:RU · SKU | — | 2 | Duas comparadas | Em breve |
| Mercado Libre | mercadolibre:BR · item ID | — | 2 | Duas comparadas | Em breve |
| Etsy | etsy:US · listing_id | 1 | 1 | Fonte única, identificada | Em breve |
| Shopify | shopify:{store} · product ID | — | 1 | Fonte única, identificada | Em breve |
| eBay | ebay:US · item ID | 1 | — | Só leitura em tempo real | Em breve |
| 1688 | 1688:CN · offerId | — | 2 | Listas de fornecedores, combinadas | Em breve |
As contagens vêm da lista de fornecedores da primeira fase. A taxa de preenchimento de cada campo aparece aqui quando cada marketplace estiver disponível.
O que não muda
A AIsa pode trocar as fontes por trás de um campo a qualquer momento. Estes pontos continuam iguais.
- A chave é o ID do próprio marketplace, guardado exatamente como o marketplace o emitiu.
- Um ID emitido pela AIsa nunca é alterado nem reutilizado.
- Duas fontes que contam de forma diferente continuam como duas métricas, e os valores brutos são guardados.
- Campos só são adicionados. Uma mudança de significado sai como nova versão, e a antiga é mantida por um tempo.