Aquisição

Funil de fluxo de ganho

GET
/v1/acquisition/funnel

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_config are returned. An organization with no bottleneck configuration gets stages: [] — 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 ?? 0 coalescing, so one stage may legitimately read count: 0 while its neighbours carry real values.
  • The RETENCAO stage of the bowtie is dropped: it is not one of the six stages of this screen.
  • count is 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.
  • scale separates 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; only stageId is returned.
  • Percentages are recomputed here AFTER filtering the configured stages — the bowtie's own percentage is 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.

Autorização

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Parâmetros de query

organizationId*string

Identificador da organização (obrigatório). Um valor ausente ou que não seja string resulta em 400.

period?stringDescontinuado

Descontinuado: 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.

Padrão"30d"
Valor em"7d""30d""90d""1y"
startDate?string

Iní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.

Formatodate
endDate?string

Fim 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.

Formatodate
gtmMotionId?string

GTM 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.

Formatouuid

Corpo da resposta

Funil retornado com sucesso

application/json
  1. 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&gtmMotionId=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"      }    }  ]}