API atual/Referência completa/Kits e Compre junto

Compre junto

Lista, minera dos pedidos, cria à mão, ativa, desativa e apaga os combos de Compre junto exibidos na página do produto.

O Compre junto mostra, na página de um produto (a âncora), um ou dois produtos que costumam ser comprados com ele, com um desconto se o cliente levar o conjunto. Cada combo é uma âncora mais 1 ou 2 companheiros. As rotas exigem o privilégio manage_catalog. Para o bloco aparecer na vitrine, o recurso também precisa estar ligado nas configurações da loja, e ao menos 2 itens do combo precisam estar visíveis e com estoque.

Todo combo criado vira um kit ativo de slug fbt-<id do combo>, com o desconto percentual definido nas configurações de Compre junto da loja (padrão 5%). É esse kit que o carrinho usa para aplicar o preço.

GET/api/v1/admin/fbtAdmin

Lista os combos

Do maior lift para o menor, 50 por página. A resposta não traz o total: para saber se há mais páginas, peça a seguinte até vir uma lista vazia.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Cada página tem 50 combos (fixo).

POST/api/v1/admin/fbt/mineAdmin

Minera combos dos pedidos

Recalcula os combos mineráveis a partir dos pedidos bem-sucedidos dos últimos 180 dias. Um par vira combo quando aparece em pelo menos 3 pedidos e em pelo menos 1% dos pedidos que têm a âncora, com os dois produtos do mesmo seller. São no máximo 2 companheiros por âncora, escolhidos pelo lift. Combos criados à mão e combos desativados nunca são alterados; combos minerados ativos que saíram do corte são removidos. Sem pedidos suficientes, nada é criado. A chamada espera o fim da mineração, com limite de 60 segundos. Sem corpo.

POST/api/v1/admin/fbt/manualAdmin

Cria um combo à mão

Cria o combo e o torna ativo. Se já existir um combo com a mesma âncora e os mesmos companheiros, ele é reativado em vez de duplicado.

Corpo da requisição (JSON)

anchor_product_iduuidobrigatório

Produto em cuja página o combo aparece.

companion_idsarrayobrigatório

De 1 a 2 ids de produto. Ids repetidos e o id da âncora são descartados; além de 2, os extras são ignorados.

PUT/api/v1/admin/fbt/{id}/statusAdmin

Ativa ou desativa um combo

Um combo desativado deixa de aparecer na vitrine e fica protegido contra a mineração.

Parâmetros de caminho

iduuidobrigatório

Id do combo.

Corpo da requisição (JSON)

statusstringobrigatório

activedisabled

Novo estado. Aceita só as palavras, não as letras.

DELETE/api/v1/admin/fbt/{id}Admin

Apaga um combo

Apaga o combo. Combos minerados apagados podem voltar na próxima mineração, a menos que você os desative em vez de apagar. O kit fbt-... gerado para o combo não é apagado.

Parâmetros de caminho

iduuidobrigatório

Id do combo.

Exemplo de requisição

bash

# criar à mão
curl -X POST "$BASE_URL/api/v1/admin/fbt/manual" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"anchor_product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","companion_ids":["c4e16aa8-59ba-45f0-aaff-d87549ced120"]}'

# desativar
curl -X PUT "$BASE_URL/api/v1/admin/fbt/$COMBO/status" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

Resposta

200Lista

json

{
  "combos": [
    {
      "id": "11b6f790-c5c2-4f31-94ab-c88c6ecf3bc2",
      "anchor_product_id": "d3602023-101d-4f7d-8ef5-52abd5c7eaaf",
      "anchor_product_name": "Notebook Essencial Bege 02156",
      "companion_ids": ["12658adf-5a62-43c3-8310-73176df91202"],
      "companion_names": ["Óculos Deluxe Preto 02710"],
      "support_count": 3,
      "lift": 2294.25,
      "status": "active",
      "source": "mined",
      "adds_count": 0
    }
  ]
}

200Combo criado

json

{ "id": "c676155b-ddcf-4f62-916c-9cc698654033" }

200Mineração concluída

json

{ "mined": true }

200Status alterado ou combo apagado

json

{ "ok": true }

Campos de cada combo

iduuid

Id do combo.

anchor_product_iduuid

Produto-âncora.

anchor_product_namestring

Nome da âncora.

companion_idsarray

Ids dos companheiros (1 ou 2).

companion_namesarray

Nomes dos companheiros, na mesma ordem.

support_countinteger

Em quantos pedidos o par apareceu. 0 nos combos manuais.

liftnumber

Quanto o par é mais frequente que o acaso (probabilidade conjunta dividida pelo produto das probabilidades). Acima de 1 é associação positiva. 0 nos combos manuais.

statusstring

activedisabled

Estado do combo.

sourcestring

minedmanual

