---
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. |