Analise Comercial

Gera, por inbox e periodo, um relatorio comercial completo de 9 secoes produzido por IA a partir do historico de conversas (resumo executivo, qualidade do atendimento, comportamento dos leads, objecoes, recomendacoes etc.). A geracao e assincrona.

Licenca e permissao

Analise Comercial esta incluida em toda licenca NooviChat valida. Todos os endpoints sao escopados a conta autenticada (multi-tenant) e respeitam a politica de acesso do chamador.

Fluxo assincrono

O fluxo recomendado e: 1) POST para enfileirar a geracao (resposta 202 com id e status: processing); 2) consultar /status ate completed (ou failed); 3) ler o relatorio completo no show; 4) opcionalmente baixar o PDF.

Cache de 24h

Um relatorio completed e nao-expirado para a mesma combinacao (inbox + periodo) e reaproveitado: o POST retorna o relatorio pronto com cache_hit: true em vez de gerar de novo. Envie force: true para forcar uma nova geracao.

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

Lista os relatorios da conta (mais recentes primeiro), 20 por pagina.

Query

Nome	Tipo	Obrigatorio	Descricao
`inbox_id`(query)	`integer`	Nao	Filtra os relatorios de uma inbox especifica
`page`(query)	`integer`	Nao	Pagina (20 por pagina)

200Lista de relatorios (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 geracao de um relatorio para uma inbox num periodo. Resposta 202 (ou o relatorio em cache).

Body

Nome	Tipo	Obrigatorio	Descricao
`inbox_id`	`integer`	Sim	Inbox a analisar (deve pertencer a conta — inexistente retorna 404)
`period_from`	`string (date)`	Sim	Inicio do periodo (YYYY-MM-DD)
`period_to`	`string (date)`	Sim	Fim do periodo (YYYY-MM-DD). Deve ser >= period_from.
`force`	`boolean`	Nao	Ignora o cache de 24h e gera um relatorio 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" }'

202Geracao enfileirada — use o id para consultar o status

json

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

200Cache hit — relatorio recente reaproveitado (inclui o corpo report)

json

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

Erros de validacao (422)

Periodo invertido (period_to < period_from) ou periodo longo demais retornam 422 com {"error": "..."}. Uma inbox_id inexistente na conta retorna 404.

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

Consulta leve do status (para polling apos o POST).

200Status atual

json

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

status e um de processing, completed ou failed.

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

Retorna o relatorio completo, incluindo o corpo report com as 9 secoes.

200Relatorio 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 relatorio renderizado em PDF (anexo). Apenas relatorios completed.

So funciona quando completed

Se o relatorio ainda nao 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 relatorio. Retorna 204 (sem conteudo).

bash

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