Referência completa dos endpoints REST públicos disponíveis para integrações externas via API Key.

Endpoints da API

Estes são os endpoints REST públicos disponíveis para integrações externas via autenticação por API Key.

Todas as requisições devem incluir o header X-API-Key com uma API Key válida.

GET /api/salespersons

Lista os vendedores e supervisores da empresa autenticada.

Fluxo de Uso

Chame GET /api/salespersons para obter a lista de vendedores da sua empresa.
Localize o vendedor desejado e copie o id dele.
Use esse id no campo salespersonId ao fazer uma requisição POST /api/analyses. Isso garante que a análise seja gerada conforme a função de trabalho específica do vendedor.

Headers

Header	Obrigatório	Descrição
`X-API-Key`	Sim	Sua API Key

Resposta

[
  {
    "id": "user_xxx",
    "name": "João Silva",
    "role": "salesperson",
    "jobFunctionName": "SDR",
    "supervisorName": "Maria Souza"
  },
  {
    "id": "user_yyy",
    "name": "Maria Souza",
    "role": "supervisor",
    "jobFunctionName": "Sales Manager",
    "supervisorName": null
  }
]

Campos da Resposta

Campo	Tipo	Descrição
`id`	`string`	ID único do usuário (use em `POST /api/analyses`)
`name`	`string`	Nome completo
`role`	`string`	`"salesperson"` ou `"supervisor"`
`jobFunctionName`	`string \| null`	Nome da função de trabalho atribuída
`supervisorName`	`string \| null`	Nome do supervisor atribuído

POST /api/analyses

Cria uma nova análise de vendas com IA. Requer transcript ou audioKey.

Headers

Header	Obrigatório	Descrição
`X-API-Key`	Sim	Sua API Key
`Content-Type`	Sim	`application/json`

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`transcript`	`string`	Um de `transcript` ou `audioKey`	Transcrição completa da ligação de vendas
`audioKey`	`string`	Um de `transcript` ou `audioKey`	Fonte de áudio (veja Opções de Entrada de Áudio abaixo)
`salespersonId`	`string`	Não	ID do vendedor (obtido via `GET /api/salespersons`)
`salespersonName`	`string`	Não	Nome do vendedor
`clientName`	`string`	Não	Nome do cliente

Opções de Entrada de Áudio

Você pode fornecer áudio via o campo audioKey de três formas:

URL direta: URL HTTP/HTTPS de um arquivo de áudio (ex: "https://exemplo.com/audio.mp3")
Base64: Data URL com áudio codificado em base64 (ex: "data:audio/mp3;base64,SGVsbG8g...")

Formatos suportados: mp3, mp4, wav, ogg, opus

Exemplo de Requisição (com transcript)

{
  "salespersonId": "user_1234567890",
  "clientName": "Cliente Teste",
  "transcript": "Olá, meu nome é João da evoluAI..."
}

Exemplo de Requisição (com URL de áudio)

{
  "salespersonId": "user_1234567890",
  "clientName": "Cliente Teste",
  "audioKey": "https://exemplo.com/audio.mp3"
}

Resposta

{
  "id": "anal_xxx",
  "score": 87,
  "summary": "O vendedor demonstrou forte rapport...",
  "clientName": "Cliente Teste",
  "salespersonName": "João Silva",
  "audioDurationSeconds": 420,
  "dimensionScores": {
    "rapport": 90,
    "listening": 85,
    "objections": 80,
    "clarity": 88
  },
  "interactionType": "outbound-prospecting",
  "interactionScore": 82,
  "interactionScorecard": {
    "typeKey": "outbound-prospecting",
    "typeLabel": "Prospecção Outbound",
    "macroFront": "comercial",
    "score": 82,
    "confidence": 0.9,
    "criteria": [
      {
        "key": "string",
        "label": "string",
        "polarity": "objective",
        "met": true,
        "evidence": "string",
        "timestamp": "01:23"
      }
    ]
  },
  "universalIndicators": {
    "methodAdherence": {
      "score": 75,
      "steps": [
        { "key": "string", "label": "string", "present": true, "timestamp": "00:12" }
      ]
    },
    "talkToListen": { "attendantPct": 40, "clientPct": 60 },
    "interruptions": { "count": 2, "perTenMinutes": 1.5 },
    "emotionalClimate": {
      "start": "neutral",
      "middle": "positive",
      "end": "positive",
      "overall": "positive"
    }
  },
  "objections": [{"objection": "Preocupação com preço", "resolved": true}],
  "productExploration": {
    "explored": true,
    "products": ["Produto A"]
  },
  "keywordDetection": {
    "client_terms": [
      { "term": "preço", "polarity": "negative", "category": "objection", "context": null }
    ],
    "attendant_terms": []
  },
  "profile": "Consultivo",
  "stage": "Qualify",
  "bant": {
    "budget": "string",
    "authority": "string",
    "need": "string",
    "timing": "string"
  },
  "publicLink": "https://app.evoluai.com.br/analysis/anal_xxx",
  "createdAt": "2024-01-15T12:00:00.000Z"
}

Nota: os campos strengths, improvements e phaseSuggestions foram descontinuados e não são mais retornados.

Respostas de Erro

Status	Código	Descrição
400	`BAD_REQUEST`	`transcript` e `audioKey` ausentes
401	`UNAUTHORIZED`	API Key inválida ou ausente
403	`FORBIDDEN`	Minutos/créditos insuficientes
404	`NOT_FOUND`	Vendedor não encontrado
429	`TOO_MANY_REQUESTS`	Rate limit atingido

