> ## Documentation Index > Fetch the complete documentation index at: https://docs.cardapioweb.com/llms.txt > Use this file to discover all available pages before exploring further. # Ranking de vendas por item > Retorna os itens vendidos no período, com quantidade, faturamento e preço médio. A resposta inclui os totais de todo o conjunto filtrado, independentemente da página atual. Use `category_id` para limitar o resultado a uma categoria. Use `search_text` para buscar pelo nome ou código externo resolvido do item. A busca considera o cadastro atual e o histórico gravado no pedido. **Autenticação:** OAuth 2.0 com escopo `orders`. Não aceita API Key. **Rate limit:** 5 requisições por minuto para este endpoint. ### Período e filtros de pedidos `start_date`, `end_date`, `date_field` e `filters` seguem as mesmas regras do [resumo de pedidos](/api-reference/pedidos/resumo-de-pedidos). Os filtros aceitam `order_type`, `order_timing`, `sales_channel`, `status`, `payment_method_id`, `driver_id`, `customer_origin`, `created_at_time`, `total` e `delivery_fee`, combinados com os operadores permitidos no resumo. Pedidos cancelados entram no ranking por padrão. Use `filters[status_not_in]=canceled` para removê-los. Itens cancelados dentro de um pedido nunca entram no cálculo. ### Filtro por entregador Use `filters[driver_id_in][]=12` para incluir os pedidos do entregador 12 ou `filters[driver_id_not_in][]=12` para excluí-los. Para informar vários IDs, repita o parâmetro com `[]`. Envie apenas IDs inteiros positivos; valores inválidos retornam `400`. ```http GET /api/partner/v1/orders/summary/items?start_date=2026-09-01T00:00:00-03:00&end_date=2026-09-10T23:59:59-03:00&filters[driver_id_in][]=12 ``` O filtro restringe os pedidos usados nas linhas do ranking e em `totals`. A consulta considera apenas pedidos do seu estabelecimento. A inclusão de um entregador de outro estabelecimento retorna uma lista vazia. O resultado continua agrupado por item. Não envie `group_by=driver_id` neste endpoint. Para agrupar pedidos por entregador, use `GET /orders/summary/grouped`. ## OpenAPI ````yaml /reference/api-pedidos.json get /api/partner/v1/orders/summary/items openapi: 3.1.0 info: title: API Pedidos version: '1.0' contact: email: integracao@cardapioweb.com name: Cardápio Web url: https://cardapioweb.com description: >- A API de pedidos acompanha pedidos de um estabelecimento, permite alterações de status e consulta resumos e rankings de vendas. ## Autenticação Apps da CW App Store usam `Authorization: Bearer ` (OAuth 2.0) com escopo `orders`. A associação e a remoção de entregadores também exigem o escopo `drivers`. Integrações legadas usam `X-API-KEY`. A criação de pedidos (`POST /orders`) também exige `X-PARTNER-KEY`. Os endpoints de resumo, rankings de vendas e gestão do entregador exigem OAuth 2.0 e não aceitam API Key. Consulte a documentação em /autenticacao/modelos-de-autenticacao. ## Rate Limits Histórico de pedidos (`GET /orders/history`), resumos e rankings de vendas (`GET /orders/summary`, `GET /orders/summary/*`): **5 requisições por minuto por endpoint**. Demais endpoints: **300 requisições a cada 3 minutos**. Consulte /sobre-a-api#rate-limits. servers: - url: https://integracao.sandbox.cardapioweb.com description: Sandbox - url: https://integracao.cardapioweb.com description: Produção security: - bearerAuth: [] - apiKey: [] paths: /api/partner/v1/orders/summary/items: get: summary: Ranking de vendas por item description: >- Retorna os itens vendidos no período, com quantidade, faturamento e preço médio. A resposta inclui os totais de todo o conjunto filtrado, independentemente da página atual. Use `category_id` para limitar o resultado a uma categoria. Use `search_text` para buscar pelo nome ou código externo resolvido do item. A busca considera o cadastro atual e o histórico gravado no pedido. **Autenticação:** OAuth 2.0 com escopo `orders`. Não aceita API Key. **Rate limit:** 5 requisições por minuto para este endpoint. ### Período e filtros de pedidos `start_date`, `end_date`, `date_field` e `filters` seguem as mesmas regras do [resumo de pedidos](/api-reference/pedidos/resumo-de-pedidos). Os filtros aceitam `order_type`, `order_timing`, `sales_channel`, `status`, `payment_method_id`, `driver_id`, `customer_origin`, `created_at_time`, `total` e `delivery_fee`, combinados com os operadores permitidos no resumo. Pedidos cancelados entram no ranking por padrão. Use `filters[status_not_in]=canceled` para removê-los. Itens cancelados dentro de um pedido nunca entram no cálculo. ### Filtro por entregador Use `filters[driver_id_in][]=12` para incluir os pedidos do entregador 12 ou `filters[driver_id_not_in][]=12` para excluí-los. Para informar vários IDs, repita o parâmetro com `[]`. Envie apenas IDs inteiros positivos; valores inválidos retornam `400`. ```http GET /api/partner/v1/orders/summary/items?start_date=2026-09-01T00:00:00-03:00&end_date=2026-09-10T23:59:59-03:00&filters[driver_id_in][]=12 ``` O filtro restringe os pedidos usados nas linhas do ranking e em `totals`. A consulta considera apenas pedidos do seu estabelecimento. A inclusão de um entregador de outro estabelecimento retorna uma lista vazia. O resultado continua agrupado por item. Não envie `group_by=driver_id` neste endpoint. Para agrupar pedidos por entregador, use `GET /orders/summary/grouped`. operationId: orders-sales-ranking-items parameters: - $ref: '#/components/parameters/SalesStartDate' - $ref: '#/components/parameters/SalesEndDate' - $ref: '#/components/parameters/SalesDateField' - $ref: '#/components/parameters/SalesFilters' - $ref: '#/components/parameters/SalesCategoryId' - $ref: '#/components/parameters/SalesSearchText' - $ref: '#/components/parameters/SalesPage' - $ref: '#/components/parameters/SalesPerPage' - $ref: '#/components/parameters/SalesOrderBy' - $ref: '#/components/parameters/SalesOrder' responses: '200': description: Ranking de itens retornado com sucesso. content: application/json: schema: $ref: '#/components/schemas/ItemSalesRankingResponse' example: data: - item_id: 208907 name: Hambúrguer clássico external_code: HAM-01 category_id: 12 category_name: Lanches total_quantity: 10 total_revenue: 300 average_price: 30 meta: page: 1 per_page: 20 total: 1 total_pages: 1 totals: total_quantity: 10 total_revenue: 300 '400': description: Algum parâmetro enviado é inválido. content: application/json: schema: $ref: '#/components/schemas/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' security: - bearerAuth: [] components: parameters: SalesStartDate: name: start_date in: query required: true description: >- Início do período. Use datetime ISO 8601 com offset para `created_at` ou `YYYY-MM-DD` para `scheduled_date`. schema: type: string example: '2025-06-01T00:00:00-03:00' SalesEndDate: name: end_date in: query required: true description: Fim do período. O intervalo não pode ultrapassar 6 meses. schema: type: string example: '2025-06-30T23:59:59-03:00' SalesDateField: name: date_field in: query required: false description: Data do pedido usada no recorte. schema: type: string enum: - created_at - scheduled_date default: created_at SalesFilters: name: filters in: query required: false style: deepObject explode: true description: >- Filtros do pedido no formato plano `filters[campo_operador]`. Para entregadores, use `driver_id_in` ou `driver_id_not_in` com IDs públicos positivos. Não coloque filtros do catálogo dentro deste objeto. Para listas, use `filters[driver_id_in][]=12&filters[driver_id_in][]=15` ou `filters[driver_id_not_in][]=12`. Os filtros afetam também os totais; não alteram a dimensão do ranking. schema: type: object additionalProperties: true properties: driver_id_in: description: IDs dos entregadores que devem entrar no resultado. oneOf: - type: integer minimum: 1 - type: array items: type: integer minimum: 1 driver_id_not_in: description: IDs dos entregadores que devem ser excluídos do resultado. oneOf: - type: integer minimum: 1 - type: array items: type: integer minimum: 1 SalesCategoryId: name: category_id in: query required: false description: ID público da categoria. schema: type: integer minimum: 1 SalesSearchText: name: search_text in: query required: false description: Busca parcial sem diferenciação entre maiúsculas e minúsculas. schema: type: string SalesPage: name: page in: query required: false description: Número da página. schema: type: integer minimum: 1 default: 1 SalesPerPage: name: per_page in: query required: false description: Quantidade de registros por página. schema: type: integer minimum: 1 maximum: 100 default: 20 SalesOrderBy: name: order_by in: query required: false description: Métrica ou nome usado para ordenar o ranking. schema: type: string enum: - total_revenue - total_quantity - average_price - name default: total_revenue SalesOrder: name: order in: query required: false description: >- Direção da ordenação. O padrão é `desc`, ou `asc` quando `order_by=name`. schema: type: string enum: - asc - desc schemas: ItemSalesRankingResponse: type: object required: - data - meta - totals properties: data: type: array items: $ref: '#/components/schemas/ItemSalesRanking' meta: $ref: '#/components/schemas/SalesRankingMeta' totals: $ref: '#/components/schemas/SalesRankingTotals' BadRequest: type: object examples: - code: 4000 message: Parâmetros inválidos details: updated_since não é uma data válida - code: 4000 message: Parâmetros inválidos details: status contém valores inválidos properties: code: type: integer description: Código interno de identificação do erro. message: type: string description: Mensagem de resumo do erro. details: type: string description: Informações adicionais sobre o erro. required: - code - message title: BadRequest x-internal: false ItemSalesRanking: title: Venda por item allOf: - $ref: '#/components/schemas/SalesMetrics' - type: object required: - item_id - name - external_code - category_id - category_name properties: item_id: type: - integer - 'null' description: >- ID público do item. Pode ser `null` quando o cadastro não existe mais. name: type: string description: >- Nome atual do item, com fallback para o nome registrado no pedido. external_code: type: - string - 'null' description: >- Código externo atual do item, com fallback para o código registrado no pedido. category_id: type: - integer - 'null' description: ID público da categoria do item. category_name: type: string description: Nome da categoria do item. SalesRankingMeta: type: object title: Paginação do ranking required: - page - per_page - total - total_pages properties: page: type: integer description: Página atual. per_page: type: integer description: Registros por página. total: type: integer description: Quantidade total de registros. total_pages: type: integer description: Quantidade total de páginas. SalesRankingTotals: type: object title: Totais do ranking required: - total_quantity - total_revenue properties: total_quantity: type: number description: Quantidade somada em todo o conjunto filtrado. total_revenue: type: number description: Faturamento somado em todo o conjunto filtrado. Unauthorized: type: object x-stoplight: id: 5cdf37ldhxqd8 examples: - code: 4010 message: Token inválido title: Unauthorized x-internal: false properties: code: type: integer description: Código interno de identificação do erro. message: type: string description: Mensagem de resumo do erro. required: - code - message SalesMetrics: type: object required: - total_quantity - total_revenue - average_price properties: total_quantity: type: number description: Quantidade total vendida, arredondada para quatro casas decimais. total_revenue: type: number description: Faturamento total, arredondado para duas casas decimais. average_price: type: number description: Preço médio ponderado, arredondado para duas casas decimais. responses: Unauthorized: description: >- Não autorizado. Token OAuth inválido ou ausente, ou X-API-KEY inválido/ausente no modelo legado. content: application/json: schema: $ref: '#/components/schemas/Unauthorized' TooManyRequests: description: >- Muitas requisições foram feitas em um curto período. Verifique nossas regras de rate limit. content: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: OAuth2 description: >- Access token OAuth 2.0 de app instalado na CW App Store. Escopo principal: orders. A gestão do entregador também exige drivers. apiKey: name: X-API-KEY type: apiKey in: header description: >- Token específico do estabelecimento integrado. Disponível na seção de integrações do Portal do estabelecimento. ````