# API Analytics de Volume de Opt-In por Canal

Recupera estatísticas de volume de interações de clientes em todos os canais de comunicação com suporte a filtragem por intervalo de datas e contagem de clientes únicos.

# Headers Obrigatórios

Header Tipo Obrigatório Descrição
authorization Authorization Bearer Token ✔️ A chave da sua API
accept application/json ✔️

# Cache

Este endpoint está em cache por 5 minutos. As respostas são cacheadas para melhorar o desempenho.

# Métodos Disponíveis

Este endpoint suporta apenas o método GET.

# GET - Buscar Analytics de Volume por Canal

  GET https://hermes.g121.io/v1/analytics/general/channel-opt-volume

Recupera estatísticas de volume de interações de clientes em todos os canais de comunicação via requisição GET. Os parâmetros de query devem ser passados como parâmetros de URL.

# Parâmetros de Query

Parâmetro Tipo Obrigatório Padrão Descrição
daysAgo Integer ️ 30 Número de dias para olhar para trás a partir de hoje (1-365, padrão 30)
startDate String ️ Data de início para intervalo de datas personalizado (formato ISO 8601, deve estar pareado com endDate)
endDate String ️ Data de término para intervalo de datas personalizado (formato ISO 8601, máximo 90 dias de startDate)
unique Boolean ️ false Contar clientes únicos por clientId em vez de interações totais (padrão false)

# Modos de Consulta

  1. Modo Padrão: Sem parâmetros (últimos 30 dias)
  2. Modo Days Ago: Forneça daysAgo (1-365 dias)
  3. Modo Intervalo de Datas: Forneça startDate e endDate (máximo 90 dias, formato YYYY-MM-DD)

Nota: Os limites de data são definidos em dias completos (00:00:00 a 23:59:59)

curl -X GET 'https://hermes.g121.io/v1/analytics/general/channel-opt-volume?daysAgo=30' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (últimos 30 dias):

{
  "status": "ok",
  "period": {
    "start": "2025-11-23T00:00:00.000Z",
    "end": "2025-12-23T23:59:59.999Z",
    "daysAgo": 30
  },
  "total": 350,
  "uniqueClients": false,
  "breakdown": [
    {
      "channel": "whatsapp",
      "count": 150
    },
    {
      "channel": "widget",
      "count": 120
    },
    {
      "channel": "messenger",
      "count": 80
    }
  ]
}

# Exemplo com Intervalo de Datas Personalizado

curl -X GET 'https://hermes.g121.io/v1/analytics/general/channel-opt-volume?startDate=2025-12-01&endDate=2025-12-23' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (intervalo personalizado de 23 dias):

{
  "status": "ok",
  "period": {
    "start": "2025-12-01T00:00:00.000Z",
    "end": "2025-12-23T23:59:59.999Z",
    "daysAgo": 23
  },
  "total": 280,
  "uniqueClients": false,
  "breakdown": [
    {
      "channel": "whatsapp",
      "count": 140
    },
    {
      "channel": "widget",
      "count": 100
    },
    {
      "channel": "messenger",
      "count": 40
    }
  ]
}

# Exemplo Contando Clientes Únicos

curl -X GET 'https://hermes.g121.io/v1/analytics/general/channel-opt-volume?daysAgo=7&unique=true' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (últimos 7 dias com clientes únicos):

{
  "status": "ok",
  "period": {
    "start": "2025-12-16T00:00:00.000Z",
    "end": "2025-12-23T23:59:59.999Z",
    "daysAgo": 7
  },
  "total": 125,
  "uniqueClients": true,
  "breakdown": [
    {
      "channel": "whatsapp",
      "count": 85
    },
    {
      "channel": "widget",
      "count": 30
    },
    {
      "channel": "messenger",
      "count": 10
    }
  ]
}

# Canais Disponíveis

Os seguintes canais são suportados no breakdown:

  • whatsapp - WhatsApp
  • whatsapp_business - WhatsApp Business
  • widget - Chat Widget
  • messenger - Facebook Messenger
  • instagram - Instagram Direct
  • email - Email

# Códigos de Status

Status Descrição
200 Sucesso ao obter as análises
400 Requisição inválida - parâmetros inválidos
401 Não autorizado - token inválido ou ausente
500 Erro interno do servidor

# Erros Comuns (400)

Erro Descrição
daysAgo deve estar entre 1 e 365 daysAgo fora do intervalo permitido
O intervalo de datas deve estar entre startDate e endDate, máximo 90 dias de diferença Intervalo de datas inválido ou > 90 dias
O intervalo de datas deve estar entre startDate e endDate, máximo 90 dias de diferença Apenas uma data foi fornecida (ambas são obrigatórias)