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

# Get

# Listar Note Especifico

> Acesse detalhes completos de uma nota, incluindo seções estruturadas

## Descrição

Retorna os detalhes completos de uma nota específica, incluindo:

* **Transcrição completa** (quando disponível)
* **Seções estruturadas** (anamnese, exame físico, diagnóstico, etc.)
* **Metadados** e informações do áudio
* **URLs de download** do áudio e transcrição

<Warning>
  As **seções estruturadas** (`note_sections`) estão disponíveis **apenas** neste endpoint. Elas não são retornadas na listagem `GET /notes`
</Warning>

## Parâmetros da Requisição

### Path Parameters

| Parâmetro | Tipo | Obrigatório | Descrição        |
| --------- | ---- | ----------- | ---------------- |
| `id`      | UUID | ✅ Sim       | ID único da nota |

### Headers

| Header      | Obrigatório | Valor            |
| ----------- | ----------- | ---------------- |
| `X-API-KEY` | ✅ Sim       | Sua chave de API |

## Exemplos de Requisição

### cURL

```bash theme={null} theme={null}
curl -H "X-API-KEY: cvn_live_abc123def456..." \
  https://api.connectvets.com/notes/6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3
```

### JavaScript/TypeScript

```javascript theme={null} theme={null}
async function getNoteById(noteId) {
  const response = await fetch(`https://api.connectvets.com/notes/${noteId}`, {
    headers: {
      'X-API-KEY': 'cvn_live_abc123def456...'
    }
  });
  
  if (!response.ok) {
    throw new Error(`Nota não encontrada: ${response.status}`);
  }
  
  return response.json();
}

// Uso
const note = await getNoteById('6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3');
console.log(`Nota: ${note.name}`);
console.log(`Status: ${note.transcription_status}`);
console.log(`Seções: ${note.note_sections.length}`);
```

### Python

```python theme={null} theme={null}
import requests

def get_note_by_id(api_key, note_id):
    url = f"https://api.connectvets.com/notes/{note_id}"
    headers = {"X-API-KEY": api_key}
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 404:
        raise ValueError(f"Nota {note_id} não encontrada")
    
    response.raise_for_status()
    return response.json()

# Uso
api_key = "cvn_live_abc123def456..."
note_id = "6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3"

note = get_note_by_id(api_key, note_id)
print(f"Paciente: {note['name']}")
print(f"Status: {note['transcription_status']}")

if note['note_sections']:
    print("Seções encontradas:")
    for section in note['note_sections']:
        print(f"- {section['title']}: {len(section['content'])} caracteres")
```

### Go

```go theme={null} theme={null}
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func getNoteByID(apiKey, noteID string) (*Note, error) {
    url := fmt.Sprintf("https://api.connectvets.com/notes/%s", noteID)
    
    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        return nil, err
    }
    
    req.Header.Set("X-API-KEY", apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    if resp.StatusCode == 404 {
        return nil, fmt.Errorf("nota %s não encontrada", noteID)
    }
    
    if resp.StatusCode != 200 {
        return nil, fmt.Errorf("erro %d: %s", resp.StatusCode, resp.Status)
    }
    
    var note Note
    err = json.NewDecoder(resp.Body).Decode(&note)
    return &note, err
}