Retorna a análise completa por ID: todos os campos do dossiê (scorecard, indicadores, diagnóstico, transcrição) mais os metadados internos (custo, tokens, observabilidade, integrações). A análise precisa pertencer à empresa da API Key — análises de outra empresa retornam 404 (isolamento multi-tenant).

Parâmetros de Path

Parâmetro	Tipo	Descrição
`id`	`string`	ID (uuid) da análise

Headers

Header	Obrigatório	Descrição
`X-API-Key`	Sim	Sua API Key

Resposta

{
  "id": "anal_xxx",
  "status": "completed",
  "source": "api",
  "createdAt": "2024-01-15T12:00:00.000Z",
  "updatedAt": "2024-01-15T12:05:00.000Z",
  "salespersonName": "João Silva",
  "clientName": "Cliente Teste",
  "supervisorName": "Maria Souza",

  "displayScore": 82,
  "score": 87,
  "interactionScore": 82,
  "summary": "O vendedor demonstrou forte rapport...",
  "profile": "Consultivo",
  "stage": "Qualify",

  "interactionType": "outbound-prospecting",
  "interactionTypeSource": "auto",
  "interactionScorecard": {
    "typeKey": "outbound-prospecting",
    "typeLabel": "Prospecção Outbound",
    "macroFront": "comercial",
    "score": 82,
    "confidence": 0.9,
    "criteria": [
      {
        "key": "string",
        "label": "string",
        "polarity": "objective",
        "met": true,
        "evidence": "string",
        "timestamp": "01:23"
      }
    ]
  },

  "universalIndicators": {
    "methodAdherence": {
      "score": 75,
      "steps": [
        { "key": "string", "label": "string", "present": true, "timestamp": "00:12" }
      ]
    },
    "talkToListen": { "attendantPct": 40, "clientPct": 60 },
    "interruptions": { "count": 2, "perTenMinutes": 1.5 },
    "emotionalClimate": {
      "start": "neutral", "middle": "positive",
      "end": "positive", "overall": "positive"
    }
  },
  "methodAdherenceScore": 75,
  "attendantTalkPct": 40,
  "interruptionsPerTenMin": 1.5,
  "climateLabel": "positive",

  "diagnostic": {
    "executive_summary": "Cliente interessado em automação...",
    "client_profile": {
      "tone": "analytical", "engagement": "active",
      "confidence": "high", "details": "Fez perguntas técnicas."
    },
    "core_motivation": { "problem": "Processo manual", "impact": "Perda de vendas" },
    "hard_data": { "collected": ["Equipe de 5"], "missing": ["Orçamento"] },
    "agent_evaluation": { "posture": "Cordial", "solution_effectiveness": "Avançou a negociação" },
    "next_steps": { "status": "scheduled", "responsibilities": ["Enviar proposta"] }
  },

  "dimensionScores": { "rapport": 90, "listening": 85, "objections": 80, "clarity": 88 },
  "bant": { "budget": "string", "authority": "string", "need": "string", "timing": "string" },
  "objections": [{ "objection": "Preço alto", "resolved": true }],
  "productExploration": { "explored": true, "products": ["Produto A"] },
  "keywordDetection": {
    "client_terms": [
      { "term": "preço", "polarity": "negative", "category": "objection", "context": null }
    ],
    "attendant_terms": []
  },

  "transcript": "Transcrição completa da conversa...",
  "transcriptSegments": [
    { "start": 0, "end": 5, "text": "Olá", "speaker": "Speaker 1" }
  ],
  "audioUrl": "https://storage.../audio.mp3",
  "audioKey": "audio/xyz.mp3",
  "audioDurationSeconds": 420,

  "tokensUsed": 1234,
  "cost": 0.42,
  "jobId": null,
  "errorSource": null,
  "errorDetail": null,
  "autoRetryCount": 0,
  "archivedAt": null,

  "provider": null,
  "externalCallId": null,
  "externalOwnerId": null,
  "attributionStatus": "auto",
  "participants": null,
  "salespersonId": "user_xxx",
  "companyId": "company_xxx"
}

Regras do Contrato

Regra	Descrição
`displayScore`	Nota oficial da análise: `interactionScore ?? score ?? null`. `null` = sem nota (nunca retorna `0` inventado)
Blocos jsonb	`interactionScorecard`, `universalIndicators`, `diagnostic`, `dimensionScores`, `bant`, `objections`, `productExploration`, `keywordDetection`, `transcriptSegments` vêm `null` quando ausentes ou em formato legado — nunca erro 500
`transcriptSegments[].start/end`	Segundos (`number`) ou `"MM:SS"` legado (`string`)
`timestamps` de critérios/etapas	Formato `"MM:SS"` ou `null`
`stage`	`Connect`, `Qualify`, `Present`, `Close`, `Negotiate` ou `null`
Campos descontinuados	`strengths`, `improvements`, `phaseSuggestions` não existem mais na resposta
`audioUrl`	URL de playback resolvida na leitura; `audioKey` é a chave de storage original

Respostas de Erro

Status	Código	Descrição
401	`UNAUTHORIZED`	API Key ausente, inválida ou expirada
404	`NOT_FOUND`	Análise não encontrada ou pertence a outra empresa

Endpoints

Endpoints da API

GET /api/salespersons

Fluxo de Uso

Headers

Resposta

Campos da Resposta

POST /api/analyses

Headers

Corpo da Requisição

Opções de Entrada de Áudio

Exemplo de Requisição (com transcript)

Exemplo de Requisição (com URL de áudio)

Resposta

Respostas de Erro

GET /api/analyses/{id}

Parâmetros de Path

Headers

Resposta

Regras do Contrato

Respostas de Erro

On this page