Métricas

As métricas transformam a agenda em indicadores acionáveis: quanto a unidade atende, quanto fatura, quem mais falta e quais horários lotam. Com esses relatórios, a equipe ajusta escala, preço e política de cancelamento com dados — não com sensação.

Todos os endpoints desta página são de somente leitura (GET) e retornam arrays ou objetos prontos para alimentar dashboards e gráficos — sem paginação.

Headers obrigatórios

Todas as requisições devem incluir o header X-Booking-Id (UUID) e Authorization: Bearer {token} com o token de um usuário staff. Endpoints de métricas não são públicos nem acessíveis a clientes.

---

Filtros comuns e escopo por profissional

Todos os relatórios exigem um período e aceitam o escopo de profissional:

Nome	Tipo	Obrigatório	Descrição
from	string	Sim	Data inicial do período, no formato YYYY-MM-DD.
to	string	Sim	Data final do período, no formato YYYY-MM-DD.

O período é aplicado sobre startsAt (o horário do atendimento) — exceto newCustomers, que usa a data de cadastro do cliente.

Escopo RBAC por profissional

owner, manager e receptionist enxergam a instância inteira. Usuários professional recebem os indicadores restritos aos próprios atendimentos; sem vínculo de profissional, recebem contagens zeradas — nunca dados de outros profissionais.

---

Endpoints

KPIs Gerais

Retorna os indicadores-chave da operação em um único objeto, ideal para os cartões do topo de um dashboard.

GET /v1/booking/user/metrics/kpis

Parâmetros de Query

Aceita os filtros comuns: from e to (obrigatórios).

Campos da Resposta

Campo	Tipo	Descrição
totalAppointments	Number	Agendamentos no período.
pending / confirmed / completed / canceled / noShow	Number	Contagem por status.
noShowRate	Number | null	Taxa de falta: no_show ÷ (completed + no_show). null quando não há finalizáveis.
cancellationRate	Number | null	Taxa de cancelamento: canceled ÷ total. null quando não há agendamentos.
realizedRevenue	Number	Receita realizada: soma de totalPrice dos completed.
expectedRevenue	Number	Receita prevista: soma de totalPrice dos pending + confirmed.
avgTicket	Number | null	Ticket médio dos completed. null quando não há concluídos.
newCustomers	Number	Clientes cadastrados no período.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/metrics/kpis?from=2026-09-01&to=2026-09-30" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o objeto com os KPIs.

{
  "totalAppointments": 42,
  "pending": 5,
  "confirmed": 12,
  "completed": 20,
  "canceled": 3,
  "noShow": 2,
  "noShowRate": 0.0909,
  "cancellationRate": 0.0714,
  "realizedRevenue": 1840,
  "expectedRevenue": 1360,
  "avgTicket": 92,
  "newCustomers": 7
}

422 Unprocessable Entity

Ocorre quando from ou to não são enviados.

{
  "errors": [
    {
      "message": "A data inicial é obrigatória",
      "rule": "required",
      "field": "from"
    }
  ]
}

Evolução de Agendamentos

Retorna uma série temporal de agendamentos por período com a receita realizada em cada bucket — a base para gráficos de linha ou área.

GET /v1/booking/user/metrics/appointments

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
groupBy	enum	Sim	Granularidade da série: day, week ou month.
from	string	Sim	Data inicial do período (YYYY-MM-DD).
to	string	Sim	Data final do período (YYYY-MM-DD).

Cada ponto da série traz date (início do bucket, YYYY-MM-DD), appointments (total) e revenue (soma dos completed no bucket).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/metrics/appointments?groupBy=day&from=2026-09-01&to=2026-09-30" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o array de pontos da série temporal, ordenado pela data.

[
  {
    "date": "2026-09-01",
    "appointments": 6,
    "revenue": 480
  },
  {
    "date": "2026-09-02",
    "appointments": 4,
    "revenue": 320
  }
]

422 Unprocessable Entity

Ocorre quando groupBy não é enviado ou tem valor inválido.

Ranking de Serviços

Retorna os serviços mais vendidos no período, com quantidade de atendimentos e receita realizada — o relatório para decidir o que destacar no menu do portal.

GET /v1/booking/user/metrics/services-ranking

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
from	string	Sim	Data inicial do período (YYYY-MM-DD).
to	string	Sim	Data final do período (YYYY-MM-DD).
limit	number	Não	Quantidade máxima de serviços no ranking (entre 1 e 50, padrão: 10).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/metrics/services-ranking?from=2026-09-01&to=2026-09-30&limit=10" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o ranking ordenado por quantidade de atendimentos, decrescente.

[
  {
    "serviceId": 1,
    "serviceName": "Corte Masculino",
    "total": 28,
    "revenue": 2240
  },
  {
    "serviceId": 3,
    "serviceName": "Barba Completa",
    "total": 14,
    "revenue": 840
  }
]

Ranking de Profissionais

Retorna os profissionais com mais atendimentos no período, com receita realizada — o retrato de produtividade da equipe.

GET /v1/booking/user/metrics/professionals-ranking

Parâmetros de Query

Mesmos parâmetros do ranking de serviços: from, to (obrigatórios) e limit (opcional).

Respostas

200 OK

Retorna o ranking ordenado por quantidade de atendimentos, decrescente.

[
  {
    "professionalId": 1,
    "professionalName": "Ana Souza",
    "total": 32,
    "revenue": 2880
  }
]

Distribuição por Origem

Retorna a contagem de agendamentos por canal de origem (online, phone, walk_in, admin, api) — quanto da sua agenda vem do portal versus o balcão.

GET /v1/booking/user/metrics/sources

Parâmetros de Query

Aceita os filtros comuns: from e to (obrigatórios).

Respostas

200 OK

Retorna o array de origens com seus totais, ordenado por total decrescente.

[
  {
    "source": "online",
    "total": 25
  },
  {
    "source": "phone",
    "total": 12
  },
  {
    "source": "walk_in",
    "total": 5
  }
]

Horários de Pico

Retorna a contagem de agendamentos por hora do dia (0–23), ordenada pela hora — o relatório para montar escalas e abrir hora extra onde dói.

GET /v1/booking/user/metrics/peak-hours

Parâmetros de Query

Aceita os filtros comuns: from e to (obrigatórios).

Respostas

200 OK

Retorna o array de horas com seus totais, ordenado pela hora do dia.

[
  {
    "hour": 9,
    "total": 8
  },
  {
    "hour": 10,
    "total": 11
  },
  {
    "hour": 18,
    "total": 9
  }
]