// Uso
note, err := getNoteByID("cvn_live_abc123def456...", "6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Paciente: %s\n", note.Name)
fmt.Printf("Seções: %d\n", len(note.NoteSections))
```

## Resposta de Sucesso (200 OK)

```json theme={null} theme={null}
{
  "id": "6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3",
  "name": "Rex",
  "gender": "male",
  "audio_name": "rex_visit_20240214.wav",
  "audio_url": "https://cdn.connectvets.com/audio/6a4fe1de.wav",
  "transcription_status": "completed",
  "transcription_url": "https://cdn.connectvets.com/transcripts/6a4fe1de.txt",
  "external_id": "CLIENTE_123",
  "metadata": [
    {"key": "procedimento", "value": "vacina"},
    {"key": "veterinario", "value": "Dr. João Silva"},
    {"key": "peso", "value": "12.5kg"}
  ],
  "note_sections": [
    {
      "id": "9b7d8b6a-12e3-45fa-9c1c-7e12f5c4a1b2",
      "title": "Anamnese",
      "label": "anamnesis",
      "content": "Paciente Rex, cão macho de 3 anos, da raça Golden Retriever. Proprietário relata que o animal tem apresentado diminuição do apetite nos últimos 3 dias. Não houve vômitos ou diarréia. Animal ativo, mas menos que o habitual.",
      "order": "1"
    },
    {
      "id": "0c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
      "title": "Exame Físico",
      "label": "physical_exam",
      "content": "Peso: 28kg. Temperatura: 38.8°C. Frequência cardíaca: 90 bpm. Frequência respiratória: 24 mpm. Mucosas rosadas e úmidas. Linfonodos normais. Abdômen sem alterações à palpação.",
      "order": "2"
    },
    {
      "id": "1d1e2f3g-4b5c-6d7e-8f9g-0a1b2c3d4e5f",
      "title": "Diagnóstico",
      "label": "diagnosis",
      "content": "Suspeita de gastrite leve. Possivelmente relacionada à mudança de alimentação recente. Recomendado dieta leve e observação.",
      "order": "3"
    },
    {
      "id": "2e2f3g4h-5c6d-7e8f-9g0h-1b2c3d4e5f6g",
      "title": "Tratamento",
      "label": "treatment",
      "content": "Prescrito omeprazol 20mg, 1 comprimido pela manhã por 7 dias. Dieta com ração gastro intestinal. Retorno em 1 semana ou se piorar dos sintomas.",
      "order": "4"
    }
  ],
  "created_at": "2024-02-14T18:25:43Z",
  "updated_at": "2024-02-14T18:30:23Z"
}
```

## Seções Estruturadas

### Tipos de Seções Comuns

| Label           | Título       | Descrição                          |
| --------------- | ------------ | ---------------------------------- |
| `anamnesis`     | Anamnese     | Histórico e relato do proprietário |
| `physical_exam` | Exame Físico | Avaliação física e sinais vitais   |
| `diagnosis`     | Diagnóstico  | Conclusões e diagnósticos          |
| `treatment`     | Tratamento   | Prescrições e recomendações        |
| `observations`  | Observações  | Notas adicionais                   |
| `follow_up`     | Seguimento   | Instruções de retorno              |

### Estrutura das Seções

| Campo     | Tipo   | Descrição                                |
| --------- | ------ | ---------------------------------------- |
| `id`      | UUID   | Identificador único da seção             |
| `title`   | String | Nome exibido da seção                    |
| `label`   | String | Identificador interno (para programação) |
| `content` | String | Conteúdo transcrito da seção             |
| `order`   | String | Ordem de exibição (1, 2, 3...)           |

## Estados da Nota

### Nota Pendente/Processando

```json theme={null} theme={null}
{
  "id": "7b5fe2ef-63d5-5c3c-b41f-5c4fa8e8d9c4",
  "name": "Luna",
  "transcription_status": "processing",
  "transcription_url": null,
  "note_sections": [],
  "created_at": "2024-02-15T09:15:22Z",
  "updated_at": "2024-02-15T09:16:10Z"
}
```

<Info>
  Quando o status é `pending` ou `processing`, os campos `transcription_url` e `note_sections` estarão vazios ou nulos
</Info>

### Nota com Erro

```json theme={null} theme={null}
{
  "id": "8c6fe3f0-74e6-6d4d-c52f-6d5fa9f9e0d5",
  "name": "Milo",
  "transcription_status": "failed",
  "transcription_url": null,
  "note_sections": [],
  "created_at": "2024-02-16T14:20:15Z",
  "updated_at": "2024-02-16T14:22:30Z"
}
```

## Casos de Uso Práticos

### Exibir Detalhes no Frontend

```javascript theme={null} theme={null}
// Componente React para exibir nota
function NoteDetails({ noteId }) {
  const [note, setNote] = useState(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    async function loadNote() {
      try {
        const noteData = await getNoteById(noteId);
        setNote(noteData);
      } catch (error) {
        console.error('Erro ao carregar nota:', error);
      } finally {
        setLoading(false);
      }
    }
    
    loadNote();
  }, [noteId]);
  
  if (loading) return <div>Carregando...</div>;
  if (!note) return <div>Nota não encontrada</div>;
  
  return (
    <div>
      <h1>{note.name}</h1>
      <p>Status: {note.transcription_status}</p>
      
      {note.note_sections.map(section => (
        <div key={section.id}>
          <h3>{section.title}</h3>
          <p>{section.content}</p>
        </div>
      ))}
    </div>
  );
}
```

### Baixar Transcrição

```javascript theme={null} theme={null}
// Baixar arquivo de transcrição
async function downloadTranscription(note) {
  if (note.transcription_status !== 'completed' || !note.transcription_url) {
    throw new Error('Transcrição não disponível');
  }
  
  const response = await fetch(note.transcription_url);
  const text = await response.text();
  
  // Criar download
  const blob = new Blob([text], { type: 'text/plain' });
  const url = URL.createObjectURL(blob);
  
  const a = document.createElement('a');
  a.href = url;
  a.download = `${note.name}_transcricao.txt`;
  a.click();
  
  URL.revokeObjectURL(url);
}
```

### Buscar Seção Específica

```javascript theme={null} theme={null}
// Encontrar seção por label
function findSection(note, label) {
  return note.note_sections.find(section => section.label === label);
}

