Produtos

Categorias de produtos consolidadas

GET
/v1/products/categories

Retorna os totais de cada categoria (departamentos e subcategorias) para a mesma seleção de GET /v1/products: loja, período, busca, status, categorias e faixas de métricas.

  • Os totais consideram todos os produtos filtrados, sem paginação: pedidos e clientes são recontados (um pedido com vários produtos conta uma vez) e as taxas são recalculadas a partir dos totais.
  • Com faixas de métricas, cada categoria soma apenas os produtos dentro de todas as faixas; categorias sem nenhum produto na faixa são omitidas.
  • Um departamento já inclui suas subcategorias: não some níveis diferentes.
  • Não aceita page nem sortBy, porque os valores são os mesmos em qualquer página ou ordenação.

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. Cada categoria soma apenas os produtos dentro de todas as faixas — os mesmos que GET /v1/products retorna com esses limites.

maxNetSales?number

Limite máximo (inclusivo) de netSales — faturamento no período, na moeda da loja. Não pode ser menor que minNetSales. Cada categoria soma apenas os produtos dentro de todas as faixas — os mesmos que GET /v1/products retorna com esses limites.

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. Cada categoria soma apenas os produtos dentro de todas as faixas — os mesmos que GET /v1/products retorna com esses limites.

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. Cada categoria soma apenas os produtos dentro de todas as faixas — os mesmos que GET /v1/products retorna com esses limites.

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. Cada categoria soma apenas os produtos dentro de todas as faixas — os mesmos que GET /v1/products retorna com esses limites.

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. Cada categoria soma apenas os produtos dentro de todas as faixas — os mesmos que GET /v1/products retorna com esses limites.

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. Cada categoria soma apenas os produtos dentro de todas as faixas — os mesmos que GET /v1/products retorna com esses limites.

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. Cada categoria soma apenas os produtos dentro de todas as faixas — os mesmos que GET /v1/products retorna com esses limites.

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

Agrupamentos de categoria e o contrato de métricas aplicado

application/json
  1. response

Todos os consolidados de categoria que correspondem aos filtros, fora da paginação de produtos.

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<>
curl -X GET "https://example.com/v1/products/categories?organizationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&integrationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&categoryIds=1&categoryIds=12&gtmMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"
{  "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"  ]}