POST
/
notes
curl -X POST https://api.connectvets.com.br/notes \
  -H "X-API-KEY: cvn_live_abc123def456..." \
  -F "audio=@consulta_rex_20240214.wav" \
  -F "name=Rex" \
  -F "external_id=CLIENTE_123" \
  -F "gender=male" \
  -F 'metadata=[{"key":"procedimento","value":"vacina"}]'

{
  "id": "6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3",
  "name": "Rex",
  "gender": "male",
  "audio_name": "consulta_rex_20240214.wav",
  "audio_url": "https://cdn.connectvets.com.br/audio/6a4fe1de.wav",
  "transcription_status": "pending",
  "transcription_url": null,
  "external_id": "CLIENTE_123",
  "metadata": [
    {"key": "procedimento", "value": "vacina"}
  ],
  "note_sections": [],
  "created_at": "2024-02-14T18:25:43Z",
  "updated_at": "2024-02-14T18:25:43Z"
}

​
Descrição

Envia um arquivo de áudio para transcrição automática e criação de uma nova nota veterinária. O áudio será processado por IA e dividido em seções estruturadas.

​
Requisitos de Áudio

Regras de ouro para obter a melhor performance e acurácia:
  1. Taxa de amostragem 16 kHz (16.000 Hz)
  2. Mono (1 canal)
  3. PCM linear sem compressão — se precisar compactar, utilize FLAC (lossless)
Formato recomendado: “WAV – 16 kHz – 16-bit – mono”

​
Formatos Aceitos

FormatoStatusQualidadeObservações
WAV✅ RecomendadoExcelentePCM linear 16-bit, 16kHz, mono
FLAC✅ RecomendadoExcelenteCompressão sem perda
MP3⚠️ AceitoBoaFormato amplamente compatível
OGG⚠️ AceitoBoaCompressão eficiente
M4A⚠️ AceitoBoaFormato Apple/AAC
WebM⚠️ AceitoBoaFormato web moderno

​
Parâmetros da Requisição

​
Headers

HeaderObrigatórioValor
X-API-KEY✅ SimSua chave de API
Content-Type✅ Simmultipart/form-data

​
Body (multipart/form-data)

CampoTipoObrigatórioDescrição
audioFile✅ SimArquivo de áudio (WAV/FLAC recomendado)
nameString✅ SimNome do paciente
external_idString❌ NãoID do seu sistema para referência
genderEnum❌ NãoSexo: male, female, unidentified (padrão)
metadataString (JSON)❌ NãoMetadados adicionais em formato JSON

​
Exemplo de Metadados

[
  {"key": "procedimento", "value": "vacina"},
  {"key": "peso", "value": "12.5kg"},
  {"key": "idade", "value": "3 anos"},
  {"key": "veterinario", "value": "Dr. João Silva"}
]

curl -X POST https://api.connectvets.com.br/notes \
  -H "X-API-KEY: cvn_live_abc123def456..." \
  -F "audio=@consulta_rex_20240214.wav" \
  -F "name=Rex" \
  -F "external_id=CLIENTE_123" \
  -F "gender=male" \
  -F 'metadata=[{"key":"procedimento","value":"vacina"}]'

{
  "id": "6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3",
  "name": "Rex",
  "gender": "male",
  "audio_name": "consulta_rex_20240214.wav",
  "audio_url": "https://cdn.connectvets.com.br/audio/6a4fe1de.wav",
  "transcription_status": "pending",
  "transcription_url": null,
  "external_id": "CLIENTE_123",
  "metadata": [
    {"key": "procedimento", "value": "vacina"}
  ],
  "note_sections": [],
  "created_at": "2024-02-14T18:25:43Z",
  "updated_at": "2024-02-14T18:25:43Z"
}

​
Status da Transcrição

A nota é criada imediatamente com status pending. O processamento acontece de forma assíncrona:
StatusDescriçãoTempo Estimado
pendingAguardando processamentoImediato
processingIA transcrevendo o áudio2-5 minutos
completedTranscrição finalizada-
failedErro no processamento-

