API atual/Referência completa/Página do produto: conversão

Experimentos A/B

Cria, lista, inicia, acompanha, para e encerra com vencedor os testes A/B da página do produto.

Um experimento A/B mostra duas versões de um elemento da página do produto a grupos diferentes de visitantes e compara quantos adicionam ao carrinho e compram em cada grupo. A versão A é a atual da loja; a B é a nova. As seis rotas desta página cobrem o ciclo inteiro: criar, listar, iniciar, ver os números, parar e aplicar o vencedor.

Exigem o privilégio manage_settings.

Listar experimentos

GET/api/v1/admin/pdp-experimentsAdmin

Listar os experimentos, mais novos primeiro

Devolve 50 por página, ordenados do mais novo para o mais antigo.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

bash

curl "$BASE_URL/api/v1/admin/pdp-experiments" \
  -H "Authorization: Bearer $TOKEN"

200Experimentos

json

{
  "experiments": [
    {
      "id": "d8bb22a1-31b6-4534-9de1-f50399a70696",
      "name": "Botão Comprar agora",
      "element_key": "cta_label",
      "variant_b_value": "buy_now",
      "scope_category_ids": null,
      "split_percent": 50,
      "status": "completed",
      "winner": "b",
      "started_at": "2026-07-20T14:59:07.205942Z",
      "ended_at": "2026-07-20T19:51:26.765153Z",
      "created_at": "2026-07-20T14:59:02.867881Z",
      "updated_at": "2026-07-20T19:51:26.765153Z"
    }
  ]
}

Campos da resposta

experiments[].iduuid

Id do experimento.

experiments[].namestring

Nome.

experiments[].element_keystring

cta_labelsocial_proof_badgesprice_history_badgereviews_position

Elemento testado.

experiments[].variant_b_valuestring

Valor da versão B (por exemplo buy_now para o texto do botão).

experiments[].scope_category_idsarray

Categorias cujos produtos entram na contagem de carrinho e pedidos do teste. null ou vazio: o catálogo todo.

experiments[].split_percentinteger

Porcentagem de visitantes que vê a versão B.

experiments[].statusstring

draftrunningcompletedstopped

Estado.

experiments[].winnerstring

ab

Vencedor. Presente só em completed.

experiments[].started_atstring

Quando foi iniciado, RFC 3339. Ausente em draft.

experiments[].ended_atstring

Quando terminou ou foi parado. Ausente enquanto não termina.

experiments[].created_atstring

RFC 3339, UTC.

experiments[].updated_atstring

RFC 3339, UTC.

Criar um experimento

POST/api/v1/admin/pdp-experimentsAdmin

Criar um experimento (começa em rascunho)

Cria o experimento em draft. Ninguém vê a versão B até você iniciá-lo.

Corpo da requisição

element_keystringobrigatório

cta_labelsocial_proof_badgesprice_history_badgereviews_position

Elemento a testar.

variant_b_valuestring

Valor da versão B. Livre; o significado depende do elemento.

namestring

Nome. Vazio usa o element_key.

split_percentintegerpadrão: 50

De 1 a 99. Fora disso vale 50.

scope_category_idsarray

Ids de categoria cujos produtos entram na contagem de carrinho e pedidos do teste. Vazio considera o catálogo todo.

bash

curl -X POST "$BASE_URL/api/v1/admin/pdp-experiments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Botão Comprar agora","element_key":"cta_label","variant_b_value":"buy_now","split_percent":50}'

201Experimento criado

json

{
  "id": "d8bb22a1-31b6-4534-9de1-f50399a70696",
  "name": "Botão Comprar agora",
  "element_key": "cta_label",
  "variant_b_value": "buy_now",
  "scope_category_ids": null,
  "split_percent": 50,
  "status": "draft",
  "created_at": "2026-10-11T22:20:00Z",
  "updated_at": "2026-10-11T22:20:00Z"
}

Iniciar

PUT/api/v1/admin/pdp-experiments/{id}/startAdmin

Iniciar um experimento em rascunho

