Funil de compra por produto
GET/api/analytics/funnel
- Auth
- Jeton requis
- Clé d’API:
- reports:read
- X-CommunityId
X-CommunityIdEnvoyez le X-CommunityId de la communauté où l’opération a lieu.
Owner, admin e financeiro. Sem valores em dinheiro. O funil é contado **por sessão de navegação**, e todas as etapas falam da mesma população:
- **Período**: começa no primeiro evento coletado pela comunidade (`collectionStartedAt`); antes disso não há visita para comparar. `period.effectiveFrom` é o dia em que o período efetivo começa (null quando ainda não há coleta). - **Etapas**: `visit` → `catalog` → `product` → `checkout_identify` → `checkout_payment` → `checkout_submitted` → `checkout_success`. - **`visit` (Visitas)** é o topo: toda sessão do período com alguma página vista na comunidade, anônima ou logada (ou que chegou a uma etapa posterior). **Não filtra por produto**: com `productIds` continua sendo todas as visitas da comunidade, e a linha traz `productAgnostic: true` para o app indicar isso. Traz `anonymous` (sessões que nunca entraram logadas) além de `members` (perfis distintos); a mesma linha se repete em `products[].steps`. - **`catalog` (Vitrine)**: sessões que abriram a vitrine (lista de produtos) **ou** chegaram a um dos produtos selecionados; quem entrou direto num produto pelo link também passou da vitrine. `direct` é quantas chegaram a um produto selecionado sem abrir a vitrine. Com filtro de produtos: quem viu a vitrine (de toda a comunidade) e/ou os produtos selecionados. - `product`, `checkout_identify`, `checkout_payment` vêm do app. `checkout_submitted` e `checkout_success` são os pedidos do período (criados nele) ligados a uma sessão rastreada: a do `analyticsSessionId` enviado no checkout ou, sem ele, a sessão mais recente do comprador nas 24 h anteriores (só para pedido feito pelo app). Pago inclui reembolsado. Renovação, item adicional e assinatura criada pela equipe não são pedidos de checkout. - **Regra da etapa**: uma sessão conta numa etapa quando chegou nela **ou numa posterior**. Assim nenhuma etapa passa da anterior. - **`totals`** conta cada sessão uma vez, na etapa mais avançada entre os produtos selecionados (sem dupla contagem entre produtos); `products` traz o mesmo por produto (`planId` é sempre null). - **Objeto `catalog`** (mantido por compatibilidade; o app deve usar a linha `catalog` de `totals`) traz as sessões que viram a lista (de toda a comunidade, mesmo com filtro) e `catalog.thenProduct` as que viram a lista e depois um dos produtos selecionados. - **`untrackedOrders`**: pedidos do período sem visita rastreada, fora das etapas: `placed`, `paid` e `byChannel` (`direct`: pelo app sem sessão, ex. bloqueador; `mcp`: assistente; `api`: chamada direta; `unknown`: pedidos anteriores ao registro do canal). Respeitam o filtro de produtos.
`rateFromPrevious` é a % sobre a etapa anterior (null quando a anterior é zero).
Paramètres
| Nom | Emplacement | Type | Description |
|---|---|---|---|
fromfacultatif | query | string (date) | |
tofacultatif | query | string (date) | |
productIdfacultatif | query | string (uuid) | Um produto (mantido por compatibilidade; soma-se a `productIds`). |
productIdsfacultatif | query | string (uuid)[] | Vários produtos, separados por vírgula (`productIds=a,b`) ou repetidos (`productIds=a&productIds=b`), até 100. Sem `productId` nem `productIds`, todos os produtos. Os pedidos (etapas e `untrackedOrders`) filtram igual. |
En-têtes
| Nom | Type | Description |
|---|---|---|
X-CommunityIdfacultatif | string (uuid) | ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade. |
Réponses
| Statut | Description |
|---|---|
200 | Funil. |
400 | Requisição inválida — falha de validação. |
401 | Token ausente, inválido ou expirado; token de outra comunidade (o `X-CommunityId` ou o `communityId` do corpo não é o do token); token antigo ou de uma sessão encerrada (troca de senha, convite aceito). Nesses casos a mensagem pede para entrar de novo (`auth.signInAgain`). |
403 | Autenticado, mas sem permissão para esta operação. |
500 | Erro interno do servidor. |
Exemple curl
curl -X GET "https://api.memberfy.net/api/analytics/funnel" \
-H "Authorization: Bearer $TOKEN" \
-H "X-CommunityId: $COMMUNITY_ID"