Lucratividade

Evolução diária do CMV

GET
/v1/profitability/cmv-evolution

Retorna uma série diária com receita, pedidos, ticket médio e o custo real das mercadorias vendidas (CMV) de cada dia, com os mesmos campos de CMV de /cards e /metrics-evolution (cogs, revenueWithCmv, revenueWithoutCmv, marginBasis, blendedContribution).

  • Um dia em que todos os pedidos têm custo real vem com marginBasis = cmv_real. Dias com cobertura parcial de custo vêm como mixed, para você sinalizar que o valor não é completo.
  • degraded: true com data: [] indica que os dados de custo não estavam disponíveis no momento da consulta, e não que o período está vazio.

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)

startDate?string

Primeiro dia do período, inclusivo (YYYY-MM-DD). Só é aplicado junto com endDate; sem os dois, a API considera todo o histórico.

Formatodate
endDate?string

Último dia do período, inclusivo (YYYY-MM-DD). Só é aplicado junto com startDate; sem os dois, a API considera todo o histórico.

Formatodate
gtmMotionId?string

GTM motion of the organization (UUID), as listed by GET /v1/gtm-motions. Optional: without it, or with the default GTM motion, the response is the organization data, exactly as before. Any other GTM motion of the organization is answered with that motion's own rows, read from the *_by_gtm_motion twins of the models behind the route (obt_profitability_daily/monthly/cohorts/product_cohorts/cohorts_by_dimension, obt_acquisition_customers, obt_acquisition_product_cohorts, fct_transactions and fct_media_daily), and the monetary figures are priced with the motion's own contribution margin (V4MOS-2707). A motion with no store linked has no orders or customers: the route answers with zeros or empty lists, never an error. Not a UUID: 400. Not a live GTM motion of the organization: 403 GTM_MOTION_NOT_IN_ORGANIZATION.

Formatouuid

Corpo da resposta

Evolução diária do CMV obtida com sucesso

application/json
  1. response
data*array<>

Série temporal diária do CMV (COGS), ordenada por data

granularity*"daily"

Sempre daily. Para a visão mensal, use /metrics-evolution.

Valor em"daily"
degraded*boolean

true quando os dados de custo não estavam disponíveis no momento da consulta. Nesse caso data vem vazio porque a consulta não pôde ser feita, e não porque o período não tem dados.

marginPercent*number

Percentual de margem de contribuição aplicado. 100 quando nenhuma margem está configurada

marginConfigured*boolean

Indica se uma margem de contribuição personalizada foi configurada para esta organização

marginCompleteness?MarginCompleteness

Completude da margem configurada item a item (gateway, imposto, frete e CMV): complete = todos os itens resolvidos; partial = algum item pendente, então a margem é parcial; none = não há composição por item (margem nunca configurada ou configurada como percentual único; diferencie pelos valores de marginConfigured).

Valor em"complete""partial""none"
marginItemStatus?|

Status por item da composição da margem (synced = vindo dos pedidos, configured = informado pelo usuário, pending = não configurado ou com dados ausentes). null quando a organização não tem composição.

curl -X GET "https://example.com/v1/profitability/cmv-evolution?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&startDate=2025-01-01&endDate=2025-12-31&gtmMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"
{  "data": [    {      "date": "2026-09-01",      "revenue": 100000,      "orders": 250,      "averageTicket": 400,      "cogs": 38000,      "revenueWithCmv": 82000,      "revenueWithoutCmv": 18000,      "marginBasis": "mixed",      "blendedContribution": 52100    }  ],  "granularity": "daily",  "degraded": false,  "marginPercent": 35,  "marginConfigured": true,  "marginCompleteness": "none",  "marginItemStatus": null}