​
Erros Comuns

​
400 Bad Request

{
  "error": "bad_request",
  "message": "Audio file is required",
  "code": "MISSING_AUDIO_FILE"
}
Causas possíveis:
  • Arquivo de áudio não enviado
  • Nome do paciente não informado
  • Formato de metadata inválido

​
401 Unauthorized

{
  "error": "unauthorized",
  "message": "API key is required",
  "code": "MISSING_API_KEY"
}

​
402 Payment Required

{
  "error": "payment_required",
  "message": "Subscription inactive or limit exceeded",
  "code": "SUBSCRIPTION_INACTIVE"
}

​
413 Payload Too Large

{
  "error": "payload_too_large",
  "message": "Audio file exceeds maximum size of 100MB",
  "code": "FILE_TOO_LARGE"
}

​
422 Unprocessable Entity

{
  "error": "unprocessable_entity",
  "message": "Invalid audio format",
  "code": "INVALID_AUDIO_FORMAT",
  "details": {
    "expected": "audio/wav, audio/flac",
    "received": "audio/mp3"
  }
}

​
Monitoramento do Processamento

​
Webhook (Recomendado)

Configure webhooks para receber notificações automáticas: 
{
  "event": "note.completed",
  "data": {
    "id": "6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3",
    "name": "Rex",
    "transcription_status": "completed",
    "external_id": "CLIENTE_123"
  },
  "timestamp": "2024-02-14T18:30:23Z"
}

​
Polling

Consulte periodicamente o status da nota: 
async function waitForCompletion(noteId) {
  let status = 'pending';
  
  while (status === 'pending' || status === 'processing') {
    await new Promise(resolve => setTimeout(resolve, 30000)); // 30s
    
    const response = await fetch(`/notes/${noteId}`, {
      headers: { 'X-API-KEY': apiKey }
    });
    
    const note = await response.json();
    status = note.transcription_status;
    
    if (status === 'completed') {
      console.log('Transcrição finalizada!');
      console.log('Seções:', note.note_sections.length);
      break;
    } else if (status === 'failed') {
      console.error('Erro no processamento');
      break;
    }
  }
}

​
Limites e Restrições

​
Limites de Upload

LimiteValorObservação
Tamanho máximo100 MBPor arquivo
Duração máxima2 horasÁudio muito longo pode falhar
FormatoWAV, FLAC, MP3, OGG, M4A, WebMWAV/FLAC recomendados
Taxa de upload10 por minutoPor API Key

​
Limites por Plano

PlanoNotas/mêsTamanhoRetenção
Gratuito1050 MB30 dias
Profissional500100 MB1 ano
EnterpriseIlimitado200 MBCustomizável

​
Melhores Práticas

​
🎙️ Qualidade do Áudio

  • Ambiente silencioso: Minimize ruído de fundo
  • Distância adequada: 30-50cm do microfone
  • Volume consistente: Evite variações extremas
  • Fala clara: Pronuncie bem as palavras técnicas

​
🔧 Integração

  • Use external_id: Para vincular com seu sistema
  • Configure webhooks: Para notificações em tempo real
  • Trate erros: Implemente retry com backoff exponencial
  • Monitore limites: Acompanhe uso da API

​
📊 Metadados Úteis

[
  {"key": "procedimento", "value": "consulta de rotina"},
  {"key": "veterinario", "value": "Dr. João Silva"},
  {"key": "peso", "value": "12.5kg"},
  {"key": "temperatura", "value": "38.5°C"},
  {"key": "pressao", "value": "normal"},
  {"key": "observacoes", "value": "animal cooperativo"}
]

​
Próximos Passos

Listar Notas

Como buscar e filtrar suas notas

Obter Nota por ID

Acesse detalhes e seções da nota

Configurar Webhooks

Receba notificações automáticas

Filtros Avançados

Exemplos de busca e filtros

Authorizations

​
X-API-KEY
string
header
required

API Key para autenticação

Body

multipart/form-data

Response

201
application/json

Nota criada com sucesso

The response is of type object.