---
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 <chave>` |
| **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.