Takeat
Versão da documentação
Relatórios

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

  1. Configure no app OAuth ou na chave de restaurante apenas os escopos necessários: reports:payments:read, reports:customers:read, reports:products:read e reports:kds:read.
  2. Para OAuth, obtenha o consentimento do restaurante por Authorization Code + PKCE. Para API key, faça a troca em POST /oauth/token conforme API key e tokens.
  3. 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.
  4. Em uma credencial com vários restaurantes, envie restaurant_id de uma loja explicitamente autorizada. Um restaurante único pode ser inferido. Uma loja de fora da concessão resulta em 403.
  5. 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çãoO que consultarParâmetros do períodoExemplo
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íliaConsultaRota GETGranularidade
PagamentosResumo de pagamentos/v1/reports/payments/summaryDiária, mensal ou período com filtros
PagamentosPagamentos por forma/v1/reports/payments/methodsDiária, mensal ou período com filtros
PagamentosPagamentos por canal/v1/reports/payments/channelsDiária, mensal ou período com filtros
ClientesResumo de clientes/v1/reports/customers/summaryDiária ou mensal
ClientesRetenção de clientes/v1/reports/customers/retentionDiária ou mensal
ClientesRetenção por frequência de visitas/v1/reports/customers/visit-retentionDiária ou mensal
ProdutosResumo de vendas de produtos/v1/reports/products/summaryDiá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.

ConsultaRota GETFiltros
Transações de pagamento/v1/reports/payments/transactionsstart_date, end_date, payment_method, cursor
Atendimentos com pagamentos/v1/reports/payments/sessionsano, mes, cursor
Resumo de pagamentos/v1/reports/payments/summarygranularity, start_date, end_date, start_month, end_month, fill, brand_id, channel_group, channel, payment_method_id
Pagamentos por forma/v1/reports/payments/methodsgranularity, start_date, end_date, start_month, end_month, brand_id, channel_group, channel, payment_method_id
Pagamentos por canal/v1/reports/payments/channelsgranularity, start_date, end_date, start_month, end_month, brand_id, channel_group, channel, payment_method_id

Clientes

Permissão: reports:customers:read.

ConsultaRota GETFiltros
Clientes por atividade/v1/reports/customers/activity/customersstart_date, end_date, segment, channel, origin, visits, mode, has_phone, cursor
Funil de visitas/v1/reports/customers/visit-funnelstart_date, end_date, cohort_start_date, cohort_end_date, min_stage, cursor
Clientes por etapa de visitas/v1/reports/customers/visit-retention/customerscohort_start_date, cohort_end_date, stage, mode, origin, channel, has_phone, cursor
Resumo de clientes/v1/reports/customers/summarygranularity, start_date, end_date, start_month, end_month, channel, fill, phone_breakdown
Retenção de clientes/v1/reports/customers/retentiongranularity, start_date, end_date, start_month, end_month, channel
Retenção por frequência de visitas/v1/reports/customers/visit-retentiongranularity, 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.

ConsultaRota GETFiltros
Vendas de hoje/v1/reports/products/realtime/todaySem filtros específicos
Pedidos de hoje/v1/reports/products/realtime/today/ordersSem filtros específicos
Curva ABC de produtos/v1/reports/products/abcstart_date, end_date, view, channel, category_id, include_today
Matriz BCG de produtos/v1/reports/products/bcgstart_date, end_date, view, channel, category_id, include_today
Análises de vendas/v1/reports/products/insightsstart_date, end_date
Imagens do catálogo/v1/reports/products/catalog/imagesSem filtros específicos
Vendas por categoria e dia/v1/reports/products/daily/categoriesstart_date, end_date, include_today
Vendas de produtos no mês/v1/reports/products/monthly/productsmonth, channel, category_id, include_today
Vendas por categoria no mês/v1/reports/products/monthly/categoriesmonth, include_today
Vendas de complementos no mês/v1/reports/products/monthly/complementsmonth
Vendas por canal no mês/v1/reports/products/monthly/channelsmonth
Categorias, produtos e complementos do mês/v1/reports/products/monthly/hierarchymonth
Vendas de produtos no período/v1/reports/products/period/productsstart_date, end_date, channel, category_id, include_today
Vendas por categoria no período/v1/reports/products/period/categoriesstart_date, end_date, include_today
Vendas de complementos no período/v1/reports/products/period/complementsstart_date, end_date, channel
Participação de produtos nos pedidos/v1/reports/products/period/order-attachstart_date, end_date
Participação de complementos nas vendas/v1/reports/products/period/complement-attachstart_date, end_date, product_id
Cancelamentos no período/v1/reports/products/period/cancellationsstart_date, end_date, group_by, filter_by
Detalhamento de vendas de um produto/v1/reports/products/period/product-salesstart_date, end_date, product_id, cursor
Resumo de vendas de produtos/v1/reports/products/summarygranularity, 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.

ConsultaRota GETFiltros
Visão geral do KDS/v1/reports/kds/overviewstart_date, end_date, kds_ids, channels, channel_groups, compare
Mapa de calor do preparo/v1/reports/kds/heatmapstart_date, end_date, kds_ids, channels, channel_groups
Tempo de preparo por estação/v1/reports/kds/stationsstart_date, end_date, kds_ids, channels, channel_groups, compare
Tempo de preparo e cumprimento de metas por produto/v1/reports/kds/productsstart_date, end_date, kds_ids, channels, channel_groups, limit, compare
Itens com preparo mais demorado/v1/reports/kds/detractorsstart_date, end_date, kds_ids, channels, channel_groups, limit, min_sample, compare
Tempo de um produto por canal/v1/reports/kds/product-channelsstart_date, end_date, kds_ids, channels, channel_groups, limit, gap_pct, gap_min, min_orders
Tempo de preparo por canal/v1/reports/kds/channelsstart_date, end_date, kds_ids, channels, channel_groups, compare
Regularidade do tempo de preparo/v1/reports/kds/consistencystart_date, end_date, kds_ids, channels, channel_groups
Tempo de preparo por garçom/v1/reports/kds/waitersstart_date, end_date, kds_ids, channels, channel_groups
Pedidos com preparo mais demorado/v1/reports/kds/sloweststart_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.

On this page