Funil de fluxo de ganho
The "Fluxo de ganho" block. Since V4MOS-1255 it is served by the product's existing bottleneck funnel (BottleneckFunnelRepository.getConversionFunnel, the same funnel that backs Destrava Receita) rather than by a distinct-customer count of its own.
Consequences the client must handle:
- Only the stages the organization CONFIGURED in
organization_bottleneck_configare returned. An organization with no bottleneck configuration getsstages: []— an empty block, not a six-stage funnel of zeros. - When the organization configured bottlenecks but no data source could produce an execution plan, every upstream stage value is null; that all-null case is collapsed to
stages: []as well. A PARTIALLY null result keeps the ordinary?? 0coalescing, so one stage may legitimately readcount: 0while its neighbours carry real values. - The
RETENCAOstage of the bowtie is dropped: it is not one of the six stages of this screen. countis SUMMED EVENT VOLUME, not distinct people: EXPOSURE = impressions, ATTENTION = clicks + GA4 sessions, INTEREST = leads + add-to-cart, QUALIFICATION = MQLs + begin-checkout, COMMITMENT = meetings/proposals + customer-data + checkout-done, DECISION = CRM wins + paid orders (or ad sale conversions when the decision stage is configured on an ads channel and no store is connected: with a store, its paid orders win, V4MOS-2863). The same person can be counted many times, and stages sum across connected tools.scaleseparates the media-volume stages (EXPOSURE, ATTENTION) from the customer-side stages. The step BETWEEN the two groups is not a conversion rate and must be labelled as such in the UI.- The human-readable stage label of the bowtie (
Exposição,Atenção, ...) is NOT forwarded; onlystageIdis returned. - Percentages are recomputed here AFTER filtering the configured stages — the bowtie's own
percentageis ignored.
With the gtmMotionId of a motion other than the organization's default (V4MOS-2707), the stages are those of that motion's own win-flow configuration and every source is cut to the motion's connections, as GET /v1/bottleneck/funnel?gtmMotionId= documents.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringIdentificador da organização (obrigatório). Um valor ausente ou que não seja string resulta em 400.
period?stringDescontinuadoDescontinuado: use startDate e endDate, que têm precedência quando enviados. Período relativo de N dias terminando hoje, inclusive (7d = hoje e os 6 dias anteriores). "Hoje" é o dia de calendário em UTC, e esse último dia ainda está parcial. Valores aceitos: 7d, 30d, 90d, 1y. Omitido ou vazio equivale a 30d; qualquer outro valor retorna 400.
"30d""7d""30d""90d""1y"startDate?stringInício do período (YYYY-MM-DD, inclusivo). Envie junto com endDate: enviar só um dos dois retorna 400. Tem precedência sobre period. Use só a data: data com hora ou data inexistente retorna 400. Regras: startDate ≤ endDate, nenhuma data no futuro (UTC) e no máximo 365 dias entre as datas (até 366 dias no período). A comparação usa o período de mesma duração imediatamente anterior.
dateendDate?stringFim do período (YYYY-MM-DD, inclusivo). Veja startDate para as regras. Quando o fim é hoje, esse último dia ainda está parcial, porque os dados do dia continuam chegando.
dategtmMotionId?stringGTM motion of the organization (UUID, as gtm_motions.id), V4MOS-2707. Omitted, or the default motion of the organization: the organization numbers, exactly as before. Another motion of the organization: /v1/acquisition/paid-media answers with that motion's own rows (investment, impressions, clicks, CRM leads and CPL from analytics.obt_cpl_daily_by_gtm_motion; Meta/Google platform leads and Meta reach are null, they have no motion grain yet); every other acquisition route answers 422 GTM_MOTION_DATA_NOT_AVAILABLE. Not a UUID: 400. Not a live motion of the organization: 403 GTM_MOTION_NOT_IN_ORGANIZATION.
uuidFunil retornado com sucesso
application/json- response
stages*array<>Só as etapas configuradas pela organização, ordenadas por stageOrder. Lista vazia quando nenhuma etapa do funil foi configurada ou quando nenhuma etapa pôde ser medida.
curl -X GET "https://example.com/v1/acquisition/funnel?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&period=30d&startDate=2026-03-11&endDate=2026-03-22>mMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"{ "stages": [ { "stageId": "EXPOSURE", "stageOrder": 1, "count": 1250000, "pctOfFirst": 100, "pctOfPrevious": 100, "previousCount": 1250000, "scale": "media", "source": { "tools": [ "META_ADS", "GOOGLE_ADS" ], "fields": [ "impressions", "impressions" ], "resolution": "sum", "label": "Meta Ads · Impressões + Google Ads · Impressões" }, "frequency": 3.33 }, { "stageId": "ATTENTION", "stageOrder": 2, "count": 18750, "pctOfFirst": 1.5, "pctOfPrevious": 1.5, "previousCount": 1250000, "scale": "media", "source": { "tools": [ "GA4" ], "fields": [ "session_start" ], "resolution": "single", "label": "GA4 · Sessões" } }, { "stageId": "QUALIFICATION", "stageOrder": 4, "count": 2100, "pctOfFirst": 0.17, "pctOfPrevious": 11.2, "previousCount": 18750, "scale": "customer", "source": { "tools": [ "GA4" ], "fields": [ "begin_checkout" ], "resolution": "single", "label": "GA4 · Initiate checkout" } }, { "stageId": "DECISION", "stageOrder": 6, "count": 420, "pctOfFirst": 0.03, "pctOfPrevious": 20, "previousCount": 2100, "scale": "customer", "source": { "tools": [ "VTEX" ], "fields": [ "orders_paid" ], "resolution": "single", "label": "VTEX · Pedido pago" } }, { "stageId": "RETENTION", "stageOrder": 7, "count": 63, "pctOfFirst": 0.01, "pctOfPrevious": 15, "previousCount": 420, "scale": "customer", "source": { "tools": [ "VTEX" ], "fields": [ "repurchase" ], "resolution": "single", "label": "VTEX · Recompra" } } ]}