Passa o experimento de draft para running. Só pode haver um experimento em andamento por elemento. Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do experimento.

bash

curl -X PUT "$BASE_URL/api/v1/admin/pdp-experiments/d8bb22a1-31b6-4534-9de1-f50399a70696/start" \
  -H "Authorization: Bearer $TOKEN"

200Iniciado

json

{ "started": true }

Ver as estatísticas

GET/api/v1/admin/pdp-experiments/{id}/statsAdmin

Funil por variante e o veredito estatístico

Devolve, para cada variante, quantos visitantes viram a versão (exposições), adicionaram ao carrinho, compraram e quanto geraram de receita, mais a significância (confiança de que a diferença não é acaso) e se já é seguro declarar um vencedor.

Parâmetros de caminho

iduuidobrigatório

Id do experimento.

bash

curl "$BASE_URL/api/v1/admin/pdp-experiments/d8bb22a1-31b6-4534-9de1-f50399a70696/stats" \
  -H "Authorization: Bearer $TOKEN"

200Estatísticas

json

{
  "variants": [
    { "variant": "a", "exposures": 20, "add_to_carts": 9, "orders": 0, "revenue_cents": 0, "conversion_rate": 0 },
    { "variant": "b", "exposures": 22, "add_to_carts": 8, "orders": 0, "revenue_cents": 0, "conversion_rate": 0 }
  ],
  "significance": 0,
  "can_declare_winner": false
}

Campos da resposta

variants[].variantstring

ab

Variante.

variants[].exposuresinteger

Visitantes que viram a variante.

variants[].add_to_cartsinteger

Adições ao carrinho.

variants[].ordersinteger

Pedidos.

variants[].revenue_centsinteger

Receita desses pedidos, em centavos.

variants[].conversion_ratenumber

Pedidos divididos por exposições (0 a 1).

significancenumber

Confiança estatística de que as variantes diferem, de 0 a 1.

can_declare_winnerboolean

true quando cada variante tem ao menos 200 exposições e a significância é de 0,95 ou mais.

Parar

PUT/api/v1/admin/pdp-experiments/{id}/stopAdmin

Parar um experimento em andamento, sem vencedor

Muda running para stopped e devolve todos os visitantes à versão A. Não faz nada em experimentos que não estão em andamento, nem acusa erro para um id que não existe. Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do experimento.

bash

curl -X PUT "$BASE_URL/api/v1/admin/pdp-experiments/d8bb22a1-31b6-4534-9de1-f50399a70696/stop" \
  -H "Authorization: Bearer $TOKEN"

200Parado

json

{ "stopped": true }

Aplicar o vencedor

PUT/api/v1/admin/pdp-experiments/{id}/apply-winnerAdmin

Encerrar o experimento declarando um vencedor

Declara a ou b vencedor, marca o experimento como completed e, se a B venceu, grava a configuração real quando o elemento tem uma:

`element_key`	Se a B vence
`social_proof_badges`	Liga os selos de vendidos em 30 dias e de estoque baixo.
`price_history_badge`	Liga o selo de histórico de preço.
`cta_label`, `reviews_position`	Nada é gravado (são só ajustes de exibição do teste). O experimento é encerrado e a vitrine volta à versão A.

Se a A vence, nada muda na configuração. A rota não confere se já há amostra suficiente: use can_declare_winner das estatísticas.

Parâmetros de caminho

iduuidobrigatório

Id do experimento.

Corpo da requisição

winnerstringobrigatório

ab

A variante vencedora.

bash

curl -X PUT "$BASE_URL/api/v1/admin/pdp-experiments/d8bb22a1-31b6-4534-9de1-f50399a70696/apply-winner" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"winner":"b"}'

200Vencedor aplicado

json

{ "applied": true }

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON (criar e aplicar).	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
404	`apply-winner` num experimento que não existe.	`{"error":"experiment not found"}`
409	`start` quando já há um em andamento para o elemento.	`{"error":"an experiment for this element is already running"}`
409	`start` em experimento que não é rascunho (inclui id inexistente).	`{"error":"experiment is not a draft"}`
422	Criar com `element_key` desconhecido.	`{"error":"invalid element_key"}`
500	`winner` diferente de `a` ou `b`; `{id}` que não é UUID; falha interna.	`{"error":"failed to apply winner","detail":"winner must be 'a' or 'b'"}`