Se veio da mineração ou foi criado à mão.

adds_countinteger

Quantas vezes clientes adicionaram o combo ao carrinho pela vitrine.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `anchor_product_id`	`{"error":"failed to create combo","detail":"anchor_product_id required"}`
400	Nenhum companheiro distinto	`{"error":"failed to create combo","detail":"at least one distinct companion_id required"}`
400	Âncora não existe	`{"error":"failed to create combo","detail":"anchor product not found"}`
400	`status` diferente de `active` e `disabled`	`{"error":"failed to set status","detail":"invalid status"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
500	Falha na mineração	`{"error":"mining failed","detail":"..."}`

Veja também

Compre junto

Lista, minera dos pedidos, cria à mão, ativa, desativa e apaga os combos de Compre junto exibidos na página do produto.

GET/api/v1/admin/fbtAdmin

Lista os combos

Do maior lift para o menor, 50 por página. A resposta não traz o total: para saber se há mais páginas, peça a seguinte até vir uma lista vazia.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Cada página tem 50 combos (fixo).

POST/api/v1/admin/fbt/mineAdmin

Minera combos dos pedidos

POST/api/v1/admin/fbt/manualAdmin

Cria um combo à mão

Cria o combo e o torna ativo. Se já existir um combo com a mesma âncora e os mesmos companheiros, ele é reativado em vez de duplicado.

Corpo da requisição (JSON)

anchor_product_iduuidobrigatório

Produto em cuja página o combo aparece.

companion_idsarrayobrigatório

De 1 a 2 ids de produto. Ids repetidos e o id da âncora são descartados; além de 2, os extras são ignorados.

PUT/api/v1/admin/fbt/{id}/statusAdmin

Ativa ou desativa um combo

Um combo desativado deixa de aparecer na vitrine e fica protegido contra a mineração.

Parâmetros de caminho

iduuidobrigatório

Id do combo.

Corpo da requisição (JSON)

statusstringobrigatório

activedisabled

Novo estado. Aceita só as palavras, não as letras.

DELETE/api/v1/admin/fbt/{id}Admin

Apaga um combo

Apaga o combo. Combos minerados apagados podem voltar na próxima mineração, a menos que você os desative em vez de apagar. O kit fbt-... gerado para o combo não é apagado.

Parâmetros de caminho

iduuidobrigatório

Id do combo.

Exemplo de requisição

bash

# criar à mão
curl -X POST "$BASE_URL/api/v1/admin/fbt/manual" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"anchor_product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","companion_ids":["c4e16aa8-59ba-45f0-aaff-d87549ced120"]}'

# desativar
curl -X PUT "$BASE_URL/api/v1/admin/fbt/$COMBO/status" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

Resposta

200Lista

json

{
  "combos": [
    {
      "id": "11b6f790-c5c2-4f31-94ab-c88c6ecf3bc2",
      "anchor_product_id": "d3602023-101d-4f7d-8ef5-52abd5c7eaaf",
      "anchor_product_name": "Notebook Essencial Bege 02156",
      "companion_ids": ["12658adf-5a62-43c3-8310-73176df91202"],
      "companion_names": ["Óculos Deluxe Preto 02710"],
      "support_count": 3,
      "lift": 2294.25,
      "status": "active",
      "source": "mined",
      "adds_count": 0
    }
  ]
}

200Combo criado

json

{ "id": "c676155b-ddcf-4f62-916c-9cc698654033" }

200Mineração concluída

json

{ "mined": true }

200Status alterado ou combo apagado

json

{ "ok": true }

Campos de cada combo

iduuid

Id do combo.

anchor_product_iduuid

Produto-âncora.

anchor_product_namestring

Nome da âncora.

companion_idsarray

Ids dos companheiros (1 ou 2).

companion_namesarray

Nomes dos companheiros, na mesma ordem.

support_countinteger

Em quantos pedidos o par apareceu. 0 nos combos manuais.

liftnumber

Quanto o par é mais frequente que o acaso (probabilidade conjunta dividida pelo produto das probabilidades). Acima de 1 é associação positiva. 0 nos combos manuais.

statusstring

activedisabled

Estado do combo.

sourcestring

minedmanual

Se veio da mineração ou foi criado à mão.

adds_countinteger

Quantas vezes clientes adicionaram o combo ao carrinho pela vitrine.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `anchor_product_id`	`{"error":"failed to create combo","detail":"anchor_product_id required"}`
400	Nenhum companheiro distinto	`{"error":"failed to create combo","detail":"at least one distinct companion_id required"}`
400	Âncora não existe	`{"error":"failed to create combo","detail":"anchor product not found"}`
400	`status` diferente de `active` e `disabled`	`{"error":"failed to set status","detail":"invalid status"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
500	Falha na mineração	`{"error":"mining failed","detail":"..."}`