// Extrair informações específicas
function extractKeyInfo(note) {
  const anamnesis = findSection(note, 'anamnesis');
  const diagnosis = findSection(note, 'diagnosis');
  const treatment = findSection(note, 'treatment');
  
  return {
    paciente: note.name,
    problema: anamnesis?.content.substring(0, 100) + '...',
    diagnostico: diagnosis?.content || 'Não informado',
    tratamento: treatment?.content || 'Não informado'
  };
}
```

### Gerar Relatório

```javascript theme={null} theme={null}
// Gerar relatório estruturado
function generateReport(note) {
  if (note.transcription_status !== 'completed') {
    return 'Nota ainda não processada';
  }
  
  let report = `RELATÓRIO VETERINÁRIO\n\n`;
  report += `Paciente: ${note.name}\n`;
  report += `Data: ${new Date(note.created_at).toLocaleDateString('pt-BR')}\n`;
  
  // Metadados
  if (note.metadata.length > 0) {
    report += `\nInformações Adicionais:\n`;
    note.metadata.forEach(meta => {
      report += `- ${meta.key}: ${meta.value}\n`;
    });
  }
  
  report += `\n${'='.repeat(50)}\n\n`;
  
  // Seções ordenadas
  const sections = note.note_sections.sort((a, b) => 
    parseInt(a.order) - parseInt(b.order)
  );
  
  sections.forEach(section => {
    report += `${section.title.toUpperCase()}\n`;
    report += `${'-'.repeat(section.title.length)}\n`;
    report += `${section.content}\n\n`;
  });
  
  return report;
}
```

### Sincronização com Sistema Local

```javascript theme={null} theme={null}
// Sincronizar nota com banco local
async function syncNoteToLocal(noteId) {
  try {
    const remoteNote = await getNoteById(noteId);
    
    // Verificar se há atualizações
    const localNote = await getLocalNote(noteId);
    if (localNote && localNote.updated_at >= remoteNote.updated_at) {
      return { updated: false, note: localNote };
    }
    
    // Salvar/atualizar no banco local
    await saveLocalNote(remoteNote);
    
    return { updated: true, note: remoteNote };
  } catch (error) {
    console.error(`Erro ao sincronizar nota ${noteId}:`, error);
    throw error;
  }
}
```

## Tratamento de Erros

### 404 Not Found

```json theme={null} theme={null}
{
  "error": "not_found",
  "message": "Note not found",
  "code": "NOTE_NOT_FOUND"
}
```

**Causas:**

* ID da nota inexistente
* Nota pertence a outro tenant/clínica
* Nota foi deletada

### 401 Unauthorized

```json theme={null} theme={null}
{
  "error": "unauthorized",
  "message": "API key is required",
  "code": "MISSING_API_KEY"
}
```

### Exemplo de Tratamento

```javascript theme={null} theme={null}
async function safeGetNote(noteId) {
  try {
    const response = await fetch(`/notes/${noteId}`, {
      headers: { 'X-API-KEY': apiKey }
    });
    
    if (response.status === 404) {
      return { error: 'Nota não encontrada', note: null };
    }
    
    if (response.status === 401) {
      return { error: 'Acesso negado', note: null };
    }
    
    if (!response.ok) {
      return { error: `Erro ${response.status}`, note: null };
    }
    
    const note = await response.json();
    return { error: null, note };
    
  } catch (error) {
    return { error: error.message, note: null };
  }
}

// Uso com tratamento
const { error, note } = await safeGetNote(noteId);
if (error) {
  console.error(error);
} else {
  console.log('Nota carregada:', note.name);
}
```

## Downloads e Arquivos

### Baixar Áudio Original

```javascript theme={null} theme={null}
async function downloadAudio(note) {
  const response = await fetch(note.audio_url);
  const blob = await response.blob();
  
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = note.audio_name;
  a.click();
  
  URL.revokeObjectURL(url);
}
```

### Verificar Disponibilidade

```javascript theme={null} theme={null}
function checkAvailability(note) {
  return {
    audio: !!note.audio_url,
    transcription: note.transcription_status === 'completed' && !!note.transcription_url,
    sections: note.note_sections.length > 0,
    completed: note.transcription_status === 'completed'
  };
}

const availability = checkAvailability(note);
if (availability.transcription) {
  console.log('Transcrição disponível para download');
}
```

## Performance e Cache

### Cache Inteligente

```javascript theme={null} theme={null}
// Cache com TTL para notas completadas
const noteCache = new Map();

