Documentação
Relatórios
Indicadores de pagamentos, clientes, produtos e KDS, com filtros e granularidade diária ou mensal.
Relatórios
A categoria Relatórios na referência da API reúne quatro famílias: Pagamentos, Clientes, Produtos e KDS. O AI Builders apresenta as mesmas famílias em um bloco próprio de Relatórios na coleção de requisições.
As consultas são somente de leitura. Cada família exige sua própria permissão e mantém os dados, cálculos, filtros, paginação e respostas do relatório de origem. O KDS é o sistema de acompanhamento do preparo na cozinha.
Conectar e consultar
- Configure no app OAuth ou na chave de restaurante apenas os escopos necessários:
reports:payments:read,reports:customers:read,reports:products:readereports:kds:read. - Para OAuth, obtenha o consentimento do restaurante por Authorization Code + PKCE. Para API key, faça a troca em
POST /oauth/tokenconforme API key e tokens. - Envie o access token em
Authorization: Bearer {access_token}. Sessões humanas da Takeat, tokens de garçom e chaves brutas não autorizam estas rotas. - Em uma credencial com vários restaurantes, envie
restaurant_idde uma loja explicitamente autorizada. Um restaurante único pode ser inferido. Uma loja de fora da concessão resulta em 403. - Ao incluir permissões em um app existente, revise a configuração e reconecte para consentir novamente. Ao editar uma chave, troque-a novamente por um token. Tokens e concessões existentes não recebem escopos automaticamente.
Pelo MCP
Assistentes de IA conectados pelo MCP consultam os mesmos relatórios com get_payments_report, get_customers_report, get_products_report e get_kds_report. Cada ferramenta exige a permissão da família, recebe em report o caminho abaixo de /v1/reports/<família>/ e aceita os filtros da rota correspondente. Conexões MCP anteriores precisam ser reconectadas para aprovar as permissões de relatórios.
Diário, mensal ou período com filtros?
A granularidade informa qual série consultar. Nas rotas unificadas, selecione-a pelo parâmetro granularity; o padrão é daily.
| Opção | O que consultar | Parâmetros do período | Exemplo |
|---|---|---|---|
Diária (daily) | A série diária do relatório, para acompanhar a evolução entre datas. | start_date e end_date, em AAAA-MM-DD. | 2026-10-01 a 2026-10-31. |
Mensal (monthly) | A série mensal do relatório, para comparar meses. | start_month e end_month, em AAAA-MM. | 2026-08 a 2026-10. |
Período com filtros (filtered) | O recorte de pagamentos por marca, grupo de canal, canal ou forma de pagamento. Disponível nas três consultas unificadas de pagamentos. | start_date e end_date, mais os filtros desejados. | Outubro, apenas do canal table. |
A escolha seleciona a variante do serviço de relatórios. Os cálculos e o corpo da resposta seguem essa variante; a API não transforma uma série diária em mensal por soma. Ao mudar para mensal, envie os parâmetros de mês correspondentes. Datas de dia são ignoradas nessa variante; meses são ignorados nas variantes por datas.
Granularidade desconhecida, repetida ou filtered fora dos pagamentos retorna 400 invalid_report_granularity. A validação dos períodos e demais filtros preserva os erros do serviço de origem.
Exemplo: o mesmo resumo por dia ou por mês
GET /v1/reports/payments/summary?restaurant_id=85&granularity=daily&start_date=2026-10-01&end_date=2026-10-31
Authorization: Bearer {access_token}GET /v1/reports/payments/summary?restaurant_id=85&granularity=monthly&start_month=2026-08&end_month=2026-10
Authorization: Bearer {access_token}Exemplo: pagamentos de um canal no período
GET /v1/reports/payments/summary?restaurant_id=85&granularity=filtered&start_date=2026-10-01&end_date=2026-10-31&channel=table
Authorization: Bearer {access_token}brand_id, channel_group, channel e payment_method_id pertencem à variante filtered de pagamentos. Para aplicar esses filtros, selecione essa granularidade explicitamente.
Consultas unificadas
Estas sete consultas selecionam a granularidade pela query, conforme a tabela abaixo. O catálogo publicado contém 41 consultas de relatórios nas quatro famílias.
| Família | Consulta | Rota GET | Granularidade |
|---|---|---|---|
| Pagamentos | Resumo de pagamentos | /v1/reports/payments/summary | Diária, mensal ou período com filtros |
| Pagamentos | Pagamentos por forma | /v1/reports/payments/methods | Diária, mensal ou período com filtros |
| Pagamentos | Pagamentos por canal | /v1/reports/payments/channels | Diária, mensal ou período com filtros |
| Clientes | Resumo de clientes | /v1/reports/customers/summary | Diária ou mensal |
| Clientes | Retenção de clientes | /v1/reports/customers/retention | Diária ou mensal |
| Clientes | Retenção por frequência de visitas | /v1/reports/customers/visit-retention | Diária ou mensal |
| Produtos | Resumo de vendas de produtos | /v1/reports/products/summary | Diária ou mensal |
fill continua disponível nos resumos. Clientes mantém channel e, nas consultas aplicáveis, phone_breakdown. Produtos mantém fill, compare e include_today. O seletor granularity é usado pela external-api e não é enviado ao serviço de relatórios.
Catálogo por família
Os nomes da documentação e das coleções estão em português. Caminhos HTTP, parâmetros, identificadores de operação e campos JSON preservam seus identificadores técnicos.
Pagamentos
Permissão: reports:payments:read.
| Consulta | Rota GET | Filtros |
|---|---|---|
| Transações de pagamento | /v1/reports/payments/transactions | start_date, end_date, payment_method, cursor |
| Atendimentos com pagamentos | /v1/reports/payments/sessions | ano, mes, cursor |
| Resumo de pagamentos | /v1/reports/payments/summary | granularity, start_date, end_date, start_month, end_month, fill, brand_id, channel_group, channel, payment_method_id |
| Pagamentos por forma | /v1/reports/payments/methods | granularity, start_date, end_date, start_month, end_month, brand_id, channel_group, channel, payment_method_id |
| Pagamentos por canal | /v1/reports/payments/channels | granularity, start_date, end_date, start_month, end_month, brand_id, channel_group, channel, payment_method_id |
Clientes
Permissão: reports:customers:read.
| Consulta | Rota GET | Filtros |
|---|---|---|
| Clientes por atividade | /v1/reports/customers/activity/customers | start_date, end_date, segment, channel, origin, visits, mode, has_phone, cursor |
| Funil de visitas | /v1/reports/customers/visit-funnel | start_date, end_date, cohort_start_date, cohort_end_date, min_stage, cursor |
| Clientes por etapa de visitas | /v1/reports/customers/visit-retention/customers | cohort_start_date, cohort_end_date, stage, mode, origin, channel, has_phone, cursor |
| Resumo de clientes | /v1/reports/customers/summary | granularity, start_date, end_date, start_month, end_month, channel, fill, phone_breakdown |
| Retenção de clientes | /v1/reports/customers/retention | granularity, start_date, end_date, start_month, end_month, channel |
| Retenção por frequência de visitas | /v1/reports/customers/visit-retention | granularity, start_date, end_date, start_month, end_month, channel, phone_breakdown |
Produtos
Permissão: reports:products:read.
As séries de resumo usam granularidade diária ou mensal. As listas de produtos, categorias e complementos por mês selecionam um único month; as consultas por período aceitam datas e têm projeções e filtros próprios. Essas análises permanecem identificadas separadamente.
| Consulta | Rota GET | Filtros |
|---|---|---|
| Vendas de hoje | /v1/reports/products/realtime/today | Sem filtros específicos |
| Pedidos de hoje | /v1/reports/products/realtime/today/orders | Sem filtros específicos |
| Curva ABC de produtos | /v1/reports/products/abc | start_date, end_date, view, channel, category_id, include_today |
| Matriz BCG de produtos | /v1/reports/products/bcg | start_date, end_date, view, channel, category_id, include_today |
| Análises de vendas | /v1/reports/products/insights | start_date, end_date |
| Imagens do catálogo | /v1/reports/products/catalog/images | Sem filtros específicos |
| Vendas por categoria e dia | /v1/reports/products/daily/categories | start_date, end_date, include_today |
| Vendas de produtos no mês | /v1/reports/products/monthly/products | month, channel, category_id, include_today |
| Vendas por categoria no mês | /v1/reports/products/monthly/categories | month, include_today |
| Vendas de complementos no mês | /v1/reports/products/monthly/complements | month |
| Vendas por canal no mês | /v1/reports/products/monthly/channels | month |
| Categorias, produtos e complementos do mês | /v1/reports/products/monthly/hierarchy | month |
| Vendas de produtos no período | /v1/reports/products/period/products | start_date, end_date, channel, category_id, include_today |
| Vendas por categoria no período | /v1/reports/products/period/categories | start_date, end_date, include_today |
| Vendas de complementos no período | /v1/reports/products/period/complements | start_date, end_date, channel |
| Participação de produtos nos pedidos | /v1/reports/products/period/order-attach | start_date, end_date |
| Participação de complementos nas vendas | /v1/reports/products/period/complement-attach | start_date, end_date, product_id |
| Cancelamentos no período | /v1/reports/products/period/cancellations | start_date, end_date, group_by, filter_by |
| Detalhamento de vendas de um produto | /v1/reports/products/period/product-sales | start_date, end_date, product_id, cursor |
| Resumo de vendas de produtos | /v1/reports/products/summary | granularity, start_date, end_date, start_month, end_month, fill, compare, include_today |
KDS
Permissão: reports:kds:read.
Todas as consultas do KDS usam um período por datas e seus filtros próprios. Elas medem tempos de preparo, volume e cumprimento de metas; não utilizam o seletor de granularidade dos resumos de vendas.
| Consulta | Rota GET | Filtros |
|---|---|---|
| Visão geral do KDS | /v1/reports/kds/overview | start_date, end_date, kds_ids, channels, channel_groups, compare |
| Mapa de calor do preparo | /v1/reports/kds/heatmap | start_date, end_date, kds_ids, channels, channel_groups |
| Tempo de preparo por estação | /v1/reports/kds/stations | start_date, end_date, kds_ids, channels, channel_groups, compare |
| Tempo de preparo e cumprimento de metas por produto | /v1/reports/kds/products | start_date, end_date, kds_ids, channels, channel_groups, limit, compare |
| Itens com preparo mais demorado | /v1/reports/kds/detractors | start_date, end_date, kds_ids, channels, channel_groups, limit, min_sample, compare |
| Tempo de um produto por canal | /v1/reports/kds/product-channels | start_date, end_date, kds_ids, channels, channel_groups, limit, gap_pct, gap_min, min_orders |
| Tempo de preparo por canal | /v1/reports/kds/channels | start_date, end_date, kds_ids, channels, channel_groups, compare |
| Regularidade do tempo de preparo | /v1/reports/kds/consistency | start_date, end_date, kds_ids, channels, channel_groups |
| Tempo de preparo por garçom | /v1/reports/kds/waiters | start_date, end_date, kds_ids, channels, channel_groups |
| Pedidos com preparo mais demorado | /v1/reports/kds/slowest | start_date, end_date, kds_ids, channels, channel_groups, limit |
Respostas e paginação
O corpo recebido é o JSON do relatório de origem, sem envelope extra. Séries de pagamentos podem usar success, data.records e meta; transações podem trazer data.next_cursor. O KDS usa projeções como summary, daily ou cells. Preserve os filtros e o período ao reutilizar um cursor.
{
"success": true,
"data": { "records": [{ "date": "2026-10-01", "gross_revenue": 1500.25 }] },
"meta": { "cached": false, "records_count": 1 }
}Os relatórios de origem podem retornar corpos e status de validação próprios. Falhas de acesso usam os erros da external-api; indisponibilidade do serviço de relatórios retorna 502 e configuração ausente retorna 503. O KDS tem cache de cinco minutos e exige datas válidas antes da leitura.
Coleções e ferramentas
- Coleção Postman de relatórios: 41 consultas organizadas por família.
- Bruno: pasta Relatórios da external-api, com nomes e orientações em português.
- AI Builders — Testar API: bloco Relatórios, dividido em Pagamentos, Clientes, Produtos e KDS.
- OpenAPI V1: contratos e escopos usados também pelas exportações Markdown e ferramentas de agentes.