API atual/Referência completa/Conteúdo da vitrine

Anúncios patrocinados

Pede os produtos patrocinados para uma área da vitrine e registra o clique, que cobra do seller que anunciou.

Venddor Ads permite que um seller (lojista) pague para destacar produtos seus em áreas da vitrine, como a busca ou a categoria. Quando a página precisa de anúncios, ela pede os slots (posições patrocinadas); a plataforma faz um leilão entre as campanhas ativas e devolve os vencedores, cada um com um tracking_token. Se o cliente clicar, o front-end avisa a plataforma com esse token e o seller é cobrado.

GET/api/v1/storefront/ads/slotsPública

Pedir os anúncios de uma área

Parâmetros de consulta

surfacestring

Área da vitrine onde os slots vão aparecer (por exemplo home, search, category). Texto livre, gravado no token e nos relatórios; a API não restringe os valores.

qstring

Termo de busca do cliente. Só concorrem produtos cujo nome contém o termo.

category_iduuid

Categoria que o cliente está vendo. Só concorrem produtos dela. Categorias bloqueadas pelo administrador nunca anunciam.

product_iduuid

Produto aberto na página. Só concorre esse produto (útil para anúncio na própria página do produto).

session_idstring

Identificador da sessão do visitante. Se faltar, vale o cabeçalho X-Session-ID. Serve para não cobrar dois cliques da mesma sessão na mesma campanha em 10 minutos.

Exemplo de requisição

bash

curl -G "$BASE_URL/api/v1/storefront/ads/slots" \
  --data-urlencode "surface=search" \
  --data-urlencode "q=cafe" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Slots

json

{
  "slots": [
    {
      "campaign_id": "2f1e0d9c-8b7a-4695-8473-625140f9e8d7",
      "product": {
        "id": "0f6c3b0a-6a52-4c53-8d2c-0e1a1d7a9b21",
        "slug": "cafe-especial-250g",
        "name": "Café Especial 250 g",
        "price_cents": 4990,
        "image_url": "/uploads/produtos/cafe-250.jpg",
        "vendor_name": "Casa do Café"
      },
      "is_sponsored": true,
      "tracking_token": "MmYxZTBkOWMtLi4u.c2lnbmF0dXJh"
    }
  ]
}

Campos da resposta

slotsarray

Anúncios vencedores, no máximo o número de posições configurado pela loja (2 por padrão). [] quando não há anúncio.

slots[].campaign_iduuid

Campanha vencedora.

slots[].product.iduuid

Produto anunciado.

slots[].product.slugstring

Slug para montar o link do produto.

slots[].product.namestring

Nome do produto.

slots[].product.price_centsinteger

Preço em centavos (4990 = R$ 49,90).

slots[].product.image_urlstring

Imagem principal. Pode ser vazia.

slots[].product.vendor_namestring

Nome do seller.

slots[].is_sponsoredboolean

Sempre true. Use para exibir o selo "Patrocinado" (obrigatório para o cliente saber que é anúncio).

slots[].tracking_tokenstring

Token assinado que representa este slot. Envie-o em POST /ads/events. Vale 30 minutos.

Erros

Esta rota não devolve erro de regra: qualquer falha interna volta como 200 com slots vazio.

POST/api/v1/storefront/ads/eventsPública

Registrar o clique em um anúncio

Corpo da requisição

tracking_tokenstringobrigatório

slots[].tracking_token do anúncio clicado.

event_typestringobrigatório

clickimpression

click registra o clique e cobra o seller. impression só registra a exibição, sem cobrança; não use, pois os slots já registram a impressão ao serem servidos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/ads/events" \
  -H "Content-Type: application/json" \
  -d '{"tracking_token":"'"$TRACKING_TOKEN"'","event_type":"click"}'

Resposta

200Evento registrado

json

{ "ok": true }

Campos da resposta

okboolean

