--- url: https://docs.ouvixpro.ai/guia/comecando.md description: >- Da criação da chave à primeira resposta: base URL, endpoints, exemplos em cURL, Python e Node, e como ir do atendimento ao áudio e à tela pronta. --- # Começando Este guia leva você da criação da chave até a leitura da primeira resposta. Em cinco minutos você terá o painel de um dia inteiro em JSON. ## Visão geral A OuvixPRO API expõe, por HTTP, os dados que o painel da recepção exibe: atendimentos, protocolo de venda, renovações, fluxo de entrada e saída, qualidade, horários de pico e insights. Cada atendimento aponta para o trecho de áudio que o originou, e esse trecho pode ser baixado pela própria API. | Característica | Valor | | --- | --- | | **Base URL** | `https://api.ouvixpro.ai` | | **Protocolo** | HTTPS, somente `GET` | | **Formato** | JSON (UTF-8); áudio em `audio/wav` | | **Autenticação** | `Authorization: Bearer ` | | **Versão** | `v1`, no caminho de todos os endpoints | ## Endpoints | Endpoint | Para quê | | --- | --- | | `GET /v1/painel` | O painel completo de uma unidade em um período: números brutos e as telas prontas em `painel.tela`. | | `GET /v1/tela` | Só as telas prontas, as listas de evidência e os atendimentos que elas usam. Para desenhar sem calcular nada. | | `GET /v1/catalogo` | Rótulos, cores, metas e catálogo de planos. Não depende de período. | | `GET /v1/atendimentos/{id}` | Um atendimento específico, com todos os campos. | | `GET /v1/atendimentos/{id}/audio` | O áudio desse atendimento, já recortado, em WAV. | | `GET /v1/health` | Verificação de disponibilidade; não exige chave. | Os endpoints de painel, tela e atendimento recebem os mesmos três parâmetros obrigatórios: `Id_unidade`, `de` e `ate`. O catálogo só precisa da chave. ## Passo 1 — Crie a chave No painel, abra o menu da conta e acesse **Chaves de API**. Dê um nome à chave (por exemplo, o sistema que vai consumi-la) e confirme. O valor completo aparece **uma única vez**; copie-o para um cofre de segredos ou variável de ambiente. ```bash export OUVIX_API_KEY="sk_sky_..." ``` A chave enxerga todas as unidades vinculadas à sua conta. Detalhes em [Autenticação](/guia/autenticacao). ## Passo 2 — Faça a primeira chamada Consulte o painel da unidade `375` em um dia: ::: code-group ```bash [cURL] curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ```python [Python] import os import json import urllib.request url = "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08" req = urllib.request.Request(url, headers={"Authorization": f"Bearer {os.environ['OUVIX_API_KEY']}"}) with urllib.request.urlopen(req) as res: painel = json.load(res)["painel"] print(painel["total"], "atendimentos;", painel["protocolo"]["fechouN"], "planos fechados") ``` ```js [Node.js] const url = 'https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08' const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.OUVIX_API_KEY}` } }) if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.json()).error.message}`) const { painel } = await res.json() console.log(`${painel.total} atendimentos; ${painel.protocolo.fechouN} planos fechados`) ``` ::: ## Passo 3 — Leia a resposta O envelope repete os parâmetros da chamada e entrega o painel em `painel`: ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-08", "ate": "2026-10-08", "turno": "todos", "painel": { "total": 24, "mediaNota": 7.4, "atendimentos": [ { "id": "2026-10-08:atend_01", "horario": "07:02:15", "tipo": "checkin", "audio": { "url": "/v1/atendimentos/2026-10-08:atend_01/audio", "duracao_s": 85, "partes": 1 } } ], "protocolo": { "vendasN": 10, "fechouN": 6, "fechadas": [], "abertas": [], "semDesfecho": [] }, "insights": [], "novosAlunos": [] } } ``` Cada bloco de `painel` tem a sua própria página de referência, com todos os campos e um exemplo real: | Bloco | Página | | --- | --- | | Números gerais, alertas, lista de atendimentos | [Resumo](/visoes/geral) | | Conversas de plano, funil e desfecho | [Protocolo](/visoes/venda) | | Migração de plano | [Renovação](/visoes/renovacao) | | Visitantes e alunos novos | [Novos alunos](/visoes/comercial) | | Pendências, decisões e riscos | [Insights](/visoes/insights) | | Catraca, entrada × saída, qualidade, horários | [Recepção](/visoes/acesso) | | O objeto de um atendimento | [Atendimento](/visoes/atendimento) | ## Passo 4 — Vá do atendimento ao áudio Todo atendimento tem um `id` no formato `data:atendimento_id` e um bloco `audio` com a URL do trecho. Com os mesmos parâmetros da chamada anterior, você busca o objeto completo e baixa o áudio — já recortado, em WAV, com dados pessoais em silêncio: ```bash # o atendimento curl "https://api.ouvixpro.ai/v1/atendimentos/2026-10-08:atend_01?Id_unidade=375&de=2026-10-08&ate=2026-10-08" \ -H "Authorization: Bearer $OUVIX_API_KEY" # o áudio dele curl -o atendimento.wav \ "https://api.ouvixpro.ai/v1/atendimentos/2026-10-08:atend_01/audio?Id_unidade=375&de=2026-10-08&ate=2026-10-08" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ## Passo 5 — Desenhe a tela sem calcular nada Se o objetivo é mostrar o painel no seu sistema, não some nem compare: `painel.tela` (ou `GET /v1/tela`) já traz cada card com o texto exibido, o tom de cor e a lista de conversas que abre ao clicar. ```bash curl "https://api.ouvixpro.ai/v1/tela?Id_unidade=375&de=2026-10-08&ate=2026-10-08&tela=resumo" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ```json { "tela": { "resumo": { "kpis": [ { "chave": "nota", "label": "Nota da recepção", "valor": "7.4/10", "numero": 7.4, "tone": "warn", "hint": "Média da qualidade percebida", "lista": null }, { "chave": "graves", "label": "Graves", "valor": "0", "numero": 0, "tone": "ok", "hint": "Trechos para feedback 1:1", "lista": "graves" } ] } }, "listas": { "graves": { "titulo": "Graves · 0", "hint": "…", "ids": [], "badges": {}, "notas": {} } }, "atendimentos": [] } ``` O guia [Montando a tela](/guia/telas) percorre as nove telas bloco a bloco, com receitas de painel de evidências e botão de ouvir. ## Convenções Três regras valem em todo o `painel`: 1. **Ordem cronológica.** Toda lista de atendimentos vem ordenada por `data_ref` e `horario`, do mais cedo para o mais tarde. 2. **Um `id` por conversa.** O mesmo `id` identifica a conversa em qualquer lista em que ela apareça (`atendimentos`, `novosAlunos`, `protocolo.vendas`, `insights[].itens`…), e é o que `/v1/atendimentos/{id}` espera. 3. **Três desfechos de venda.** `fechou=true` fechou um plano; `fechou=false` saiu sem fechar; `fechou=null` o áudio não mostra o fim. A regra completa está em [Protocolo](/visoes/venda). ::: tip Privacidade Resumos e evidências já vêm sem documento e sem nome completo. No áudio, os trechos com dados pessoais são entregues em silêncio. A API não expõe arquivos de gravação nem identificadores internos. ::: ## Próximos passos * [Montando a tela](/guia/telas) — reproduza o painel no seu sistema a partir de `tela`, `listas` e `rotulos`. * [Autenticação](/guia/autenticacao) — escopo da chave, rotação e revogação. * [Período e turno](/guia/periodo) — intervalos, limite de 31 dias e filtro por turno. * [Limites e erros](/guia/erros) — códigos de erro, status HTTP e limite de requisições. * [Novidades](/guia/novidades) — o que mudou na resposta da API. --- --- url: https://docs.ouvixpro.ai/guia/autenticacao.md description: >- Chaves de API: como criar, enviar como Bearer token, escopo por unidade, rotação e revogação. --- # Autenticação Toda chamada de dados é autenticada por uma chave de API enviada como *Bearer token* no cabeçalho `Authorization`. ```http GET /v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08 HTTP/1.1 Host: api.ouvixpro.ai Authorization: Bearer sk_sky_... ``` ## Como obter uma chave 1. Entre no painel com a conta da academia. 2. No menu da conta, abra **Chaves de API**. 3. Clique em **Nova chave**, dê um nome que identifique quem vai usá-la (por exemplo, `ERP financeiro`) e confirme. 4. Copie o valor exibido. Ele aparece **uma única vez**: a plataforma guarda apenas um *hash* e não consegue mostrá-lo de novo. Se perder a chave, revogue-a e crie outra. ## Escopo Uma chave enxerga **todas as unidades vinculadas à conta que a criou**, e nada além delas. A unidade desejada é informada em cada chamada pelo parâmetro `Id_unidade`. * Uma unidade nova, ao ser vinculada à conta, passa a valer nas chaves já existentes. * Um `Id_unidade` de outra academia responde `403 unidade_negada`. * Chaves são somente leitura: a API não altera dados. ## Revogação Em **Chaves de API**, use **Revogar** na chave desejada. O efeito é imediato: a próxima chamada com ela responde `401 chave_invalida`. Uma conta pode manter até 20 chaves ativas. ## Boas práticas * Guarde a chave em um cofre de segredos ou em variável de ambiente, nunca no código-fonte nem em repositórios. * Use uma chave por sistema consumidor. Assim a revogação de uma integração não afeta as outras. * Envie a chave sempre no cabeçalho `Authorization`. A API não aceita chave na *query string*. * Chame a API apenas a partir de servidores. Não exponha a chave em aplicações de navegador ou celular. * Rotacione a chave periodicamente: crie a nova, troque na integração e revogue a antiga. ## Erros relacionados | HTTP | `code` | Causa | | --- | --- | --- | | 401 | `chave_ausente` | Cabeçalho `Authorization: Bearer` não enviado. | | 401 | `chave_invalida` | Chave inexistente, digitada errado ou revogada. | | 403 | `unidade_negada` | A chave não tem acesso ao `Id_unidade` informado. | O formato do corpo de erro está em [Limites e erros](/guia/erros). --- --- url: https://docs.ouvixpro.ai/guia/unidades.md description: 'Id_unidade e visao: como identificar a unidade e escolher a visão da recepção.' --- # Unidades e visões ## `Id_unidade` `Id_unidade` é o código da unidade no sistema da academia — o mesmo que você já usa internamente — e é **obrigatório em toda chamada de dados**. A unidade de Boituva, por exemplo, é `375`. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` Regras do parâmetro: * Aceita letras, números, `_` e `-`, com até 40 caracteres. * Um código que não corresponde a nenhuma unidade cadastrada responde `404 unidade_nao_encontrada`. * Um código de unidade fora da sua conta responde `403 unidade_negada`. * Não existe consulta "todas as unidades": para consolidar a rede, faça uma chamada por unidade. ## Visões Cada unidade pode ter mais de um ponto de captação. A API separa esses pontos em **visões**, escolhidas pelo parâmetro opcional `visao`. | `visao` | O que entrega | Situação | | --- | --- | --- | | `recepcao` (padrão) | O painel do balcão: atendimentos, vendas, renovações, acesso, qualidade, horários e insights. | Disponível. | | `professor` | O painel do tablet dos professores. | Reservada. Responde `404 visao_indisponivel` até o painel existir. | Sem o parâmetro, a chamada é a da recepção. As duas chamadas abaixo são equivalentes: ```text /v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08 /v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08&visao=recepcao ``` Quando a visão do professor for publicada, o mesmo endereço passará a respondê-la, sem mudança na sua integração. Até lá, trate `visao_indisponivel` como "ainda não há dados", não como erro de configuração. ## Erros relacionados | HTTP | `code` | Causa | | --- | --- | --- | | 400 | `id_unidade_obrigatoria` | `Id_unidade` não foi informado. | | 400 | `id_unidade_invalida` | Caractere fora de letras, números, `_` e `-`, ou mais de 40 caracteres. | | 404 | `unidade_nao_encontrada` | Nenhuma unidade com esse código. | | 403 | `unidade_negada` | A chave não acessa essa unidade. | | 400 | `visao_desconhecida` | `visao` diferente de `recepcao` ou `professor`. | | 404 | `visao_indisponivel` | `visao=professor` ainda não tem painel. | --- --- url: https://docs.ouvixpro.ai/guia/periodo.md description: >- Parâmetros de, ate e turno: formato das datas, limite de 31 dias e as faixas de manhã, tarde e noite. --- # Período e turno Os endpoints `/v1/painel`, `/v1/atendimentos/{id}` e `/v1/atendimentos/{id}/audio` exigem o período da consulta. Não há valor padrão: a API não assume "hoje" nem "ontem", para que o resultado seja sempre reproduzível. ## `de` e `ate` Datas no formato `YYYY-MM-DD`, inclusivas nas duas pontas. | Consulta | Parâmetros | | --- | --- | | Um dia | `de=2026-10-08&ate=2026-10-08` | | Uma semana | `de=2026-10-02&ate=2026-10-08` | | Um mês | `de=2026-10-01&ate=2026-10-31` | * O intervalo máximo é de **31 dias**. Para períodos maiores, divida em chamadas mensais. * `de` precisa ser menor ou igual a `ate`. * Em intervalos, os números do `painel` são consolidados e as listas trazem os atendimentos de todos os dias, em ordem de `data_ref` e `horario`. ::: tip Quando consultar Os dados de um dia ficam prontos na madrugada seguinte, depois do processamento das gravações. Consultas ao dia corrente podem voltar incompletas. ::: ## `turno` Parâmetro opcional para recortar o período por faixa de horário. Sem ele, a API devolve o dia inteiro. | `turno` | Faixa | | --- | --- | | `todos` (padrão) | O período inteiro. | | `manha` | 06:00 – 11:59 | | `tarde` | 12:00 – 16:59 | | `noite` | 17:00 – 22:00 | ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08&turno=tarde" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` O filtro vale para todos os blocos do `painel`: contadores, listas e insights refletem só o turno pedido. A resposta repete o turno aplicado no campo `turno`. ## Período em `/v1/atendimentos/{id}` e no áudio O `id` de um atendimento só é resolvido **dentro do `Id_unidade` e do período informados**. Use o mesmo `de` / `ate` (e `turno`) da chamada ao `/v1/painel` que devolveu o atendimento; fora desse recorte a resposta é `404 atendimento_nao_encontrado`. ## Erros relacionados | HTTP | `code` | Causa | | --- | --- | --- | | 400 | `data_obrigatoria` | `de` ou `ate` não informados. | | 400 | `periodo_invalido` | Data inválida, `de` maior que `ate`, ou intervalo acima de 31 dias. | | 400 | `turno_invalido` | Valor fora de `todos`, `manha`, `tarde`, `noite`. | --- --- url: https://docs.ouvixpro.ai/guia/telas.md description: >- Como reproduzir o painel OuvixPRO no seu sistema com /v1/catalogo, /v1/tela e o áudio: kpis, listas de evidência, rótulos, tons e as nove telas bloco a bloco. --- # Montando a tela A API entrega o painel do jeito que a interface OuvixPRO mostra: cada card com texto pronto, cor e a lista de conversas que abre ao clicar. Você não precisa reimplementar regra nenhuma — os blocos de `tela` são calculados pelo mesmo código que desenha o painel. ## Em três chamadas | Chamada | Quando | O que traz | | --- | --- | --- | | `GET /v1/catalogo` | uma vez, ao iniciar | rótulos, cores, metas, catálogo de planos. Não muda por dia. Cache de 1 hora. | | `GET /v1/tela` | a cada período ou turno | as nove telas prontas em `tela`, as listas de evidência em `listas` e os atendimentos referenciados em `atendimentos`. | | `GET /v1/atendimentos/{id}/audio` | quando a pessoa clica em ouvir | o WAV do trecho, já recortado e com dados sensíveis em silêncio. | ```bash curl "https://api.ouvixpro.ai/v1/catalogo" -H "Authorization: Bearer $OUVIX_API_KEY" curl "https://api.ouvixpro.ai/v1/tela?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" # só uma tela, com os atendimentos que ela usa curl "https://api.ouvixpro.ai/v1/tela?Id_unidade=375&de=2026-10-06&ate=2026-10-06&tela=venda" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` `GET /v1/painel` continua entregando tudo: os números brutos **e** `painel.tela`, idêntico ao de `/v1/tela`. Use `/v1/tela` quando só quer desenhar; use `/v1/painel` quando também quer os dados para cruzar. ## Como os blocos se ligam Todo card segue o mesmo caminho: **kpi → lista → atendimento → áudio**. ```text tela.resumo.kpis[3] → { label: "Graves", valor: "0", tone: "ok", lista: "graves" } listas["graves"] → { titulo, hint, ids: ["2026-10-06:atend_12", …], badges, notas } atendimentos[].id → o objeto completo, com rotulos e audio atendimentos[].audio.url → GET /v1/atendimentos/2026-10-06:atend_12/audio ``` ### Um kpi | Campo | Tipo | O que é | | --- | --- | --- | | `chave` | string | Identificador estável do indicador (episodios, nota, graves…). | | `label` | string | Título do card, como no painel. | | `valor` | string | Texto pronto para mostrar: "7.4/10", "9 de 13", "25%", "—". | | `numero` | number / null | O valor bruto, para quem quer calcular ou ordenar. | | `tone` | string | ok, warn, bad ou neutral. Cores em /v1/catalogo → tons. | | `hint` | string / null | Legenda pequena abaixo do número. | | `lista` | string / null | Chave em tela.listas com os atendimentos que o card abre ao clicar. null quando o card não abre nada. | ### Uma lista | Campo | Tipo | O que é | | --- | --- | --- | | `chave` | string | A mesma chave usada em kpis\[].lista, funil\[].lista, barras\[].lista… | | `titulo` | string | Título do painel lateral de evidências. | | `hint` | string | Texto de apoio abaixo do título. | | `ids` | array | ids dos atendimentos, em ordem cronológica. O objeto completo está em painel.atendimentos (ou em atendimentos, no /v1/tela). | | `badges` | object | Por id: label e tone do selo que a tela mostra ao lado da conversa. | | `notas` | object | Por id: texto extra (por exemplo, o insight completo). | Toda referência a atendimento nas telas é um **id** (`"2026-10-06:atend_12"`). Procure em `atendimentos` (ou em `painel.atendimentos`). O `id` é o mesmo em todas as listas e nos itens de insight. ### Tons e cores `tone` aparece em kpis, badges, chips, funis e barras. São quatro valores; a cor de cada um está em `catalogo.tons`: | tone | significado | cor padrão | | --- | --- | --- | | `ok` | dentro da meta ou bom | `#059669` | | `warn` | atenção | `#d97706` | | `bad` | fora da meta ou grave | `#dc2626` | | `neutral` | informativo, sem juízo | `#64748b` | Momentos e tipos de conversa têm cor própria (`catalogo.cores.momento`, `catalogo.cores.tipo`) e já vêm resolvidas em cada `rotulos`. As regras que escolhem o tom estão escritas em `catalogo.regras` (nota: ok ≥ 8, warn ≥ 6; percentual: ok ≥ meta, warn ≥ meta − 20). ### Campos `vazio` Quando um bloco não tem o que mostrar, ele vem com `vazio` preenchido com a frase que a interface exibe ("Nenhuma matrícula confirmada neste recorte."). Quando há conteúdo, `vazio` é `null`. Mostre a frase no lugar do bloco. ## As nove telas A ordem abaixo é a ordem dos blocos na interface. ### Resumo {#resumo} `tela.resumo` — a primeira tela, visão do dono. | Bloco | O que é | | --- | --- | | `kpis` | 4 cards: Episódios, Nota da recepção, Cadastro de novos ("9 de 13"), Graves. | | `fluxo` | Chegaram → Pararam no balcão → Saíram com despedida (`etapas`, com cor), três linhas de meta (`metas`) e a frase de leitura (`insight`, pode ser null). | | `balcao` | Quem parou no balcão: alunos de casa, novos, com cadastro, sem próximo passo — cada contagem com a `lista` que abre. | | `matriculas` | Matrículas confirmadas: `n`, `ids` e `lista`. | | `churn` | Cancelamento e congelamento: `n`, `cancelar`, `congelar`, `ids`. | | `alertas` | "O que pede atenção": itens com `codigo`, `titulo`, `severidade` (alta/media) e `lista`. Quando não há alerta, `semAlerta` traz a frase. | | `dono` | Quatro linhas de decisão: `planoNaoFechou`, `travouEntrada` (facial/catraca/aplicativo), `prometeuDiretoria` (temas), `totalpass` (barreira / explicou a diferença / só passou). | | `insightsEmAberto` | Quantos insights estão abertos e o texto do atalho para a tela Insights. | | `oportunidades` | "Oportunidades na fala": o que o cliente pediu, com `fato`, `insight`, `tom` e `lista`. | | `agregadores` | Dois cards: Gympass e TotalPass. | | `mix` | Onde a recepção falou (`partes` com percentual e cor) e os assuntos mais frequentes (`assuntos`). | | `guia` | O que a recepção fez: linhas do guia de aluno (`aluno`) e de aluno novo (`novo`), cada uma com `valor` pronto ("57% (4/7)"). | | `porHora` | Série por hora com entrada, atendimento, saída. | ### Entrada × Saída {#fluxo} `tela.fluxo` | Bloco | O que é | | --- | --- | | `avisoFormatoAntigo` | Frase de aviso quando o recorte tem análises no formato anterior; null normalmente. | | `kpis` | Entradas, Balcão, Saídas, Saídas por entrada (tom pela proporção: ok ≥ 60%, warn ≥ 30%). | | `colunas` | Três colunas (Entrada, Balcão, Saída), cada uma com `cor`, 3 `kpis` (Episódios, Nota, Guia), um `destaque` com meta (Saudação / Guia de aluno novo / Despedida) e as linhas do `guia`. | | `porHora` | Série por hora por momento. | | `entradasSemSaudacao`, `saidasSemDespedida` | ids das conversas a ouvir, ou `vazio`. | ### Qualidade {#qualidade} `tela.qualidade` | Bloco | O que é | | --- | --- | | `kpis` | 7 cards: Nota média, Nota na entrada, no balcão, na saída, Saudação na entrada, Despedida na saída, Objeções. | | `guias` | Três tabelas do guia (entrada, balcão, saída), com cor do momento. | | `graves` | ids dos graves para ouvir com a equipe. | | `boasPraticas` | ids das conversas com nota 8 ou mais. | ### Acesso {#acesso} `tela.acesso` | Bloco | O que é | | --- | --- | | `kpis` | Entradas liberadas, Travou na porta, Resolveu na hora ("2 de 2"), TotalPass / Gympass. | | `ondeTravou` | Barras Facial / Catraca / Aplicativo, cada uma com `hint` e `lista`. | | `agregador` | Barras Não conseguiu entrar / Recepção mostrou o plano Sky / Só passou. | | `travas` | Cada conversa que travou: `id`, `badge` (Resolveu na hora / Saiu sem resolver) e as `travas` com rótulo. | | `cadastros` | Cadastros novos: `id`, `fotoFacial` e o selo "Foto do facial feita" quando houve. | ### Novos alunos {#comercial} `tela.comercial` | Bloco | O que é | | --- | --- | | `kpis` | Alunos novos atendidos, Com cadastro no balcão, Sem próximo passo, Guia de aluno novo. | | `funil` | Etapas Atendidos → Visita → Cadastro → Com cadastro → Sem próximo passo, a frase `semCadastro` e os `motivos`. | | `guiaNovos` | Linhas do guia de aluno novo. | | `novos` | Cada aluno novo: `id`, `rotulo` (Matrícula · plano, Cadastro no balcão, Saiu sem próximo passo…), `motivo` e o checklist `guia` (item, label, ok). | | `alunosDeCasa` | Alunos de casa no balcão: 3 kpis, ids de risco de churn e de demanda não resolvida. | | `oportunidadesLista` | "Dinheiro deixado na recepção": conversas com oportunidade comercial. | ### Horários {#horarios} `tela.horarios` — séries para o gráfico: `porHoraMomento` (entrada, atendimento, saída por hora), `porHora` (total por hora), `series` com label e cor de cada linha e `unidades` (quando o período cruza mais de uma). ### Protocolo de venda {#venda} `tela.venda` | Bloco | O que é | | --- | --- | | `titulo`, `texto` | Cabeçalho da tela. | | `funil` | Conversas de venda → Apresentou o recorrente → Fechou plano. Cada etapa com `valor`, `base`, `pct`, `hint`, `tone` e `lista`. | | `chips` | Ao lado do funil: "3 não fecharam" e "1 sem desfecho no áudio", com a lista de cada um. | | `passos` | Os 7 passos do protocolo: `feitos`/`total`, `pct`, `meta`, ids em `fez` e `faltou`, e a `lista` que abre com o selo Fez / Deixou passar. | | `planosCitados` | Barras por plano citado, cada uma com lista. | | `objecoes` | Barras por objeção; a lista marca Respondeu / Sem resposta. | | `conversas` | Cada conversa de venda: `quando`, `desfecho` (Fechou · plano / Não fechou / Sem desfecho no áudio), `badges`, `resumo`, `evidencia` (fala literal), `passos` com `fez` por passo e `proximoPasso`. | | `catalogo` | O catálogo de planos da unidade, com o recorrente em destaque. | ### Renovação {#renovacao} `tela.renovacao` — mesma estrutura da venda, aplicada a quem paga o Prime Mensal: `funil` (Alunos do mensal → Ouviram a oferta → Migraram), `passos` do roteiro de renovação, `argumento` (os números do Prime Mensal × Recorrente), `motivos` (por que não migrou) e `conversas` com desfecho Migrou pro recorrente / Ficou no mensal · motivo. ### Insights {#insights} `tela.insights` | Bloco | O que é | | --- | --- | | `kpis` | Risco de perder aluno, Pra fechar, Decisões suas — cada um com a lista. | | `blocos` | Um por tipo (risco, pendencia, decisao) que tiver itens: `label`, `hint`, `tone`, `cor`, `contagem` ("3 conversas"), `repetidos` (o mesmo assunto em várias pessoas, com lista) e `itens` (cada conversa com `id`, `quando`, `quemLabel` "Você decide" / "Recepção liga", `titulo`, `fato`, `aberto`, `acao`). | ## Receitas ### Painel lateral de evidências Ao clicar num kpi, funil, barra ou chip com `lista`, abra um painel com o título e as conversas: ```js const r = await fetch(`${API}/v1/tela?Id_unidade=375&de=2026-10-06&ate=2026-10-06`, { headers }) const { tela, listas, atendimentos } = await r.json() const porId = new Map(atendimentos.map((a) => [a.id, a])) function abrirLista(chave) { const l = listas[chave] return { titulo: l.titulo, hint: l.hint, conversas: l.ids.map((id) => { const a = porId.get(id) return { quando: a.rotulos.quando, momento: a.rotulos.momento, // { label: "Balcão", cor: "#7c3aed" } resumo: a.rotulos.resumo, chips: a.rotulos.chips, // [{ label: "verificado no áudio", tone: "ok", hint }] badge: l.badges[id] ?? null, // { label: "Cadastro no balcão", tone: "ok" } nota: l.notas[id] ?? null, audio: a.audio, // { url, duracao_s, partes } ou null } }), } } const graves = tela.resumo.kpis.find((k) => k.chave === 'graves') if (graves.lista) abrirLista(graves.lista) ``` ### Botão de ouvir ```js async function tocar(a) { if (!a.audio) return const r = await fetch(`${API}${a.audio.url}?Id_unidade=375&de=2026-10-06&ate=2026-10-06`, { headers }) const blob = await r.blob() const el = new Audio(URL.createObjectURL(blob)) el.title = a.rotulos.play // "06/10 · 13:16:41 · Balcão" await el.play() } ``` O WAV já vem só com o trecho da conversa e com documento e nome completo em silêncio. Detalhes em [Áudio](/guia/audio). ### Card de kpi ```js function Card(k, cores) { return `
${k.label} ${k.valor} ${k.hint ? `${k.hint}` : ''}
` } ``` ## O que não vem Nenhuma referência a arquivo, caminho ou identificador interno de gravação. O que a interface mostra como "verificado no áudio" chega como o chip `verificado` em `rotulos.chips`, sem o laudo interno. Nome completo e documento não aparecem em texto nem em áudio. --- --- url: https://docs.ouvixpro.ai/guia/novidades.md description: >- Registro das mudanças na API, da mais recente para a mais antiga: logs e X-Request-Id, tela pronta, áudio por atendimento, desfecho da venda, Id_unidade. --- # Novidades Registro das mudanças na API, da mais recente para a mais antiga. A regra é compatibilidade: campos existentes mantêm nome e significado; mudanças entram como campos novos. Quando algo deixa de ser aceito, está dito explicitamente. ## Outubro de 2026 — logs das chamadas * **Novo cabeçalho `X-Request-Id`** em toda resposta, sucesso ou erro. Guarde-o no seu log. * **Nova tela Logs da API** no OuvixPRO: cada chamada feita com as suas chaves, com status, código do erro, parâmetros, duração, tamanho e IP de origem; filtros por período, status, endpoint e chave; detalhe com a URL e um `curl` para reproduzir. O `X-Request-Id` localiza a linha. Veja [Limites e erros](/guia/erros#rastreando-uma-chamada). * A autenticação passou a rodar antes da validação dos parâmetros: sem chave válida a resposta é sempre `401`, mesmo que falte `de`/`ate`. ## Outubro de 2026 — a tela pronta Para quem quer reproduzir o painel OuvixPRO no próprio sistema sem reescrever regra nenhuma. Tudo é calculado pelo mesmo código que desenha a interface. * **Novo bloco `painel.tela`** em `GET /v1/painel`: as nove telas (`resumo`, `fluxo`, `qualidade`, `acesso`, `comercial`, `horarios`, `venda`, `renovacao`, `insights`) já montadas — cards com texto pronto (`valor`), cor (`tone`), legenda (`hint`) e a `lista` de conversas que abre ao clicar — mais `tela.listas`, com os ids, selos e notas de cada lista de evidência. * **Novo endpoint `GET /v1/tela`**: só as telas, as listas e os atendimentos referenciados. Aceita `tela=venda` (ou qualquer uma das nove) para vir uma por vez, com apenas os atendimentos que ela usa. * **Novo endpoint `GET /v1/catalogo`**: rótulos, cores, metas, catálogo de planos, motivos e regras de tom. Não depende de unidade nem período; cache de 1 hora. * **Novo bloco `rotulos`** em todo atendimento: `quando`, `momento`, `perfil`, `tipo` (com label e cor), `chips` de contexto, tags de `planos` e o desfecho pronto para aluno novo (`novo`), venda (`venda`) e renovação (`renovacao`). * **Correção:** o mesmo atendimento recebia ids diferentes conforme a lista (`atend_6`, `atend_6:2`, `atend_6:3`). Agora é um só id por conversa em todas as listas; o sufixo `:n` só aparece quando duas conversas distintas dividem o mesmo `atendimento_id`. * Novo guia [Montando a tela](/guia/telas). ## Outubro de 2026 — áudio pelo id do atendimento * **Novo endpoint** `GET /v1/atendimentos/{id}/audio`: entrega só o trecho da conversa, igual ao play do painel, sempre em WAV, com documento e nome completo em silêncio. Conversas que atravessam a troca de arquivo vêm coladas em um único áudio. Detalhes em [Áudio](/guia/audio). * **Novo bloco `audio`** em todo atendimento (também nos itens de `insights` e nas listas de `protocolo`): `url`, `duracao_s`, `partes`. `null` quando não há gravação. * **Removidos da resposta** os campos internos de arquivo: `id_upload`, `nome_arquivo`, `inicio_hms`, `fim_hms`, `arquivos`, `pii_mutes`, `id_cliente`. A API não expõe mais referência a arquivos de gravação. * **Descontinuado** `GET /v1/audio` (parâmetros `id_upload`, `inicio_hms`, `fim_hms`). Responde `410 endpoint_removido`. * Nova página [Começando](/guia/comecando) e reorganização desta documentação sob a marca OuvixPRO. ## Outubro de 2026 — desfecho da venda A conta de venda passou a ter três estados em vez de dois. Antes, uma conversa de plano era "fechou" ou "não fechou"; agora o áudio cortado é separado. **Em `painel.protocolo`** | Campo | O que é | | --- | --- | | `fechadas` | Conversas que fecharam um plano (`fechou=true` ou `protocolo.plano_fechado`). | | `abertas` | Saíram sem fechar e isso aparece no áudio (`fechou=false`). | | `semDesfecho` | O áudio corta antes do fim (`fechou=null`). Não conta nem como fechada nem como aberta. | | `vendasN` | Agora é `fechadas + abertas + semDesfecho`. | **Em cada atendimento** | Campo | O que é | | --- | --- | | `desfecho_venda` | Leitura dedicada do desfecho: `eh_venda`, `fechou`, `plano_fechado`, `evidencia` (fala literal que prova) e `proximo_passo`. Presente em toda conversa de plano. | | `fechou` | Passa a seguir a mesma regra em todas as visões: `true` fechou plano, `false` saiu sem fechar, `null` sem desfecho no áudio. | | `protocolo.plano_fechado` | Sempre preenchido quando `fechou=true`; sempre `null` quando `fechou=false`. | | `motivo_nao_fechou` | Dois valores novos: `volta_depois` (volta outro dia para fechar) e `diaria` (pagou só a diária avulsa, R$ 49,90 — não é plano). | | `id` | Agora vem também nos itens de `protocolo.vendas`, `fechadas`, `abertas`, `semDesfecho`, `renovacoes`, `passosVenda[].fez/faltou` e em `insights[].itens[]`. É o mesmo `id` de `painel.atendimentos`. | **Regras que a leitura aplica** * Fechou só com sinal forte na fala (link do contrato, cadastro do cartão, "fechou", liberação do acesso). * Diária avulsa não é plano: `fechou=false`, `motivo_nao_fechou="diaria"`. * Cadastro digital ou ativação de quem já pagou não é venda: `desfecho_venda.eh_venda=false`, fora de `protocolo.vendas`. * Quem entra por Gympass/Wellhub ou TotalPass fica fora de `protocolo.vendas` (`agregador` preenchido). * Ex-aluno que volta e pede plano é venda. **Ordem das listas** Toda lista de atendimentos (`atendimentos`, `novosAlunos`, `protocolo.vendas`, `evidencias`, `insights[].itens`…) vem em ordem de `data_ref` e `horario`, do mais cedo para o mais tarde. Antes, algumas listas vinham com "fechadas primeiro". **Alunos novos** `novosFechados` e `funilNovos.fechados` contam aluno novo **com cadastro** (nome, documento ou ficha). Plano fechado é `protocolo.fechouN`. As duas contas são diferentes de propósito: um visitante pode ter cadastro e ainda não ter plano. **Insights** `painel.insights` é uma lista de grupos: `chave`, `tipo` (`pendencia`, `decisao`, `risco`), `tema`, `assunto`, `acao`, `qtd`, `dias` e `itens[]` (um por conversa, com `id`, `quem`, `titulo`, `fato`, `aberto`, `acao`). O formato antigo (`assunto`, `qtd`, `aproveitou`) não existe mais. ## Outubro de 2026 — Id\_unidade * `Id_unidade` substituiu `unidade` em toda chamada. Boituva é `375`. O parâmetro antigo não é mais aceito. * `visao=professor` reservada; responde `visao_indisponivel` até o painel do tablet existir. --- --- url: https://docs.ouvixpro.ai/visoes/geral.md description: >- Resumo: Pulso da recepção: onde falou, quem parou no balcão, alunos novos e o que pede atenção. Campos, exemplo e a tela pronta em painel.tela.resumo. --- # Resumo Pulso da recepção: onde falou, quem parou no balcão, alunos novos e o que pede atenção. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.resumo` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=resumo`. O guia [Montando a tela](/guia/telas#resumo) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `total` | number | Episódios na recepção no período (entrada + balcão + saída). | | `mediaNota` | number / null | Nota média da recepção, de 0 a 10. | | `graves` | number | Atendimentos marcados como graves. | | `oportunidades` | number | Oportunidades apontadas no período. | | `visitas` | number | Visitas ou tours. | | `churn` | number | Cancelamentos e congelamentos. | | `entradas` | number | Pessoas recebidas na entrada. | | `atendimentosBalcao` | number | Atendimentos parados no balcão. | | `saidas` | number | Despedidas na saída. | | `atendNovos` | number | Alunos novos (visitantes) atendidos no balcão. | | `novosFechados` | number | Alunos novos com cadastro no balcão (nome, documento ou ficha). Plano fechado é outra conta: veja protocolo.fechouN. | | `novosSemProximoPasso` | number | Alunos novos que saíram sem contato, agendamento ou matrícula. | | `alertas` | array | Alertas do período: título, severidade e quantidade. | | `tipos` | array | Mix de tipos de atendimento (check-in, matrícula, renovação…). | | `atendimentos` | array | Todos os atendimentos do período, em ordem de data e horário. Use o campo id em /v1/atendimentos/{id}. | | `evidencias` | array | Atendimentos que pedem atenção (graves, sem próximo passo, demanda em aberto). | | `ranking` | array | Nota e volume por unidade no período. Com uma unidade, a lista tem um item. | | `isV2` | boolean | Verdadeiro quando o período usa o formato atual do painel. Períodos antigos podem trazer menos campos. | | `demandas` | array | Pedidos fora do cardápio de planos, agrupados por tema: tema, chave, qtd, prometeu e exemplos. | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "total": 24, "mediaNota": 7.4, "graves": 0, "oportunidades": 2, "visitas": 0, "churn": 0, "entradas": 4, "atendimentosBalcao": 19, "saidas": 1, "atendNovos": 13, "novosFechados": 9, "novosSemProximoPasso": 3, "alertas": [ { "titulo": "Aluno novo saiu sem próximo passo", "qtd": 3 } ], "tipos": [ { "tipo": "matricula", "label": "Matrícula", "qtd": 6 } ], "atendimentos": [], "evidencias": [], "ranking": [ { "loja": "Boituva", "score": 7.4, "qtd": 24 } ], "isV2": true, "demandas": [] } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/insights.md description: >- Insights: O que ficou em aberto: uma pessoa pra fechar, uma decisão sua, ou um aluno em risco. Campos, exemplo e a tela pronta em painel.tela.insights. --- # Insights O que ficou em aberto: uma pessoa pra fechar, uma decisão sua, ou um aluno em risco. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.insights` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=insights`. O guia [Montando a tela](/guia/telas#insights) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `insights` | array | O que ficou em aberto, agrupado por assunto. Cada grupo traz tipo (pendencia, decisao, risco), ação e os itens com id do atendimento. Campos na tabela "Dentro de insights". | ## Dentro de `insights` | Campo | Tipo | O que é | | --- | --- | --- | | `chave` | string | Identificador do grupo: tipo/tema/assunto. | | `tipo` | string | pendencia (uma pessoa pra fechar), decisao (só o dono resolve) ou risco (aluno que pode parar). | | `tema` | string | Tema curto: avaliacao, aula, plano, lesao, horario… | | `assunto` | string | Assunto legível, por exemplo "Spinning". | | `acao` | string | A ação mais repetida entre os itens do grupo. | | `qtd` | number | Quantas pessoas no grupo. | | `dias` | number | Em quantos dias do período o assunto apareceu. | | `itens` | array | Um item por conversa: id, atendimento\_id, data\_ref, horario, tipo, quem (dono ou recepcao), titulo, fato, aberto, acao. Use id em /v1/atendimentos/{id} para o áudio. | Cada grupo junta o mesmo assunto no período ("Spinning · 2 pessoas"). Para ouvir, pegue `itens[].id` e chame `/v1/atendimentos/{id}/audio`: o trecho vem recortado, com dados pessoais em silêncio. ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "insights": [ { "chave": "pendencia|avaliacao|avaliação física", "tema": "avaliacao", "tipo": "pendencia", "assunto": "Avaliação física", "acao": "Ligar e marcar a avaliação física com dia e hora.", "qtd": 2, "dias": 1, "itens": [ { "id": "2026-10-06:atend_8", "atendimento_id": "atend_8", "data_ref": "2026-10-06", "horario": "07:24:58", "tema": "avaliacao", "tipo": "pendencia", "quem": "recepcao", "titulo": "Tem direito à avaliação e saiu sem data", "fato": "Na fala, a recepção disse que a pessoa tem avaliação a cada três meses.", "aberto": "Saiu sem dia marcado pra avaliação.", "acao": "Ligar e marcar a avaliação física com dia e hora." } ] } ] } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/venda.md description: >- Protocolo: Cada conversa de venda no balcão: objetivo, estrutura, escada de planos e fechamento no recorrente. Campos, exemplo e a tela pronta em painel.tela.venda. --- # Protocolo Cada conversa de venda no balcão: objetivo, estrutura, escada de planos e fechamento no recorrente. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.venda` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=venda`. O guia [Montando a tela](/guia/telas#venda) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `motivosNaoFechou` | array | Por que o aluno novo saiu sem fechar, com quantidade. Valores em "Motivos de não fechar". | | `protocolo` | object | Venda e renovação: funil (conversas → apresentou o recorrente → fechou), listas fechadas / abertas / semDesfecho, passos do protocolo, planos e objeções. Campos na tabela "Dentro de protocolo". | ## Como ler o desfecho Cada conversa de plano com visitante cai em uma, e só uma, destas três listas de `painel.protocolo`: | Lista | Regra | Na tela | | --- | --- | --- | | `fechadas` | `fechou === true` ou `protocolo.plano_fechado` preenchido | "Fechou · Recorrente R$ 129,90" | | `abertas` | `fechou === false` (saiu sem fechar e isso aparece no áudio) | "Não fechou", com `motivo_nao_fechou` | | `semDesfecho` | `fechou === null` (o áudio corta antes do fim) | "Sem desfecho no áudio" | `vendasN = fechadas.length + abertas.length + semDesfecho.length` e `fechouN = fechadas.length`. Regras que o leitor de desfecho aplica, na ordem: * Fechou só com sinal forte na fala: link do contrato, cadastro do cartão, "fechou", liberação do acesso. A frase vem em `desfecho_venda.evidencia`. * Diária avulsa (R$ 49,90) não é plano: `fechou=false`, `motivo_nao_fechou="diaria"`. * Cadastro digital ou ativação de quem já pagou antes não é venda: fica fora de `vendas` (`desfecho_venda.eh_venda=false`). * Quem entra por Gympass/Wellhub ou TotalPass fica fora de `vendas` (`agregador` preenchido). * Áudio cortado sem despedida nem combinado: `fechou=null`. ## Dentro de `protocolo` | Campo | Tipo | O que é | | --- | --- | --- | | `vendasN` | number | Conversas de plano com visitante no período (fechadas + abertas + sem desfecho). | | `recorrenteN` | number | Quantas dessas conversas tiveram o recorrente (R$ 129,90) apresentado. | | `fechouN` | number | Quantas fecharam um plano. Igual a fechadas.length. | | `fechadas` | array | Atendimentos que fecharam plano (fechou=true ou protocolo.plano\_fechado). Cada item tem id. | | `abertas` | array | Atendimentos que saíram sem fechar e isso aparece no áudio (fechou=false). Veja motivo\_nao\_fechou e desfecho\_venda.proximo\_passo. | | `semDesfecho` | array | Atendimentos em que o áudio corta antes do fim (fechou=null). Não contam nem como fechada nem como aberta. | | `vendas` | array | Todas as conversas de plano, em ordem de horário. União de fechadas, abertas e semDesfecho. | | `objetivoPct` | number / null | Percentual das conversas em que a recepção perguntou o objetivo. | | `escadaPct` | number / null | Percentual com a escada de planos na ordem (Prime → Recorrente → Anual → Quadrimestral). | | `recorrentePct` | number / null | Percentual em que o recorrente foi apresentado. | | `registroPct` | number / null | Percentual com nome, contato e origem registrados. | | `fechamentoPct` | number / null | Percentual em que a recepção pediu o fechamento ou fechou. | | `avaliacaoPct` | number / null | Percentual em que a avaliação física foi oferecida. | | `experimentacaoN` | number | Quem não fechou e saiu com visitas de experimentação marcadas. | | `passosVenda` | array | Os 7 passos do protocolo de venda: id, label, meta, feitos, total, pct e as listas fez / faltou (atendimentos com id). | | `planos` | array | Planos fechados no período: plano, label e qtd. | | `objecoes` | array | Objeções ditas por quem não fechou: tipo, label e qtd. | | `renovacoesN` | number | Conversas de renovação (aluno no Prime Mensal que podia ir pro Recorrente). | | `oferecidas` | number | Renovações em que o recorrente foi oferecido. | | `migradas` | number | Renovações que migraram para o recorrente. | | `renovacoes` | array | Conversas de renovação, em ordem de horário, com id. | | `migradasLista` | array | Renovações que migraram, com id. | | `ficaramLista` | array | Renovações que ficaram no plano antigo, com id. | | `passosRenovacao` | array | Passos do protocolo de renovação, no mesmo formato de passosVenda. | | `motivosRenovacao` | array | Por que não migrou: motivo (cartao, pensar, totalpass, outro), label e qtd. | ## Dentro de `desfecho_venda` Vem em cada atendimento de `vendas`, `fechadas`, `abertas` e `semDesfecho`. | Campo | Tipo | O que é | | --- | --- | --- | | `eh_venda` | boolean | Verdadeiro quando é uma conversa de plano com visitante. Falso em cadastro digital, ativação de quem já pagou e check-in de agregador. | | `fechou` | boolean / null | true fechou um plano; false saiu sem fechar; null o áudio corta antes do fim. Só vem preenchido quando eh\_venda=true. | | `plano_fechado` | string / null | Plano fechado: prime, recorrente, anual, quadrimestral, familia ou melhor\_idade. Sempre null quando fechou=false. | | `evidencia` | string | A fala literal que prova o desfecho ("vou mandar o link do contrato", "eu fecho amanhã"). | | `proximo_passo` | string | O que ficou combinado quando não fechou (volta amanhã, WhatsApp, avaliação). | ## Motivos de não fechar Valores possíveis de `motivo_nao_fechou` e de `motivosNaoFechou[].motivo`. | Valor | Rótulo na tela | Quando | | --- | --- | --- | | `volta_depois` | Volta outro dia pra fechar | Disse que volta amanhã ou outro dia para fechar (sem documento, sem cartão, vai trazer alguém). | | `diaria` | Pagou só a diária | Pagou a diária avulsa (R$ 49,90) e não entrou em plano. | | `preco` | Preço | Achou caro ou comparou preço. | | `caro` | Tá caro | Disse explicitamente que está caro. | | `horario` | Horário | O horário da academia ou da aula não serve. | | `vai_pensar` | Vai pensar | Vai pensar, sem data para voltar. | | `vou_pensar` | Disse que ia ver | "Vou ver", sem compromisso. | | `conjuge` | Vou ver com marido/esposa | Depende de outra pessoa. | | `totalpass` | TotalPass | Prefere ou já tem TotalPass. | | `cartao` | Não quer cartão | Não quis deixar o cartão no recorrente. | | `pix` | Quer pagar no Pix | Quer pagar à vista no Pix. | | `so_olhando` | Só olhando | Veio só conhecer. | | `sem_oferta` | Sem oferta da recepção | A recepção não ofereceu plano. | | `outro` | Outro | Qualquer outro motivo. | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "motivosNaoFechou": [ { "motivo": "volta_depois", "label": "Volta outro dia pra fechar", "qtd": 2 }, { "motivo": "diaria", "label": "Pagou só a diária", "qtd": 1 } ], "protocolo": { "vendasN": 10, "recorrenteN": 8, "fechouN": 6, "fechadas": [ { "id": "2026-10-06:atend_35", "horario": "17:40:28", "fechou": true, "protocolo": { "cena": "venda_nova", "plano_fechado": "recorrente" } } ], "abertas": [ { "id": "2026-10-06:atend_27", "horario": "13:16:41", "fechou": false, "motivo_nao_fechou": "volta_depois", "desfecho_venda": { "eh_venda": true, "fechou": false, "plano_fechado": null, "evidencia": "sem documento sem nada nem cartão mas eu fecho amanhã", "proximo_passo": "Volta amanhã para fechar o quadrimestral." } } ], "semDesfecho": [ { "id": "2026-10-06:atend_4", "horario": "06:36:20", "fechou": null, "truncado": true } ], "objetivoPct": 0, "escadaPct": 40, "recorrentePct": 80, "registroPct": 10, "fechamentoPct": 60, "planos": [ { "plano": "recorrente", "label": "Recorrente R$ 129,90", "qtd": 2 }, { "plano": "quadrimestral", "label": "Quadrimestral R$ 99,90", "qtd": 2 } ], "objecoes": [], "renovacoesN": 0, "oferecidas": 0, "migradas": 0, "motivosRenovacao": [] } } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/renovacao.md description: >- Renovação: Prime Mensal R$ 179,90 → Recorrente R$ 129,90: quem voltou pra pagar, quem ouviu a oferta e quem migrou. Campos, exemplo e a tela pronta em painel.tela.renovacao. --- # Renovação Prime Mensal R$ 179,90 → Recorrente R$ 129,90: quem voltou pra pagar, quem ouviu a oferta e quem migrou. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.renovacao` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=renovacao`. O guia [Montando a tela](/guia/telas#renovacao) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `protocolo` | object | Venda e renovação: funil (conversas → apresentou o recorrente → fechou), listas fechadas / abertas / semDesfecho, passos do protocolo, planos e objeções. Campos na tabela "Dentro de protocolo". | ## Dentro de `protocolo` A renovação usa o mesmo objeto `painel.protocolo` da página Protocolo. Os campos de renovação: | Campo | Tipo | O que é | | --- | --- | --- | | `renovacoesN` | number | Conversas de renovação (aluno no Prime Mensal que podia ir pro Recorrente). | | `oferecidas` | number | Renovações em que o recorrente foi oferecido. | | `migradas` | number | Renovações que migraram para o recorrente. | | `renovacoes` | array | Conversas de renovação, em ordem de horário, com id. | | `migradasLista` | array | Renovações que migraram, com id. | | `ficaramLista` | array | Renovações que ficaram no plano antigo, com id. | | `passosRenovacao` | array | Passos do protocolo de renovação, no mesmo formato de passosVenda. | | `motivosRenovacao` | array | Por que não migrou: motivo (cartao, pensar, totalpass, outro), label e qtd. | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "protocolo": { "vendasN": 10, "recorrenteN": 8, "fechouN": 6, "fechadas": [ { "id": "2026-10-06:atend_35", "horario": "17:40:28", "fechou": true, "protocolo": { "cena": "venda_nova", "plano_fechado": "recorrente" } } ], "abertas": [ { "id": "2026-10-06:atend_27", "horario": "13:16:41", "fechou": false, "motivo_nao_fechou": "volta_depois", "desfecho_venda": { "eh_venda": true, "fechou": false, "plano_fechado": null, "evidencia": "sem documento sem nada nem cartão mas eu fecho amanhã", "proximo_passo": "Volta amanhã para fechar o quadrimestral." } } ], "semDesfecho": [ { "id": "2026-10-06:atend_4", "horario": "06:36:20", "fechou": null, "truncado": true } ], "objetivoPct": 0, "escadaPct": 40, "recorrentePct": 80, "registroPct": 10, "fechamentoPct": 60, "planos": [ { "plano": "recorrente", "label": "Recorrente R$ 129,90", "qtd": 2 }, { "plano": "quadrimestral", "label": "Quadrimestral R$ 99,90", "qtd": 2 } ], "objecoes": [], "renovacoesN": 0, "oferecidas": 0, "migradas": 0, "motivosRenovacao": [] } } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/comercial.md description: >- Novos alunos: Cada aluno novo atendido no balcão: guia cumprido, fechou ou saiu sem próximo passo. Alunos de casa, churn e oportunidades. Campos, exemplo e a tela pronta em painel.tela.comercial. --- # Novos alunos Cada aluno novo atendido no balcão: guia cumprido, fechou ou saiu sem próximo passo. Alunos de casa, churn e oportunidades. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.comercial` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=comercial`. O guia [Montando a tela](/guia/telas#comercial) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `atendAlunos` | number | Atendimentos de quem já é aluno. | | `atendNovos` | number | Alunos novos (visitantes) atendidos no balcão. | | `novosFechados` | number | Alunos novos com cadastro no balcão (nome, documento ou ficha). Plano fechado é outra conta: veja protocolo.fechouN. | | `novosSemProximoPasso` | number | Alunos novos que saíram sem contato, agendamento ou matrícula. | | `novosSemOferta` | number | Alunos novos atendidos sem oferta de plano ou experimental. | | `taxaFechamentoNovos` | number / null | Percentual de alunos novos com cadastro. | | `contatoNovosPct` | number / null | Percentual de alunos novos com contato registrado. | | `notaNovos` | number / null | Nota média nos atendimentos de aluno novo. | | `aderenciaNovos` | number / null | Aderência ao guia de aluno novo, em percentual. | | `demandasNaoResolvidas` | number | Atendimentos de aluno em que a demanda ficou em aberto. | | `funilNovos` | object | Funil do aluno novo: atendidos, visitas, cadastros, fechados (com cadastro), sem próximo passo e sem oferta. | | `motivosNaoFechou` | array | Por que o aluno novo saiu sem fechar, com quantidade. Valores em "Motivos de não fechar". | | `novosAlunos` | array | Lista dos alunos novos, em ordem de horário. Cada item é um atendimento, com id para o áudio. | | `guiaNovos` | array | Guia dos alunos novos. | | `oportunidadesLista` | array | Atendimentos com oportunidade na fala. | | `gympass` | array | Atendimentos em que a pessoa entra pelo Gympass ou Wellhub. | | `totalpass` | array | Atendimentos em que a pessoa entra ou compara com TotalPass. | ## Cadastro × plano fechado `novosFechados` conta aluno novo **com cadastro** (nome, documento ou ficha). Plano fechado é `painel.protocolo.fechouN`. Um visitante pode ter cadastro e não ter fechado plano (pagou a diária, volta amanhã), e as duas contas aparecem separadas na tela. `novosSemProximoPasso` conta quem saiu sem contato, agendamento ou matrícula. `motivosNaoFechou` diz por quê. ## Motivos de não fechar | Valor | Rótulo na tela | Quando | | --- | --- | --- | | `volta_depois` | Volta outro dia pra fechar | Disse que volta amanhã ou outro dia para fechar (sem documento, sem cartão, vai trazer alguém). | | `diaria` | Pagou só a diária | Pagou a diária avulsa (R$ 49,90) e não entrou em plano. | | `preco` | Preço | Achou caro ou comparou preço. | | `caro` | Tá caro | Disse explicitamente que está caro. | | `horario` | Horário | O horário da academia ou da aula não serve. | | `vai_pensar` | Vai pensar | Vai pensar, sem data para voltar. | | `vou_pensar` | Disse que ia ver | "Vou ver", sem compromisso. | | `conjuge` | Vou ver com marido/esposa | Depende de outra pessoa. | | `totalpass` | TotalPass | Prefere ou já tem TotalPass. | | `cartao` | Não quer cartão | Não quis deixar o cartão no recorrente. | | `pix` | Quer pagar no Pix | Quer pagar à vista no Pix. | | `so_olhando` | Só olhando | Veio só conhecer. | | `sem_oferta` | Sem oferta da recepção | A recepção não ofereceu plano. | | `outro` | Outro | Qualquer outro motivo. | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "atendAlunos": 4, "atendNovos": 13, "novosFechados": 9, "novosSemProximoPasso": 3, "novosSemOferta": 0, "taxaFechamentoNovos": 69, "contatoNovosPct": 31, "notaNovos": 7.4, "aderenciaNovos": 35, "demandasNaoResolvidas": 0, "funilNovos": { "atendidos": 13, "visitas": 0, "cadastros": 3, "fechados": 9, "sem_proximo_passo": 3, "sem_oferta": 0 }, "motivosNaoFechou": [ { "motivo": "volta_depois", "label": "Volta outro dia pra fechar", "qtd": 2 }, { "motivo": "diaria", "label": "Pagou só a diária", "qtd": 1 } ], "novosAlunos": [], "guiaNovos": [], "oportunidadesLista": [], "gympass": [], "totalpass": [] } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/acesso.md description: >- Acesso: Facial, catraca, aplicativo e agregadores — quem travou na porta e se a recepção resolveu na hora. Campos, exemplo e a tela pronta em painel.tela.acesso. --- # Acesso Facial, catraca, aplicativo e agregadores — quem travou na porta e se a recepção resolveu na hora. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.acesso` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=acesso`. O guia [Montando a tela](/guia/telas#acesso) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `checkins` | number | Check-ins ouvidos. | | `catraca` | number | Conversas de catraca ou acesso. | | `cadastros` | number | Cadastros novos. | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "checkins": 2, "catraca": 3, "cadastros": 3 } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/fluxo.md description: >- Entrada × Saída: Como a recepção recebe quem chega, atende quem para no balcão e se despede de quem sai. Campos, exemplo e a tela pronta em painel.tela.fluxo. --- # Entrada × Saída Como a recepção recebe quem chega, atende quem para no balcão e se despede de quem sai. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.fluxo` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=fluxo`. O guia [Montando a tela](/guia/telas#fluxo) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `entradas` | number | Pessoas recebidas na entrada. | | `atendimentosBalcao` | number | Atendimentos parados no balcão. | | `saidas` | number | Despedidas na saída. | | `indefinidos` | number | Atendimentos sem momento definido. | | `saudacaoEntradaPct` | number / null | Percentual de entradas com saudação. | | `despedidaSaidaPct` | number / null | Percentual de saídas com despedida. | | `aderenciaEntrada` | number / null | Aderência ao guia na entrada, em percentual. | | `aderenciaAtendimento` | number / null | Aderência ao guia no balcão, em percentual. | | `aderenciaSaida` | number / null | Aderência ao guia na saída, em percentual. | | `porHoraMomento` | array | Volume por hora, separado em entrada, balcão, saída e indefinido. | | `guiaEntrada` | array | Guia só das entradas. | | `guiaAtendimento` | array | Guia só do balcão. | | `guiaSaida` | array | Guia só das saídas. | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "entradas": 4, "atendimentosBalcao": 19, "saidas": 1, "indefinidos": 0, "saudacaoEntradaPct": 25, "despedidaSaidaPct": 100, "aderenciaEntrada": 75, "aderenciaAtendimento": 68, "aderenciaSaida": 44, "porHoraMomento": [ { "hora": "18", "entrada": 4, "atendimento": 3, "saida": 2, "indefinido": 0 } ], "guiaEntrada": [], "guiaAtendimento": [], "guiaSaida": [] } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/qualidade.md description: >- Qualidade: Nota por momento, saudação, despedida, graves e boas práticas. Campos, exemplo e a tela pronta em painel.tela.qualidade. --- # Qualidade Nota por momento, saudação, despedida, graves e boas práticas. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.qualidade` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=qualidade`. O guia [Montando a tela](/guia/telas#qualidade) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `mediaNota` | number / null | Nota média da recepção, de 0 a 10. | | `graves` | number | Atendimentos marcados como graves. | | `objecoes` | number | Objeções ouvidas no período. | | `aderenciaGuia` | number / null | Percentual médio de cumprimento do guia da recepção. | | `saudacaoPct` | number / null | Percentual de atendimentos com saudação. | | `notaEntrada` | number / null | Nota média da entrada. | | `notaAtendimento` | number / null | Nota média do balcão. | | `notaSaida` | number / null | Nota média da saída. | | `guia` | array | Itens do guia da recepção, com feitos, total e percentual. | | `evidencias` | array | Atendimentos que pedem atenção (graves, sem próximo passo, demanda em aberto). | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "mediaNota": 7.4, "graves": 0, "objecoes": 0, "aderenciaGuia": 71, "saudacaoPct": 25, "notaEntrada": 8.1, "notaAtendimento": 7.2, "notaSaida": 6.4, "guia": [ { "item": "saudacao", "label": "Saudação", "feitos": 20, "total": 30, "pct": 67 } ], "evidencias": [] } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/horarios.md description: >- Horários: Picos do dia para escala da recepção. Campos, exemplo e a tela pronta em painel.tela.horarios. --- # Horários Picos do dia para escala da recepção. Os números abaixo estão em `painel` na resposta de `GET /v1/painel`. A chamada sempre leva `Id_unidade` e o período. Toda lista de atendimentos vem em ordem de data e horário, do mais cedo para o mais tarde. ```bash curl "https://api.ouvixpro.ai/v1/painel?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ::: tip Quer a tela pronta? Esta mesma visão já vem montada em `painel.tela.horarios` (cards com texto, cor e lista de evidências) e, mais leve, em `GET /v1/tela?tela=horarios`. O guia [Montando a tela](/guia/telas#horarios) mostra bloco a bloco. ::: | Campo | Tipo | O que é | | --- | --- | --- | | `porHora` | array | Volume por hora cheia. | | `porHoraMomento` | array | Volume por hora, separado em entrada, balcão, saída e indefinido. | | `ranking` | array | Nota e volume por unidade no período. Com uma unidade, a lista tem um item. | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "turno": "todos", "painel": { "porHora": [ { "hora": "18", "qtd": 9 } ], "porHoraMomento": [ { "hora": "18", "entrada": 4, "atendimento": 3, "saida": 2, "indefinido": 0 } ], "ranking": [ { "loja": "Boituva", "score": 7.4, "qtd": 24 } ] } } ``` --- --- url: https://docs.ouvixpro.ai/visoes/atendimento.md description: >- O objeto de um atendimento: todos os campos, o bloco audio, os rotulos prontos, desfecho_venda e os motivos de não fechar. --- # Atendimento Um item de `painel.atendimentos`. O `id` vale só junto com o mesmo `Id_unidade` e o mesmo período. O mesmo objeto aparece nas listas de cada visão (`novosAlunos`, `protocolo.vendas`, `evidencias`…), sempre com o mesmo `id`. ```bash curl "https://api.ouvixpro.ai/v1/atendimentos/2026-10-06:atend_27?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` | Campo | Tipo | O que é | | --- | --- | --- | | `id` | string | Identificador estável no período: data:atendimento\_id. Use em /v1/atendimentos/{id}. O mesmo id aparece nas listas de protocolo e nos itens de insights. | | `atendimento_id` | string | Id interno do dia, por exemplo atend\_12. Não é único entre dias; o campo id é. | | `data_ref` | string | Dia do atendimento, YYYY-MM-DD. | | `horario` | string | Horário do início da conversa, HH:MM:SS. | | `momento` | string | entrada, atendimento (balcão), saida ou indefinido. | | `perfil` | string | aluno (já treina), novo (visitante ou aluno novo) ou indefinido. | | `tipo` | string | Tipo da conversa: checkin, matricula, cadastro, renovacao, plano, visita, cancelamento, congelamento e outros. | | `nota` | number / null | Nota de 0 a 10. | | `resumo` | string | O que aconteceu, já sem documento e nome completo. | | `grave` | boolean | Verdadeiro quando o atendimento pede atenção. | | `agregador` | string / null | gympass ou totalpass quando a pessoa entra por agregador. Essas conversas ficam fora da conta de venda. | | `planos` | array | Planos do catálogo citados na conversa: prime, recorrente, anual, quadrimestral, familia, melhor\_idade. | | `protocolo` | object | Passos do protocolo nesta conversa. cena diz o que é a conversa (venda\_nova, renovacao, nenhuma); plano\_fechado diz qual plano fechou. Demais campos são booleanos por passo (objetivo, recorrente, ordem\_ok, registrou\_contato, agendou…). | | `fechou` | boolean / null | Desfecho da conversa de plano. true = fechou um plano; false = saiu sem fechar e isso aparece no áudio; null = o áudio não mostra o fim. Diária avulsa não é plano: fechou=false com motivo diaria. | | `motivo_nao_fechou` | string / null | Por que não fechou, quando fechou=false. Valores em "Motivos de não fechar". | | `desfecho_venda` | object / null | Leitura dedicada do desfecho, com a fala literal que prova. Presente nas conversas de plano. Campos na tabela "Dentro de desfecho\_venda". | | `sem_proximo_passo` | boolean | Aluno novo que saiu sem contato, agendamento ou matrícula. | | `truncado` | boolean | A conversa encosta na borda do bloco de áudio: está incompleta. | | `desfecho_nao_captado` | boolean | O fim da conversa não aparece no áudio (a pessoa foi levada para outro lugar). | | `paralelo` | boolean | Conversa separada de um trecho com mais de um atendimento ao mesmo tempo. | | `guia` | object | Itens do guia da recepção nesta conversa, cada um true/false (saudacao, identificacao, resolveu\_demanda, proximo\_passo…). | | `pedidos` | array | Pedidos fora do cardápio de planos: tema, pedido, resposta, citacao, prometeu\_encaminhar. | | `insights_abertos` | array | O que ficou em aberto nesta conversa: tipo, quem, titulo, fato, aberto, acao. | | `audio` | object / null | Como ouvir esta conversa: url (GET, mesma autenticação e mesmos Id\_unidade/de/ate), duracao\_s e partes. null quando não há trecho de áudio. Campos na tabela "Dentro de audio". | | `rotulos` | object | Textos e cores prontos para mostrar esta conversa como o painel mostra: quando, momento, perfil, tipo, chips, desfecho de aluno novo, venda e renovação. Campos na tabela "Dentro de rotulos". | ## Dentro de `audio` O áudio de um atendimento sai por `GET /v1/atendimentos/{id}/audio`, com os mesmos parâmetros da chamada que devolveu o atendimento. A resposta é sempre um WAV com apenas o trecho da conversa, igual ao play da interface, com documento e nome completo em silêncio. O guia [Áudio](/guia/audio) detalha. ```bash curl -o atendimento.wav \ "https://api.ouvixpro.ai/v1/atendimentos/2026-10-06:atend_27/audio?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` | Campo | Tipo | O que é | | --- | --- | --- | | `url` | string | Caminho relativo à base da API: /v1/atendimentos/{id}/audio. Envie o mesmo Authorization, Id\_unidade, de, ate (e turno, se usou) da chamada que devolveu o atendimento. | | `duracao_s` | number | Duração do áudio entregue, em segundos. | | `partes` | number | Quantos recortes foram colados em sequência (a conversa pode atravessar a troca de arquivo da gravação). A API entrega um único WAV. | ## Dentro de `rotulos` Tudo o que o painel escreve ao lado de uma conversa, já pronto: você não precisa traduzir `momento`, `perfil`, `tipo` ou decidir o texto do desfecho. As cores vêm em hexadecimal e os `tone` seguem a tabela de `/v1/catalogo`. | Campo | Tipo | O que é | | --- | --- | --- | | `quando` | string | Data e hora como aparece nos cards: "06/10 · 13:16:41". | | `momento` | object | id, label e cor do momento: Entrada, Balcão ou Saída. | | `perfil` | object / null | id e label do perfil (Aluno, Novo). null quando indefinido. | | `tipo` | object | id, label e cor do tipo da conversa (Check-in, Cadastro, Plano…). | | `sexo` | string / null | "Mulher", "Homem" ou null. | | `agregador` | object / null | id e label (Gympass, TotalPass) quando a pessoa entra por agregador. | | `resumo` | string | O resumo já no tom do painel (sem jargão interno). | | `chips` | array | Chips de contexto na ordem da tela: chave, label, hint e tone. Inclui "verificado no áudio", "conversa incompleta", "atendimento paralelo", "desfecho não captado", "avaliação parcial". | | `planos` | array | Tags dos planos citados, na ordem do catálogo: id e label. | | `novo` | object / null | Só para aluno novo: label (Matrícula · plano, Cadastro no balcão, Saiu sem próximo passo, Contato garantido…), tone e motivo. | | `venda` | object / null | Só em conversa de venda: label (Fechou · plano, Não fechou, Sem desfecho no áudio), tone, evidencia e proximoPasso. | | `renovacao` | object / null | Só em conversa de renovação: label (Migrou pro recorrente, Ficou no mensal · motivo) e tone. | | `play` | string | Texto do botão de ouvir: "06/10 · 13:16:41 · Balcão". | ## Dentro de `desfecho_venda` | Campo | Tipo | O que é | | --- | --- | --- | | `eh_venda` | boolean | Verdadeiro quando é uma conversa de plano com visitante. Falso em cadastro digital, ativação de quem já pagou e check-in de agregador. | | `fechou` | boolean / null | true fechou um plano; false saiu sem fechar; null o áudio corta antes do fim. Só vem preenchido quando eh\_venda=true. | | `plano_fechado` | string / null | Plano fechado: prime, recorrente, anual, quadrimestral, familia ou melhor\_idade. Sempre null quando fechou=false. | | `evidencia` | string | A fala literal que prova o desfecho ("vou mandar o link do contrato", "eu fecho amanhã"). | | `proximo_passo` | string | O que ficou combinado quando não fechou (volta amanhã, WhatsApp, avaliação). | ## Motivos de não fechar | Valor | Rótulo na tela | Quando | | --- | --- | --- | | `volta_depois` | Volta outro dia pra fechar | Disse que volta amanhã ou outro dia para fechar (sem documento, sem cartão, vai trazer alguém). | | `diaria` | Pagou só a diária | Pagou a diária avulsa (R$ 49,90) e não entrou em plano. | | `preco` | Preço | Achou caro ou comparou preço. | | `caro` | Tá caro | Disse explicitamente que está caro. | | `horario` | Horário | O horário da academia ou da aula não serve. | | `vai_pensar` | Vai pensar | Vai pensar, sem data para voltar. | | `vou_pensar` | Disse que ia ver | "Vou ver", sem compromisso. | | `conjuge` | Vou ver com marido/esposa | Depende de outra pessoa. | | `totalpass` | TotalPass | Prefere ou já tem TotalPass. | | `cartao` | Não quer cartão | Não quis deixar o cartão no recorrente. | | `pix` | Quer pagar no Pix | Quer pagar à vista no Pix. | | `so_olhando` | Só olhando | Veio só conhecer. | | `sem_oferta` | Sem oferta da recepção | A recepção não ofereceu plano. | | `outro` | Outro | Qualquer outro motivo. | ## Exemplo ```json { "Id_unidade": "375", "visao": "recepcao", "de": "2026-10-06", "ate": "2026-10-06", "atendimento": { "id": "2026-10-06:atend_27", "atendimento_id": "atend_27", "data_ref": "2026-10-06", "horario": "13:16:41", "momento": "atendimento", "perfil": "novo", "tipo": "plano", "nota": 7, "resumo": "Visitante interessada no quadrimestral guardou o nome e contato, mas não fechou porque não estava com documento ou cartão. Volta amanhã.", "grave": false, "agregador": null, "planos": [ "prime", "recorrente", "anual", "quadrimestral", "familia" ], "protocolo": { "cena": "venda_nova", "objetivo": false, "recorrente": true, "ordem_ok": true, "registrou_contato": true, "plano_fechado": null }, "fechou": false, "motivo_nao_fechou": "volta_depois", "desfecho_venda": { "eh_venda": true, "fechou": false, "plano_fechado": null, "evidencia": "sem documento sem nada nem cartão mas eu fecho amanhã", "proximo_passo": "Volta amanhã para fechar o quadrimestral." }, "sem_proximo_passo": true, "truncado": false, "audio": { "url": "/v1/atendimentos/2026-10-06:atend_27/audio", "duracao_s": 324, "partes": 1 }, "rotulos": { "quando": "06/10 · 13:16:41", "momento": { "id": "atendimento", "label": "Balcão", "cor": "#7c3aed" }, "perfil": { "id": "novo", "label": "Novo" }, "tipo": { "id": "plano", "label": "Plano", "cor": "#ea580c" }, "sexo": "Mulher", "agregador": null, "resumo": "Visitante interessada no quadrimestral guardou o nome e contato, mas não fechou porque não estava com documento ou cartão. Volta amanhã.", "chips": [], "planos": [ { "id": "prime", "label": "Prime" }, { "id": "recorrente", "label": "Recorrente" }, { "id": "anual", "label": "Anual" }, { "id": "quadrimestral", "label": "Quadrimestral" }, { "id": "familia", "label": "Família" } ], "novo": { "label": "Saiu sem próximo passo", "tone": "bad", "motivo": "Volta outro dia pra fechar" }, "venda": { "label": "Não fechou", "tone": "warn", "evidencia": "sem documento sem nada nem cartão mas eu fecho amanhã", "proximoPasso": "Volta amanhã para fechar o quadrimestral." }, "renovacao": null, "play": "06/10 · 13:16:41 · Balcão" } } } ``` --- --- url: https://docs.ouvixpro.ai/guia/audio.md description: >- Como obter o áudio de um atendimento: GET /v1/atendimentos/{id}/audio, sempre WAV, só o trecho da conversa, com dados pessoais em silêncio. --- # Áudio Cada atendimento pode ser ouvido. `GET /v1/atendimentos/{id}/audio` devolve exatamente o que o botão de play do painel reproduz: só o trecho da conversa, em um único arquivo WAV, com documento e nome completo já em silêncio. A API não expõe arquivos de gravação, nomes de arquivo nem posições internas. O único identificador que você precisa é o `id` do atendimento. ## Como chegar ao áudio Todo atendimento traz um bloco `audio`: ```json { "id": "2026-10-06:atend_27", "horario": "13:16:41", "resumo": "Visitante interessada no quadrimestral…", "audio": { "url": "/v1/atendimentos/2026-10-06:atend_27/audio", "duracao_s": 324, "partes": 1 } } ``` | Campo | O que é | | --- | --- | | `url` | Caminho relativo à base da API. | | `duracao_s` | Duração do áudio entregue, em segundos. | | `partes` | Quantos recortes foram colados em sequência (a conversa pode atravessar a troca de arquivo da gravação). Você sempre recebe um único WAV. | `audio` é `null` quando o atendimento não tem trecho de gravação. ## Chamada Use o mesmo `Authorization`, `Id_unidade`, `de`, `ate` (e `turno`, se usou) da chamada que devolveu o atendimento. ::: code-group ```bash [cURL] curl -o atendimento.wav \ "https://api.ouvixpro.ai/v1/atendimentos/2026-10-06:atend_27/audio?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \ -H "Authorization: Bearer $OUVIX_API_KEY" ``` ```python [Python] import os import urllib.request url = ( "https://api.ouvixpro.ai/v1/atendimentos/2026-10-06:atend_27/audio" "?Id_unidade=375&de=2026-10-06&ate=2026-10-06" ) req = urllib.request.Request(url, headers={"Authorization": f"Bearer {os.environ['OUVIX_API_KEY']}"}) with urllib.request.urlopen(req) as res, open("atendimento.wav", "wb") as f: f.write(res.read()) ``` ```js [Node.js] import { writeFile } from 'node:fs/promises' const base = 'https://api.ouvixpro.ai' const atendimento = { audio: { url: '/v1/atendimentos/2026-10-06:atend_27/audio' } } // vindo do /v1/painel const res = await fetch(`${base}${atendimento.audio.url}?Id_unidade=375&de=2026-10-06&ate=2026-10-06`, { headers: { Authorization: `Bearer ${process.env.OUVIX_API_KEY}` }, }) if (!res.ok) throw new Error(`HTTP ${res.status}`) await writeFile('atendimento.wav', Buffer.from(await res.arrayBuffer())) ``` ::: ## Resposta | Cabeçalho | Valor | | --- | --- | | `Content-Type` | `audio/wav` — PCM 16 bits, pronto para tocar em qualquer player. | | `Content-Disposition` | `inline; filename="atendimento-.wav"` | | `X-Audio-Duracao-S` | Duração em segundos. | | `X-Audio-Partes` | Número de recortes colados. | | `Cache-Control` | `private, max-age=300` | O formato é sempre o mesmo, independentemente de como a unidade grava. A API recorta e converte no servidor. ## Dados pessoais As janelas em que foram ditos documento ou nome completo chegam em silêncio, com a mesma regra do player do painel. Os textos (`resumo`, `evidencia`, `fato`…) já vêm mascarados. Não há nada a tratar do seu lado. ## Desempenho A primeira chamada para um atendimento busca a gravação no armazenamento e pode levar alguns segundos, proporcional ao tamanho do bloco de áudio. Chamadas seguintes para a mesma gravação são rápidas. Para catálogos grandes, baixe sob demanda (quando alguém clicar em ouvir) em vez de pré-carregar o dia inteiro. ## Erros relacionados | HTTP | `code` | Causa | | --- | --- | --- | | 404 | `atendimento_nao_encontrado` | O `id` não está nessa unidade e nesse período (confira `Id_unidade`, `de`, `ate` e `turno`). | | 404 | `audio_indisponivel` | O atendimento não tem trecho de gravação (`audio` é `null`). | | 502 | `audio_indisponivel` | O armazenamento de áudio não respondeu ou o recorte falhou. Tente novamente em instantes. | | 410 | `endpoint_removido` | Chamada ao antigo `/v1/audio`. Use `/v1/atendimentos/{id}/audio`. | --- --- url: https://docs.ouvixpro.ai/guia/erros.md description: >- Formato do erro, X-Request-Id e a tela Logs da API, códigos (400, 401, 404, 410, 429, 500), limite de 60 chamadas por minuto e como tratar cada caso. --- # Limites e erros ## Formato do erro Toda resposta de erro tem status HTTP 4xx ou 5xx e um corpo JSON com o mesmo formato: ```json { "error": { "message": "Informe de e ate no formato YYYY-MM-DD. Para um único dia, use a mesma data nos dois.", "type": "invalid_request_error", "code": "data_obrigatoria" } } ``` | Campo | Uso | | --- | --- | | `code` | Identificador estável. Trate os erros por ele. | | `type` | Família: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`. | | `message` | Texto em português para registrar em log ou exibir a quem opera a integração. Pode mudar entre versões. | ## Rastreando uma chamada Toda resposta — sucesso ou erro — traz o cabeçalho `X-Request-Id`, um identificador único da chamada. Guarde-o no seu log: é o mesmo id que aparece na tela **Logs da API** do OuvixPRO (menu da conta → *Logs da API*, ou a partir de *Chaves de API*). Lá ficam as chamadas feitas com as suas chaves: status, código do erro, parâmetros, duração, tamanho e IP de origem, com filtros por período, status, endpoint e chave. Serve para conferir o que a integração está mandando sem precisar de acesso ao servidor. Chamadas sem chave válida (`401`) não são atribuídas a ninguém e não aparecem para o cliente. ```http HTTP/1.1 400 Bad Request X-Request-Id: be685b9c-2391-42d7-b591-46f8eaf895f3 ``` ## Códigos ### Autenticação e acesso | HTTP | `code` | Causa | | --- | --- | --- | | 401 | `chave_ausente` | Cabeçalho `Authorization: Bearer` não enviado. | | 401 | `chave_invalida` | Chave inexistente, digitada errado ou revogada. | | 403 | `unidade_negada` | A chave não acessa o `Id_unidade` informado. | ### Parâmetros | HTTP | `code` | Causa | | --- | --- | --- | | 400 | `id_unidade_obrigatoria` | `Id_unidade` não informado. | | 400 | `id_unidade_invalida` | Caractere fora de letras, números, `_` e `-`, ou mais de 40 caracteres. | | 400 | `data_obrigatoria` | `de` ou `ate` não informados. | | 400 | `periodo_invalido` | Data inválida, `de` maior que `ate`, ou intervalo acima de 31 dias. | | 400 | `turno_invalido` | Valor fora de `todos`, `manha`, `tarde`, `noite`. | | 400 | `visao_desconhecida` | `visao` diferente de `recepcao` ou `professor`. | | 400 | `tela_desconhecida` | `tela` em `/v1/tela` fora de `resumo`, `fluxo`, `qualidade`, `acesso`, `comercial`, `horarios`, `venda`, `renovacao`, `insights`. | | 405 | `metodo` | Método diferente de `GET`. | ### Recurso não encontrado | HTTP | `code` | Causa | | --- | --- | --- | | 404 | `unidade_nao_encontrada` | Nenhuma unidade com esse `Id_unidade`. | | 404 | `visao_indisponivel` | `visao=professor` ainda não tem painel. | | 404 | `atendimento_nao_encontrado` | O `id` não está nessa unidade e nesse período. | | 404 | `audio_indisponivel` | O atendimento não tem trecho de gravação (`audio` é `null`). | | 404 | `nao_encontrado` | Caminho inexistente. | | 410 | `endpoint_removido` | Endpoint descontinuado (`/v1/audio`). A mensagem indica o substituto. | ### Limite e servidor | HTTP | `code` | Causa | | --- | --- | --- | | 429 | `limite` | Mais de 60 chamadas por minuto com a mesma chave. Aguarde e repita. | | 502 | `audio_indisponivel` | O armazenamento de áudio não respondeu ou o recorte falhou. | | 500 | `servidor` | Falha interna. Repita com *backoff*; se persistir, informe o horário e o `Id_unidade` ao suporte. | ## Limites | Limite | Valor | | --- | --- | | Intervalo por chamada | 31 dias | | Requisições | 60 por minuto, por chave | | Chaves ativas por conta | 20 | | Tamanho de `Id_unidade` | 40 caracteres | ## Recomendações * Trate `code`, não `message`. * Faça cache do `/v1/painel` por período: os dados de um dia fechado não mudam. * Em `429` e `5xx`, repita com espera crescente (por exemplo 1 s, 2 s, 4 s) e um teto de tentativas. * Registre `Id_unidade`, `de`, `ate` e o horário da chamada junto com o erro; é o que o suporte precisa para investigar.