async function getCachedNote(noteId) {
  const cached = noteCache.get(noteId);
  
  // Cache hit para notas completadas (não mudam)
  if (cached && cached.transcription_status === 'completed') {
    return cached;
  }
  
  // Cache hit com TTL para notas em processamento
  if (cached && Date.now() - cached._cached_at < 30000) { // 30s
    return cached;
  }
  
  // Cache miss - buscar nova versão
  const note = await getNoteById(noteId);
  note._cached_at = Date.now();
  noteCache.set(noteId, note);
  
  return note;
}
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Listar Notas" icon="list" href="/notes/api-reference/notes/list">
    Busque e filtre suas notas
  </Card>

  <Card title="Criar Nova Nota" icon="plus" href="/notes/api-reference/notes/create">
    Envie áudio para transcrição
  </Card>

  <Card title="Atualizar Seções" icon="edit" href="/notes/api-reference/notes/update-section">
    Edite conteúdo das seções
  </Card>

  <Card title="Conceitos - Notas" icon="book" href="/notes/concepts/notes">
    Entenda como funcionam as notas
  </Card>
</CardGroup>

## OpenAPI

```yaml GET /notes/{noteId} theme={null}
openapi: 3.0.3
info:
  title: ConnectVets Notes API
  description: API para transcrição e análise de consultas veterinárias
  version: 1.0.0
  contact:
    name: ConnectVets Support
    email: suporte@connectvets.com.br
    url: https://connectvets.com.br
  license:
    name: Proprietary
    url: https://connectvets.com.br/terms
servers:
  - url: https://api-sandbox.connectvets.com.br/notes/v1
    description: Homologação
security:
  - ApiKeyAuth: []
paths:
  /notes/{noteId}:
    get:
      tags:
        - Notes
      summary: Obter nota específica
      description: >
        Recuperar uma nota pelo ID.


        **Rate Limiting**: Este endpoint está sujeito aos limites da sua API Key
        (padrão: 100 req/min, 1000 req/hora).
      operationId: getNote
      parameters:
        - name: noteId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID da nota
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Nota encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/NoteWithSections'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    NoteWithSections:
      allOf:
        - $ref: '#/components/schemas/Note'
        - type: object
          properties:
            note_sections:
              type: array
              items:
                $ref: '#/components/schemas/NoteSection'
              description: Seções estruturadas da nota
    Note:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID único da nota
          example: 6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3
        name:
          type: string
          description: Nome do paciente
          example: Rex
        gender:
          type: string
          enum:
            - male
            - female
            - unidentified
          description: Sexo do paciente
          example: male
        audio_name:
          type: string
          description: Nome do arquivo de áudio
          example: consulta_rex_20240214.wav
        audio_url:
          type: string
          format: uri
          description: URL do arquivo de áudio
          example: https://cdn.connectvets.com/audio/6a4fe1de.wav
        transcription_status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Status da transcrição
          example: completed
        transcription_url:
          type: string
          format: uri
          nullable: true
          description: URL da transcrição
          example: https://cdn.connectvets.com/transcriptions/6a4fe1de.txt
        external_id:
          type: string
          nullable: true
          description: ID externo do seu sistema
          example: CLIENTE_123
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/Metadata'
          description: Metadados adicionais
        created_at:
          type: string
          format: date-time
          description: Data de criação
          example: '2024-02-14T18:25:43Z'
        updated_at:
          type: string
          format: date-time
          description: Data de atualização
          example: '2024-02-14T18:30:23Z'
    NoteSection:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID da seção
          example: abc123-def456-ghi789
        title:
          type: string
          description: Título da seção
          example: Anamnese
        label:
          type: string
          description: Label da seção
          example: anamnese
        content:
          type: string
          description: Conteúdo da seção
          example: Paciente apresenta sintomas de...
        order:
          type: string
          description: Ordem da seção
          example: '1'
    Error:
      type: object
      properties:
        error:
          type: string
          description: Código do erro
          example: bad_request
        message:
          type: string
          description: Mensagem de erro
          example: Invalid audio format
        code:
          type: string
          description: Código específico
          example: INVALID_AUDIO_FORMAT
        details:
          type: object
          description: Detalhes adicionais do erro
    Metadata:
      type: object
      properties:
        key:
          type: string
          description: Chave do metadado
          example: procedimento
        value:
          type: string
          description: Valor do metadado
          example: vacina
  responses:
    Unauthorized:
      description: Não autorizado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: API Key missing or invalid
            code: INVALID_API_KEY
    NotFound:
      description: Recurso não encontrado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Note not found
            code: NOTE_NOT_FOUND
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key para autenticação

```