Sempre true quando o evento foi aceito.

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	Token ausente, malformado, com assinatura errada, ou expirado (30 minutos).	`{"error":"failed to record event","detail":"invalid token"}` (outros `detail`: `invalid token signature`, `token expired`)
400	`event_type` diferente de `click` e `impression`.	`{"error":"failed to record event","detail":"invalid event_type: x"}`

Veja também

Anúncios patrocinados

Pede os produtos patrocinados para uma área da vitrine e registra o clique, que cobra do seller que anunciou.

GET/api/v1/storefront/ads/slotsPública

Pedir os anúncios de uma área

Parâmetros de consulta

surfacestring

Área da vitrine onde os slots vão aparecer (por exemplo home, search, category). Texto livre, gravado no token e nos relatórios; a API não restringe os valores.

qstring

Termo de busca do cliente. Só concorrem produtos cujo nome contém o termo.

category_iduuid

Categoria que o cliente está vendo. Só concorrem produtos dela. Categorias bloqueadas pelo administrador nunca anunciam.

product_iduuid

Produto aberto na página. Só concorre esse produto (útil para anúncio na própria página do produto).

session_idstring

Identificador da sessão do visitante. Se faltar, vale o cabeçalho X-Session-ID. Serve para não cobrar dois cliques da mesma sessão na mesma campanha em 10 minutos.

Exemplo de requisição

bash

curl -G "$BASE_URL/api/v1/storefront/ads/slots" \
  --data-urlencode "surface=search" \
  --data-urlencode "q=cafe" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Slots

json

{
  "slots": [
    {
      "campaign_id": "2f1e0d9c-8b7a-4695-8473-625140f9e8d7",
      "product": {
        "id": "0f6c3b0a-6a52-4c53-8d2c-0e1a1d7a9b21",
        "slug": "cafe-especial-250g",
        "name": "Café Especial 250 g",
        "price_cents": 4990,
        "image_url": "/uploads/produtos/cafe-250.jpg",
        "vendor_name": "Casa do Café"
      },
      "is_sponsored": true,
      "tracking_token": "MmYxZTBkOWMtLi4u.c2lnbmF0dXJh"
    }
  ]
}

Campos da resposta

slotsarray

Anúncios vencedores, no máximo o número de posições configurado pela loja (2 por padrão). [] quando não há anúncio.

slots[].campaign_iduuid

Campanha vencedora.

slots[].product.iduuid

Produto anunciado.

slots[].product.slugstring

Slug para montar o link do produto.

slots[].product.namestring

Nome do produto.

slots[].product.price_centsinteger

Preço em centavos (4990 = R$ 49,90).

slots[].product.image_urlstring

Imagem principal. Pode ser vazia.

slots[].product.vendor_namestring

Nome do seller.

slots[].is_sponsoredboolean

Sempre true. Use para exibir o selo "Patrocinado" (obrigatório para o cliente saber que é anúncio).

slots[].tracking_tokenstring

Token assinado que representa este slot. Envie-o em POST /ads/events. Vale 30 minutos.

Erros

Esta rota não devolve erro de regra: qualquer falha interna volta como 200 com slots vazio.

POST/api/v1/storefront/ads/eventsPública

Registrar o clique em um anúncio

Corpo da requisição

tracking_tokenstringobrigatório

slots[].tracking_token do anúncio clicado.

event_typestringobrigatório

clickimpression

click registra o clique e cobra o seller. impression só registra a exibição, sem cobrança; não use, pois os slots já registram a impressão ao serem servidos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/ads/events" \
  -H "Content-Type: application/json" \
  -d '{"tracking_token":"'"$TRACKING_TOKEN"'","event_type":"click"}'

Resposta

200Evento registrado

json

{ "ok": true }

Campos da resposta

okboolean

Sempre true quando o evento foi aceito.

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	Token ausente, malformado, com assinatura errada, ou expirado (30 minutos).	`{"error":"failed to record event","detail":"invalid token"}` (outros `detail`: `invalid token signature`, `token expired`)
400	`event_type` diferente de `click` e `impression`.	`{"error":"failed to record event","detail":"invalid event_type: x"}`