Veja também

API atual/Referência completa/Página do produto: conversão

Experimentos A/B

Cria, lista, inicia, acompanha, para e encerra com vencedor os testes A/B da página do produto.

Exigem o privilégio manage_settings.

Listar experimentos

GET/api/v1/admin/pdp-experimentsAdmin

Listar os experimentos, mais novos primeiro

Devolve 50 por página, ordenados do mais novo para o mais antigo.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

bash

curl "$BASE_URL/api/v1/admin/pdp-experiments" \
  -H "Authorization: Bearer $TOKEN"

200Experimentos

json

{
  "experiments": [
    {
      "id": "d8bb22a1-31b6-4534-9de1-f50399a70696",
      "name": "Botão Comprar agora",
      "element_key": "cta_label",
      "variant_b_value": "buy_now",
      "scope_category_ids": null,
      "split_percent": 50,
      "status": "completed",
      "winner": "b",
      "started_at": "2026-07-20T14:59:07.205942Z",
      "ended_at": "2026-07-20T19:51:26.765153Z",
      "created_at": "2026-07-20T14:59:02.867881Z",
      "updated_at": "2026-07-20T19:51:26.765153Z"
    }
  ]
}

Campos da resposta

experiments[].iduuid

Id do experimento.

experiments[].namestring

Nome.

experiments[].element_keystring

cta_labelsocial_proof_badgesprice_history_badgereviews_position

Elemento testado.

experiments[].variant_b_valuestring

Valor da versão B (por exemplo buy_now para o texto do botão).

experiments[].scope_category_idsarray

Categorias cujos produtos entram na contagem de carrinho e pedidos do teste. null ou vazio: o catálogo todo.

experiments[].split_percentinteger

Porcentagem de visitantes que vê a versão B.

experiments[].statusstring

draftrunningcompletedstopped

Estado.

experiments[].winnerstring

ab

Vencedor. Presente só em completed.

experiments[].started_atstring

Quando foi iniciado, RFC 3339. Ausente em draft.

experiments[].ended_atstring

Quando terminou ou foi parado. Ausente enquanto não termina.

experiments[].created_atstring

RFC 3339, UTC.

experiments[].updated_atstring

RFC 3339, UTC.

Criar um experimento

POST/api/v1/admin/pdp-experimentsAdmin

Criar um experimento (começa em rascunho)

Cria o experimento em draft. Ninguém vê a versão B até você iniciá-lo.

Corpo da requisição

element_keystringobrigatório

cta_labelsocial_proof_badgesprice_history_badgereviews_position

Elemento a testar.

variant_b_valuestring

Valor da versão B. Livre; o significado depende do elemento.

namestring

Nome. Vazio usa o element_key.

split_percentintegerpadrão: 50

De 1 a 99. Fora disso vale 50.

scope_category_idsarray

Ids de categoria cujos produtos entram na contagem de carrinho e pedidos do teste. Vazio considera o catálogo todo.

bash

curl -X POST "$BASE_URL/api/v1/admin/pdp-experiments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Botão Comprar agora","element_key":"cta_label","variant_b_value":"buy_now","split_percent":50}'

201Experimento criado

json

{
  "id": "d8bb22a1-31b6-4534-9de1-f50399a70696",
  "name": "Botão Comprar agora",
  "element_key": "cta_label",
  "variant_b_value": "buy_now",
  "scope_category_ids": null,
  "split_percent": 50,
  "status": "draft",
  "created_at": "2026-10-11T22:20:00Z",
  "updated_at": "2026-10-11T22:20:00Z"
}

Iniciar

PUT/api/v1/admin/pdp-experiments/{id}/startAdmin

Iniciar um experimento em rascunho

Passa o experimento de draft para running. Só pode haver um experimento em andamento por elemento. Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do experimento.

