​
Base URL

​
Produção

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

​
Homologação

https://api-sandbox.connectvets.com.br/notes/v1
Frontend da aplicação:

​
Autenticação

Para todas as requisições utilize o header: 
X-API-KEY: <SUA_API_KEY>
Sua API Key é secreta! Nunca a compartilhe em código público ou logs.

​
Obtendo sua API Key

Para obter acesso à API:
  1. Contate nossa equipe via Discord ConnectVets
  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
Cada API Key possui limites específicos de uso. Entre em contato para discutir suas necessidades.

​
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: 
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: 
{
  "data": {}, // ou array para listas
  "meta": {} // informações adicionais como paginação
}

​
Erro

Respostas de erro incluem informações detalhadas: 
{
  "error": "bad_request",
  "message": "Invalid audio format",
  "code": "INVALID_AUDIO_FORMAT",
  "details": {
    "expected": "audio/wav",
    "received": "audio/mp3"
  }
}

​
Códigos de Status HTTP

CódigoSignificadoDescrição
200OKRequisição bem-sucedida
201CreatedRecurso criado com sucesso
400Bad RequestDados inválidos na requisição
401UnauthorizedAPI Key ausente ou inválida
403ForbiddenPermissões insuficientes
404Not FoundRecurso não encontrado
413Payload Too LargeArquivo muito grande
422Unprocessable EntityDados válidos mas processamento falhou
429Too Many RequestsRate limit excedido
500Internal Server ErrorErro interno do servidor

​
Endpoints Disponíveis

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

​
Notes

EndpointMétodoDescriçãoRate Limiting
/notesPOSTCriar nova nota com upload de áudio✅ 100/min, 1000/h
/notesGETListar notas com filtros✅ 100/min, 1000/h
/notes/{id}GETObter detalhes de uma nota específica✅ 100/min, 1000/h
/notes/{id}/statusGETObter status de transcrição de uma nota❌ Sem limitação*
/notes/{id}/exportGETExportar nota em formatos RTF/TXT✅ 100/min, 1000/h
/notes/{noteId}/retryPOSTReprocessar nota falhada✅ 100/min, 1000/h
/note_sectionsPATCHAtualizar seção específica de uma nota✅ 100/min, 1000/h

​
Transcripts

EndpointMétodoDescriçãoRate Limiting
/transcripts/retryPOSTReprocessar uma nota que falhou✅ 100/min, 1000/h

​
Tipos de Dados

​
Note

{
  "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

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

​
StatusResult

{
  "status": "completed",
  "valid": true
}

​
MetadataItem

{
  "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

{
  "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

# 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
Dica: Para verificar apenas o status de uma nota específica sem buscar todos os dados, use o endpoint /notes/{noteId}/status - sem rate limiting para polling eficiente.

​
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: 
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á: 
{
  "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: 
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));
    }
  }
}
Próximo passo: Explore os endpoints de Notes na seção API Endpoints ou veja exemplos práticos.