> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectvets.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Notes

# Como funcionam as Notas

> Entenda o fluxo de processamento de notas de consulta veterinária

## O que são Notas?

As **Notas** são transcrições estruturadas de consultas veterinárias. Você envia um arquivo de áudio via API e recebe de volta texto organizado em seções úteis como anamnese, diagnóstico e tratamento.

## Fluxo de Processamento

<Steps>
  <Step title="Upload do áudio">
    Envie seu arquivo de áudio via POST para `/v1/notes`
  </Step>

  <Step title="Processamento">
    Nossa IA processa e transcreve o áudio (1-5 minutos)
  </Step>

  <Step title="Estruturação">
    O texto é automaticamente organizado em seções médicas
  </Step>

  <Step title="Disponibilização">
    Os dados ficam disponíveis via GET `/v1/notes/{id}`
  </Step>
</Steps>

## Estados de Processamento

Uma nota pode ter os seguintes status:

<CardGroup cols={2}>
  <Card title="pending" icon="clock" color="#f59e0b">
    **Aguardando processamento**

    Áudio foi recebido e está na fila
  </Card>

  <Card title="processing" icon="gear" color="#3b82f6">
    **Em processamento**

    IA está transcrevendo o áudio
  </Card>

  <Card title="completed" icon="check" color="#10b981">
    **Concluído**

    Transcrição finalizada e seções disponíveis
  </Card>

  <Card title="failed" icon="x" color="#ef4444">
    **Falhou**

    Erro no processamento (verifique qualidade do áudio)
  </Card>
</CardGroup>

## Estrutura de uma Nota

### Dados Básicos

```json theme={null} theme={null}
{
  "id": "6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3",
  "name": "Rex",
  "gender": "male",
  "external_id": "CLIENTE_123",
  "transcription_status": "completed",
  "created_at": "2024-02-14T18:25:43Z"
}
```

| Campo                  | Tipo   | Descrição                              |
| ---------------------- | ------ | -------------------------------------- |
| `id`                   | UUID   | Identificador único da nota            |
| `name`                 | String | Nome do paciente                       |
| `gender`               | String | Sexo: `male`, `female`, `unidentified` |
| `external_id`          | String | ID do seu sistema (opcional)           |
| `transcription_status` | String | Status atual do processamento          |

### Seções Estruturadas

Quando processada, a nota é dividida automaticamente em seções:

```json theme={null} theme={null}
{
  "note_sections": [
    {
      "id": "9b7d8b6a-12e3-45fa-9c1c-7e12f5c4a1b2",
      "title": "Anamnese",
      "label": "anamnesis",
      "content": "Paciente apresenta histórico de...",
      "order": "1"
    },
    {
      "title": "Diagnóstico", 
      "label": "diagnosis",
      "content": "Após exame físico, diagnosticado...",
      "order": "2"
    }
  ]
}
```

### Seções Padrão

<CardGroup cols={2}>
  <Card title="Anamnese" icon="clipboard-list">
    **Histórico do paciente**

    * Sintomas relatados pelo tutor
    * Histórico médico anterior
    * Observações de comportamento
  </Card>

  <Card title="Exame Físico" icon="stethoscope">
    **Avaliação física**

    * Peso, temperatura, sinais vitais
    * Observações do exame clínico
    * Alterações encontradas
  </Card>

  <Card title="Diagnóstico" icon="diagnoses">
    **Conclusões médicas**

    * Diagnóstico principal
    * Diagnósticos diferenciais
    * Suspeitas clínicas
  </Card>

  <Card title="Tratamento" icon="pills">
    **Plano terapêutico**

    * Medicações prescritas
    * Dosagens e frequência
    * Instruções para o tutor
  </Card>
</CardGroup>

## Metadados Personalizados

Você pode incluir informações adicionais ao criar uma nota:

```json theme={null} theme={null}
{
  "metadata": [
    {"key": "procedimento", "value": "vacina"},
    {"key": "peso", "value": "12.5kg"},
    {"key": "idade", "value": "3 anos"},
    {"key": "veterinario", "value": "Dr. Silva"}
  ]
}
```

**Casos de uso para metadados:**

* Identificação do veterinário
* Tipo de procedimento
* Informações do paciente
* Referências do seu sistema

## Requisitos de Áudio

### Formato Recomendado

<Tip>
  Para melhores resultados, use **WAV, 16kHz, mono, 16-bit**
</Tip>

**Especificações ideais:**

* **Formato**: WAV ou FLAC
* **Taxa de amostragem**: 16.000 Hz
* **Canais**: Mono (1 canal)
* **Bit depth**: 16-bit

### Formatos Aceitos

| Formato | Suporte   | Qualidade |
| ------- | --------- | --------- |
| WAV     | ✅ Ideal   | Excelente |
| FLAC    | ✅ Bom     | Boa       |
| MP3     | ⚠️ Aceito | Regular   |
| M4A     | ⚠️ Aceito | Regular   |

### Dicas para Melhor Qualidade

<CardGroup cols={2}>
  <Card title="🔇 Ambiente Silencioso" icon="volume-mute">
    Minimize ruído de fundo durante a gravação
  </Card>

  <Card title="🎤 Distância Adequada" icon="microphone">
    Mantenha 30-50cm de distância do microfone
  </Card>

  <Card title="🗣️ Fala Clara" icon="comment">
    Evite falar muito rápido ou com volume muito baixo
  </Card>

  <Card title="⏱️ Duração" icon="clock">
    Entre 1 minuto e 1 hora de duração
  </Card>
</CardGroup>

## Limitações

<Warning>
  **Limitações importantes:**

  * **Tamanho máximo**: 100MB por arquivo
  * **Duração máxima**: 60 minutos
  * **Idioma**: Português brasileiro (primário)
  * **Qualidade**: Áudio com muito ruído pode falhar
</Warning>

## Monitoramento via Webhook

Ao invés de fazer polling, configure webhooks para receber notificações:

```json theme={null} theme={null}
{
  "event": "note.completed",
  "data": {
    "note_id": "6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3",
    "status": "completed"
  }
}
```

Veja mais em [Conceitos de Webhooks](/notes/concepts/webhooks).

***

<Info>
  **Próximo passo**: Experimente criar sua primeira nota seguindo o [Guia de Início Rápido](/notes/quickstart).
</Info>