bash

curl -X PUT "$BASE_URL/api/v1/admin/pdp-experiments/d8bb22a1-31b6-4534-9de1-f50399a70696/start" \
  -H "Authorization: Bearer $TOKEN"

200Iniciado

json

{ "started": true }

Ver as estatísticas

GET/api/v1/admin/pdp-experiments/{id}/statsAdmin

Funil por variante e o veredito estatístico

Parâmetros de caminho

iduuidobrigatório

Id do experimento.

bash

curl "$BASE_URL/api/v1/admin/pdp-experiments/d8bb22a1-31b6-4534-9de1-f50399a70696/stats" \
  -H "Authorization: Bearer $TOKEN"

200Estatísticas

json

{
  "variants": [
    { "variant": "a", "exposures": 20, "add_to_carts": 9, "orders": 0, "revenue_cents": 0, "conversion_rate": 0 },
    { "variant": "b", "exposures": 22, "add_to_carts": 8, "orders": 0, "revenue_cents": 0, "conversion_rate": 0 }
  ],
  "significance": 0,
  "can_declare_winner": false
}

Campos da resposta

variants[].variantstring

ab

Variante.

variants[].exposuresinteger

Visitantes que viram a variante.

variants[].add_to_cartsinteger

Adições ao carrinho.

variants[].ordersinteger

Pedidos.

variants[].revenue_centsinteger

Receita desses pedidos, em centavos.

variants[].conversion_ratenumber

Pedidos divididos por exposições (0 a 1).

significancenumber

Confiança estatística de que as variantes diferem, de 0 a 1.

can_declare_winnerboolean

true quando cada variante tem ao menos 200 exposições e a significância é de 0,95 ou mais.

Parar

PUT/api/v1/admin/pdp-experiments/{id}/stopAdmin

Parar um experimento em andamento, sem vencedor

Muda running para stopped e devolve todos os visitantes à versão A. Não faz nada em experimentos que não estão em andamento, nem acusa erro para um id que não existe. Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do experimento.

bash

curl -X PUT "$BASE_URL/api/v1/admin/pdp-experiments/d8bb22a1-31b6-4534-9de1-f50399a70696/stop" \
  -H "Authorization: Bearer $TOKEN"

200Parado

json

{ "stopped": true }

Aplicar o vencedor

PUT/api/v1/admin/pdp-experiments/{id}/apply-winnerAdmin

Encerrar o experimento declarando um vencedor

Declara a ou b vencedor, marca o experimento como completed e, se a B venceu, grava a configuração real quando o elemento tem uma:

`element_key`	Se a B vence
`social_proof_badges`	Liga os selos de vendidos em 30 dias e de estoque baixo.
`price_history_badge`	Liga o selo de histórico de preço.
`cta_label`, `reviews_position`	Nada é gravado (são só ajustes de exibição do teste). O experimento é encerrado e a vitrine volta à versão A.

Se a A vence, nada muda na configuração. A rota não confere se já há amostra suficiente: use can_declare_winner das estatísticas.

Parâmetros de caminho

iduuidobrigatório

Id do experimento.

Corpo da requisição

winnerstringobrigatório

ab

A variante vencedora.

bash

curl -X PUT "$BASE_URL/api/v1/admin/pdp-experiments/d8bb22a1-31b6-4534-9de1-f50399a70696/apply-winner" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"winner":"b"}'

200Vencedor aplicado

json

{ "applied": true }

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON (criar e aplicar).	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
404	`apply-winner` num experimento que não existe.	`{"error":"experiment not found"}`
409	`start` quando já há um em andamento para o elemento.	`{"error":"an experiment for this element is already running"}`
409	`start` em experimento que não é rascunho (inclui id inexistente).	`{"error":"experiment is not a draft"}`
422	Criar com `element_key` desconhecido.	`{"error":"invalid element_key"}`
500	`winner` diferente de `a` ou `b`; `{id}` que não é UUID; falha interna.	`{"error":"failed to apply winner","detail":"winner must be 'a' or 'b'"}`