Produtos

Produtos consolidados

GET
/v1/products

Retorna uma linha por produto com vendas, margem, estoque, devoluções e métricas de recompra do período, além dos totais por categoria em categories.

  • Métricas de venda seguem dateFrom/dateTo; catálogo, status e estoque mostram a foto mais recente.
  • Valores indisponíveis vêm como null, com o motivo em ndReasons — por exemplo, a margem fica oculta quando falta o custo de alguma unidade.
  • LTV e recompra de 180 dias consideram só os clientes que já completaram 180 dias desde a primeira compra; matureEntryCustomers e entryCustomers mostram quantos são.
  • Se você já consulta GET /v1/products/categories, envie includeCategories=false para receber a listagem mais rápido.

Autorização

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Parâmetros de query

organizationId*string
Formatouuid
integrationId*string

Identificador da loja: o sourceIntegrationId retornado por GET /v1/products/integrations. Não use a App Key da VTEX — ela pode ser trocada e a mesma chave pode estar ligada a mais de uma loja ou organização.

Formatouuid
dateFrom?string
Formatodate
dateTo?string
Formatodate
search?string
Tamanholength <= 120
categoryId?stringDescontinuado

Obsoleto: prefira categoryIds. Corresponde a qualquer nível do caminho de categorias da VTEX, portanto um departamento também retorna os produtos de seus descendentes.

categoryIds?array<>

Filtra por uma ou mais categorias. Um produto entra quando pertence a QUALQUER uma delas, diretamente ou por uma subcategoria — escolher um departamento traz também os produtos das subcategorias. Envie separados por vírgula (categoryIds=1,12) ou repetidos (categoryIds=1&categoryIds=12); valores vazios e duplicados são ignorados. Até 50 ids distintos (contando também o categoryId, se enviado), cada um com até 50 caracteres; acima disso a resposta é 400.

Itensitems <= 50
status?string
Padrão"all"
Valor em"all""active""inactive"
minNetSales?number

Limite mínimo (inclusivo) de netSales — faturamento no período, na moeda da loja. Não pode ser maior que maxNetSales. Filtra as linhas, a pagination e os totais de categories.

maxNetSales?number

Limite máximo (inclusivo) de netSales — faturamento no período, na moeda da loja. Não pode ser menor que minNetSales. Filtra as linhas, a pagination e os totais de categories.

minMarginTotal?number

Limite mínimo (inclusivo) de marginTotal — margem em moeda. Produtos com margem N/D (falta de valor de venda ou de custo) nunca entram na faixa. Não pode ser maior que maxMarginTotal. Filtra as linhas, a pagination e os totais de categories.

maxMarginTotal?number

Limite máximo (inclusivo) de marginTotal — margem em moeda. Produtos com margem N/D (falta de valor de venda ou de custo) nunca entram na faixa. Não pode ser menor que minMarginTotal. Filtra as linhas, a pagination e os totais de categories.

minMarginAverage?number

Limite mínimo (inclusivo) de marginAverage — margem % em decimal: 0.3 = 30%. Produtos com margem N/D nunca entram na faixa. Não pode ser maior que maxMarginAverage. Filtra as linhas, a pagination e os totais de categories.

maxMarginAverage?number

Limite máximo (inclusivo) de marginAverage — margem % em decimal: 0.3 = 30%. Produtos com margem N/D nunca entram na faixa. Não pode ser menor que minMarginAverage. Filtra as linhas, a pagination e os totais de categories.

minAvailableStock?number

Limite mínimo (inclusivo) de availableStock — estoque disponível em unidades. Produtos com estoque N/D (nem todos os SKUs monitorados) nunca entram na faixa. Não pode ser maior que maxAvailableStock. Filtra as linhas, a pagination e os totais de categories.

maxAvailableStock?number

Limite máximo (inclusivo) de availableStock — estoque disponível em unidades. Produtos com estoque N/D (nem todos os SKUs monitorados) nunca entram na faixa. Não pode ser menor que minAvailableStock. Filtra as linhas, a pagination e os totais de categories.

sortBy?string
Padrão"netSales"
Valor em"productName""grossSales""netSales""netUnits""averageTicket""marginAverage""marginTotal""newCustomers""recurringCustomers""ltv180""repurchaseRate180""ltvToDate""repurchaseRateToDate""entryCustomers""matureEntryCustomers""availableStock""daysOfStock""returnRate""updatedAt"
sortOrder?string
Padrão"desc"
Valor em"asc""desc"
page?integer
Intervalo1 <= value
Padrão1
pageSize?integer
Intervalo1 <= value <= 100
Padrão25
columns?string

Métricas a retornar, separadas por vírgula (ex.: netSales,marginTotal). Identificação, estado, cobertura e motivos de N/D sempre vêm. Uma métrica desconhecida retorna 400.

gtmMotionId?string

