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

# Overview

# Visão Geral da API

> Documentação completa da API REST do ConnectVets Notes

## Base URL

### Produção

```
https://api.connectvets.com.br/notes/v1
```

### Homologação

```
https://api-sandbox.connectvets.com.br/notes/v1
```

<Info>
  **Frontend da aplicação**:

  * Produção: [https://notes.connectvets.com.br](https://notes.connectvets.com.br)
  * Homologação: [https://notes-sandbox.connectvets.com.br](https://notes-sandbox.connectvets.com.br)
</Info>

## Autenticação

Para todas as requisições utilize o header:

```http theme={null} theme={null}
X-API-KEY: <SUA_API_KEY>
```

<Warning>
  Sua API Key é secreta! Nunca a compartilhe em código público ou logs.
</Warning>

## Obtendo sua API Key

Para obter acesso à API:

1. **Contate nossa equipe** via [Discord ConnectVets](https://discord.gg/uN4NxUGk)
2. **Forneça informações** sobre seu projeto e casos de uso
3. **Receba suas credenciais** com instruções de configuração
4. **Comece a integrar** seguindo nossa documentação

<Info>
  Cada API Key possui limites específicos de uso. Entre em contato para discutir suas necessidades.
</Info>

## Convenções de Campos

* **UUIDs** são strings no formato RFC 4122
* **Datas** utilizam ISO 8601 em UTC (`YYYY-MM-DDThh:mm:ssZ`)
* **Status** são strings em lowercase com underscore

## Rate Limiting

A API implementa rate limiting baseado na API Key para a maioria dos endpoints:

### Endpoints com Rate Limiting

Os seguintes endpoints possuem limitações (padrão: **100 req/min**, **1000 req/hora**):

* `POST /notes` - Criação de notas
* `GET /notes` - Listagem de notas
* `GET /notes/{id}` - Detalhes da nota

### Endpoints SEM Rate Limiting

* `GET /notes/{id}/status` - **Sem limitação**, mas recomendamos intervalo de 5s entre chamadas

### Headers de Rate Limiting

Quando aplicável, os headers de resposta incluem informações sobre os limites:

```http theme={null} theme={null}
X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 87
X-RateLimit-Reset-Minute: 1642694400
```

## Formato de Resposta

### Sucesso

Todas as respostas de sucesso seguem um formato JSON consistente:

```json theme={null} theme={null}
{
  "data": {}, // ou array para listas
  "meta": {} // informações adicionais como paginação
}
```

### Erro

Respostas de erro incluem informações detalhadas:

```json theme={null} theme={null}
{
  "error": "bad_request",
  "message": "Invalid audio format",
  "code": "INVALID_AUDIO_FORMAT",
  "details": {
    "expected": "audio/wav",
    "received": "audio/mp3"
  }
}
```

## Códigos de Status HTTP

| Código | Significado           | Descrição                              |
| ------ | --------------------- | -------------------------------------- |
| `200`  | OK                    | Requisição bem-sucedida                |
| `201`  | Created               | Recurso criado com sucesso             |
| `400`  | Bad Request           | Dados inválidos na requisição          |
| `401`  | Unauthorized          | API Key ausente ou inválida            |
| `403`  | Forbidden             | Permissões insuficientes               |
| `404`  | Not Found             | Recurso não encontrado                 |
| `413`  | Payload Too Large     | Arquivo muito grande                   |
| `422`  | Unprocessable Entity  | Dados válidos mas processamento falhou |
| `429`  | Too Many Requests     | Rate limit excedido                    |
| `500`  | Internal Server Error | Erro interno do servidor               |

## Endpoints Disponíveis

A API ConnectVets Notes oferece endpoints para gerenciar **notas de consultas veterinárias**:

### Notes

| Endpoint                | Método | Descrição                               | Rate Limiting     |
| ----------------------- | ------ | --------------------------------------- | ----------------- |
| `/notes`                | POST   | Criar nova nota com upload de áudio     | ✅ 100/min, 1000/h |
| `/notes`                | GET    | Listar notas com filtros                | ✅ 100/min, 1000/h |
| `/notes/{id}`           | GET    | Obter detalhes de uma nota específica   | ✅ 100/min, 1000/h |
| `/notes/{id}/status`    | GET    | Obter status de transcrição de uma nota | ❌ Sem limitação\* |
| `/notes/{id}/export`    | GET    | Exportar nota em formatos RTF/TXT       | ✅ 100/min, 1000/h |
| `/notes/{noteId}/retry` | POST   | Reprocessar nota falhada                | ✅ 100/min, 1000/h |
| `/note_sections`        | PATCH  | Atualizar seção específica de uma nota  | ✅ 100/min, 1000/h |

### Transcripts

| Endpoint             | Método | Descrição                       | Rate Limiting     |
| -------------------- | ------ | ------------------------------- | ----------------- |
| `/transcripts/retry` | POST   | Reprocessar uma nota que falhou | ✅ 100/min, 1000/h |

<small>\* Recomendamos intervalo de 5s entre chamadas</small>

## Tipos de Dados

### Note

```json theme={null} theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Rex",
  "gender": "male",
  "transcription_status": "completed",
  "external_id": "CLIENTE_123",
  "metadata": [{"key": "veterinario", "value": "Dr. Silva"}],
  "created_at": "2024-02-14T18:25:43Z",
  "updated_at": "2024-02-14T18:30:23Z"
}
```

### NoteSection

```json theme={null} theme={null}
{
  "id": "9b7d8b6a-12e3-45fa-9c1c-7e12f5c4a1b2",
  "title": "Anamnese",
  "label": "anamnesis",
  "content": "Paciente apresenta histórico de...",
  "order": "1"
}
```

### StatusResult

```json theme={null} theme={null}
{
  "status": "completed",
  "valid": true
}
```

### MetadataItem

```json theme={null} theme={null}
{
  "key": "veterinario",
  "value": "Dr. Silva"
}
```

## Paginação

Endpoints que retornam listas implementam paginação:

### Parâmetros de Query

* `page`: Número da página (padrão: 1)
* `limit`: Itens por página (padrão: 10, máximo: 100)

### Resposta

```json theme={null} theme={null}
{
  "data": [...],
  "meta": {
    "total": 200,
    "page": 1,
    "limit": 10,
    "total_pages": 20
  }
}
```

## Filtros para Notes

O endpoint `/notes` suporta diversos filtros via query parameters:

* `transcription_status`: Filtrar por status (`pending`, `processing`, `completed`, `failed`)
* `name`: Busca parcial por nome do paciente
* `from` / `to`: Filtrar por data (YYYY-MM-DD)
* `days`: Últimos X dias
* `external_id`: Filtrar por ID externo

### Exemplos

```bash theme={null} theme={null}
# Notas processadas
GET /notes?transcription_status=completed

# Notas de um período
GET /notes?from=2024-01-01&to=2024-01-31

# Notas de um paciente
GET /notes?name=Rex

# Últimos 7 dias
GET /notes?days=7

# Combinando filtros
GET /notes?transcription_status=completed&days=30&limit=50
```

<Info>
  **Dica**: Para verificar apenas o status de uma nota específica sem buscar todos os dados, use o endpoint [`/notes/{noteId}/status`](/notes/api-reference/notes/status) - sem rate limiting para polling eficiente.
</Info>

### Boas Práticas para Rate Limiting

1. **Use `/notes/{id}/status` para polling**: Sem limitações, ideal para verificações frequentes
2. **Implemente backoff exponencial**: Para retries em caso de erro 429
3. **Cache resultados quando possível**: Evite chamadas desnecessárias
4. **Monitore headers de rate limit**: Para ajustar a frequência das requisições

## Upload de Arquivos

O endpoint `POST /notes` aceita upload de arquivos de áudio usando `multipart/form-data`:

```bash theme={null} theme={null}
curl -X POST "https://api-sandbox.connectvets.com.br/notes/v1/notes" \
  -H "X-API-KEY: sua_api_key_aqui" \
  -F "audio=@caminho/para/audio.mp3" \
  -F "metadata={\"patient_name\":\"Rex\",\"owner_name\":\"João Silva\"}"
```

## Tratamento de Erros

### Rate Limit Exceeded (429)

Quando o rate limit é excedido, você receberá:

```json theme={null} theme={null}
{
  "error": "too_many_requests",
  "message": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Importante**: O endpoint `/notes/{id}/status` não possui esta limitação.

### Retry com Backoff

Para erros temporários (429, 500), implemente retry com backoff exponencial:

```javascript theme={null} theme={null}
async function apiCall(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 30;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      if (response.ok) return await response.json();
      
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}
```

***

<Info>
  **Próximo passo**: Explore os endpoints de Notes na seção [API Endpoints](/notes/api-reference/notes/create) ou veja [exemplos práticos](/notes/examples/basic-integration).
</Info>