Análise Comercial

Gera, por inbox e período, um relatório comercial completo de 9 seções produzido por IA a partir do histórico de conversas (resumo executivo, qualidade do atendimento, comportamento dos leads, objeções, recomendações etc.). A geração é assíncrona.

Licença e permissão

Análise Comercial está incluída em toda licença NooviChat válida. Todos os endpoints são escopados à conta autenticada (multi-tenant) e respeitam a política de acesso do chamador.

Fluxo assíncrono

O fluxo recomendado é: 1) POST para enfileirar a geração (resposta 202 com id e status: processing); 2) consultar /status até completed (ou failed); 3) ler o relatório completo no show; 4) opcionalmente baixar o PDF.

Cache de 24h

Um relatório completed e não-expirado para a mesma combinação (inbox + período) é reaproveitado: o POST retorna o relatório pronto com cache_hit: true em vez de gerar de novo. Envie force: true para forçar uma nova geração.

GET/api/v1/accounts/{account_id}/commercial-analyses

Lista os relatórios da conta (mais recentes primeiro), 20 por página.

Query

Nome	Tipo	Obrigatorio	Descricao
`inbox_id`(query)	`integer`	Nao	Filtra os relatórios de uma inbox específica
`page`(query)	`integer`	Nao	Página (20 por página)

200Lista de relatórios (resumo, sem o corpo do report)

json

{
  "data": [
    {
      "id": 120,
      "inbox_id": 7,
      "period_from": "2026-05-03",
      "period_to": "2026-06-02",
      "status": "completed",
      "messages_count": 1840,
      "leads_count": 73,
      "model_used": "gpt-5.5",
      "error_message": null,
      "expires_at": "2026-06-14T12:00:00Z",
      "created_at": "2026-06-13T12:00:00Z",
      "updated_at": "2026-06-13T12:01:30Z"
    }
  ]
}

POST/api/v1/accounts/{account_id}/commercial-analyses

Enfileira a geração de um relatório para uma inbox num período. Resposta 202 (ou o relatório em cache).

Body

Nome	Tipo	Obrigatorio	Descricao
`inbox_id`	`integer`	Sim	Inbox a analisar (deve pertencer à conta — inexistente retorna 404)
`period_from`	`string (date)`	Sim	Início do período (YYYY-MM-DD)
`period_to`	`string (date)`	Sim	Fim do período (YYYY-MM-DD). Deve ser >= period_from.
`force`	`boolean`	Nao	Ignora o cache de 24h e gera um relatório novo

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/commercial-analyses" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "inbox_id": 7, "period_from": "2026-05-03", "period_to": "2026-06-02" }'

202Geração enfileirada — use o id para consultar o status

json

{ "data": { "id": 120, "status": "processing" } }

200Cache hit — relatório recente reaproveitado (inclui o corpo report)

json

{ "data": { "id": 118, "status": "completed", "report": { "executive_summary": { } } }, "cache_hit": true }

Erros de validação (422)

Período invertido (period_to < period_from) ou período longo demais retornam 422 com {"error": "..."}. Um inbox_id inexistente na conta retorna 404.

GET/api/v1/accounts/{account_id}/commercial-analyses/{id}/status

Consulta leve do status (para polling após o POST).

200Status atual

json

{ "data": { "id": 120, "status": "processing", "expires_at": null } }

status é um de processing, completed ou failed.

GET/api/v1/accounts/{account_id}/commercial-analyses/{id}

Retorna o relatório completo, incluindo o corpo report com as 9 seções.

200Relatório completo (resumo + report)

json

{
  "data": {
    "id": 120,
    "inbox_id": 7,
    "period_from": "2026-05-03",
    "period_to": "2026-06-02",
    "status": "completed",
    "messages_count": 1840,
    "leads_count": 73,
    "model_used": "gpt-5.5",
    "report": {
      "executive_summary": { },
      "attendance_analysis": { },
      "lead_behavior": { },
      "conversation_quality": { },
      "objections_and_barriers": { },
      "trends_and_insights": { },
      "recommendations": { },
      "by_inbox": { },
      "team_analysis": { }
    }
  }
}

GET/api/v1/accounts/{account_id}/commercial-analyses/{id}/export.pdf

Baixa o relatório renderizado em PDF (anexo). Apenas relatórios completed.

Só funciona quando completed

Se o relatório ainda não estiver completed, o endpoint retorna 422.

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/commercial-analyses/120/export.pdf" \
  -H "api_access_token: YOUR_TOKEN" \
  --output analise-comercial-120.pdf

DELETE/api/v1/accounts/{account_id}/commercial-analyses/{id}

Remove um relatório. Retorna 204 (sem conteúdo).

bash

curl -X DELETE "https://chat.seudominio.com/api/v1/accounts/1/commercial-analyses/120" \
  -H "api_access_token: YOUR_TOKEN"