GTM motion of the organization (UUID), as listed by GET /v1/gtm-motions. Optional: without it, the response covers the organization's default GTM motion. The default motion is answered with the organization's data, the same numbers as when the parameter is omitted. Another GTM motion of the organization only sees its own stores (V4MOS-2707): a store belongs to a motion whole, so GET /v1/products/integrations lists only the motion's stores (none for a motion without a store) and a route that reads one store answers exactly as for the organization when integrationId is a store of the motion, and 404 GTM_MOTION_STORE_NOT_IN_MOTION otherwise. Not a UUID: 400. Not a live GTM motion of the organization: 403 GTM_MOTION_NOT_IN_ORGANIZATION.

Formatouuid

Corpo da resposta

Linhas de produtos paginadas

application/json
  1. response
data*array<>
categories*array<>

Agrupamentos para cada nível de categoria presente no conjunto filtrado, calculados fora da paginação. Os numeradores das métricas são recalculados por nível, nunca somados a partir da página.

period*
asOf*|
Formatodate-time
selectedColumns*array<>
availableColumns*array<>
pagination*
curl -X GET "https://example.com/v1/products?organizationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&integrationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&categoryIds=1&categoryIds=12&gtmMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"
{  "data": [    {      "integrationId": "497a18ca-284e-40c0-985d-f72be35d468e",      "productId": "string",      "productName": "string",      "stockPosition": {        "state": "ready",        "reason": "source_unavailable",        "snapshotAt": "2019-08-24",        "previousSnapshotAt": "2019-08-24",        "availableStock": 0,        "previousAvailableStock": 0,        "inventoryState": "string",        "previousInventoryState": "string",        "stockDelta": 0,        "stockDeltaReason": "source_unavailable",        "previousDaysOfStock": 0,        "previousDaysOfStockReason": "source_unavailable",        "previousVelocity30d": 0      },      "imageUrl": "string",      "sourceImageUrl": "string",      "imageStatus": "mirrored",      "categoryId": "string",      "categoryName": "string",      "categoryPath": [        {          "id": "string",          "name": "string"        }      ],      "status": "active",      "inventoryState": "monitored",      "inventoryFreshness": "fresh",      "inventoryUpdatedAt": "2019-08-24T14:15:22Z",      "cohortState": "no_base",      "cohortWindowDays": 180,      "entryCustomers": 0,      "matureEntryCustomers": 0,      "asOf": "2019-08-24T14:15:22Z",      "grossSales": 0,      "netSales": 0,      "grossUnits": 0,      "netUnits": 0,      "averageTicket": 0,      "marginAverage": 0,      "marginTotal": 0,      "newCustomers": 0,      "recurringCustomers": 0,      "ltv180": 0,      "repurchaseRate180": 0,      "ltvToDate": 0,      "repurchaseRateToDate": 0,      "cohortElapsedDaysAverage": 0,      "availableStock": 0,      "velocity30d": 0,      "daysOfStock": 0,      "returnRate": 0,      "coverage": {        "grossValue": 0,        "cost": 0,        "inventory": 0,        "matureCohort": 0      },      "ndReasons": {        "averageTicket": "string",        "margin": "string",        "averageMargin": "string",        "daysOfStock": "string",        "ltv180": "string",        "repurchaseRate180": "string",        "returnRate": null      },      "cogs": 6200    }  ],  "categories": [    {      "integrationId": "497a18ca-284e-40c0-985d-f72be35d468e",      "categoryId": "string",      "categoryName": "string",      "parentCategoryId": "string",      "depth": 1,      "inventoryState": "monitored",      "inventoryFreshness": "fresh",      "inventoryUpdatedAt": "2019-08-24T14:15:22Z",      "cohortState": "no_base",      "cohortWindowDays": 180,      "entryCustomers": 0,      "matureEntryCustomers": 0,      "asOf": "2019-08-24T14:15:22Z",      "grossSales": 0,      "netSales": 0,      "grossUnits": 0,      "netUnits": 0,      "averageTicket": 0,      "marginAverage": 0,      "marginTotal": 0,      "newCustomers": 0,      "recurringCustomers": 0,      "ltv180": 0,      "repurchaseRate180": 0,      "ltvToDate": 0,      "repurchaseRateToDate": 0,      "cohortElapsedDaysAverage": 0,      "availableStock": 0,      "velocity30d": 0,      "daysOfStock": 0,      "returnRate": 0,      "coverage": {        "grossValue": 0,        "cost": 0,        "inventory": 0,        "matureCohort": 0      },      "ndReasons": {        "averageTicket": "string",        "margin": "string",        "averageMargin": "string",        "daysOfStock": "string",        "ltv180": "string",        "repurchaseRate180": "string",        "returnRate": null      },      "cogs": 6200    }  ],  "period": {    "from": "2019-08-24",    "to": "2019-08-24"  },  "asOf": "2019-08-24T14:15:22Z",  "selectedColumns": [    "grossSales"  ],  "availableColumns": [    "grossSales"  ],  "pagination": {    "page": 0,    "pageSize": 0,    "total": 0,    "totalPages": 0  }}