Categorias de produtos consolidadas
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
pagenemsortBy, porque os valores são os mesmos em qualquer página ou ordenação.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringuuidintegrationId*stringIdentificador 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.
uuiddateFrom?stringdatedateTo?stringdatesearch?stringlength <= 120categoryId?stringDescontinuadoObsoleto: 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.
items <= 50status?string"all""all""active""inactive"minNetSales?numberLimite 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?numberLimite 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?numberLimite 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?numberLimite 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.
maxAvailableStock?numberLimite 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?stringMé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?stringGTM 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.
uuidAgrupamentos de categoria e o contrato de métricas aplicado
application/json- 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*|date-timeselectedColumns*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>mMotionId=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" ]}