ConnectVets Notes - API para Transcrição de Consultas Veterinárias

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:

Taxa de amostragem 16 kHz (16.000 Hz)
Mono (1 canal)
PCM linear sem compressão — se precisar compactar, utilize FLAC (lossless)

Formato recomendado: “WAV – 16 kHz – 16-bit – mono”

Formatos Aceitos

Formato	Status	Qualidade	Observações
WAV	✅ Recomendado	Excelente	PCM linear 16-bit, 16kHz, mono
FLAC	✅ Recomendado	Excelente	Compressão sem perda
MP3	⚠️ Aceito	Boa	Formato amplamente compatível
OGG	⚠️ Aceito	Boa	Compressão eficiente
M4A	⚠️ Aceito	Boa	Formato Apple/AAC
WebM	⚠️ Aceito	Boa	Formato web moderno

Parâmetros da Requisição

Headers

Header	Obrigatório	Valor
`X-API-KEY`	✅ Sim	Sua chave de API
`Content-Type`	✅ Sim	`multipart/form-data`

Body (multipart/form-data)

Campo	Tipo	Obrigatório	Descrição
`audio`	File	✅ Sim	Arquivo de áudio (WAV/FLAC recomendado)
`name`	String	✅ Sim	Nome do paciente
`external_id`	String	❌ Não	ID do seu sistema para referência
`gender`	Enum	❌ Não	Sexo: `male`, `female`, `unidentified` (padrão)
`metadata`	String (JSON)	❌ Não	Metadados 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:

Status	Descrição	Tempo Estimado
`pending`	Aguardando processamento	Imediato
`processing`	IA transcrevendo o áudio	2-5 minutos
`completed`	Transcrição finalizada	-
`failed`	Erro 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

Limite	Valor	Observação
Tamanho máximo	100 MB	Por arquivo
Duração máxima	2 horas	Áudio muito longo pode falhar
Formato	WAV, FLAC, MP3, OGG, M4A, WebM	WAV/FLAC recomendados
Taxa de upload	10 por minuto	Por API Key

Limites por Plano

Plano	Notas/mês	Tamanho	Retenção
Gratuito	10	50 MB	30 dias
Profissional	500	100 MB	1 ano
Enterprise	Ilimitado	200 MB	Customizá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

audio

file

required

Arquivo de áudio (WAV/FLAC recomendado)

name

string

required

Nome do paciente

Example:

"Rex"

external_id

string

ID do seu sistema para referência

Example:

"CLIENTE_123"

gender

enum<string>

Sexo do paciente

Available options:

male,

female,

unidentified

Example:

"male"

metadata

string

Metadados adicionais em formato JSON

Example:

"[{\"key\":\"procedimento\",\"value\":\"vacina\"}]"

Response

Nota criada com sucesso

string<uuid>

ID único da nota

Example:

"6a4fe1de-52c4-4b2b-a30f-4b3fa9d7d8b3"

name

string

Nome do paciente

Example:

"Rex"

gender

enum<string>

Sexo do paciente

Available options:

male,

female,

unidentified

Example:

"male"

audio_name

string

Nome do arquivo de áudio

Example:

"consulta_rex_20240214.wav"

audio_url

string<uri>

URL do arquivo de áudio

Example:

"https://cdn.connectvets.com/audio/6a4fe1de.wav"

transcription_status

enum<string>

Status da transcrição

Available options:

pending,

processing,

completed,

failed

Example:

"completed"

transcription_url

string<uri> | null

URL da transcrição

Example:

"https://cdn.connectvets.com/transcriptions/6a4fe1de.txt"

external_id

string | null

ID externo do seu sistema

Example:

"CLIENTE_123"

metadata

object[]

Metadados adicionais

Show child attributes

created_at

string<date-time>

Data de criação

Example:

"2024-02-14T18:25:43Z"

updated_at

string<date-time>

Data de atualização

Example:

"2024-02-14T18:30:23Z"

API Endpoints

Notes

Criar Notes

Descrição

Requisitos de Áudio

Formatos Aceitos

Parâmetros da Requisição

Headers

Body (multipart/form-data)

Exemplo de Metadados

Status da Transcrição

Erros Comuns

400 Bad Request

401 Unauthorized

402 Payment Required

413 Payload Too Large

422 Unprocessable Entity

Monitoramento do Processamento

Webhook (Recomendado)

Polling

Limites e Restrições

Limites de Upload

Limites por Plano

Melhores Práticas

🎙️ Qualidade do Áudio

🔧 Integração

📊 Metadados Úteis

Próximos Passos

Listar Notas

Obter Nota por ID

Configurar Webhooks

Filtros Avançados

Authorizations

Body

Response

API Endpoints

Notes

​Descrição

​Requisitos de Áudio

​Formatos Aceitos

​Parâmetros da Requisição

​Headers

​Body (multipart/form-data)

​Exemplo de Metadados

​Status da Transcrição

​Erros Comuns

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​413 Payload Too Large

​422 Unprocessable Entity

​Monitoramento do Processamento

​Webhook (Recomendado)

​Polling

​Limites e Restrições

​Limites de Upload

​Limites por Plano

​Melhores Práticas

​🎙️ Qualidade do Áudio

​🔧 Integração

​📊 Metadados Úteis

​Próximos Passos

Listar Notas

Obter Nota por ID

Configurar Webhooks

Filtros Avançados

Authorizations

Body

Response

Descrição

Requisitos de Áudio

Formatos Aceitos

Parâmetros da Requisição

Headers

Body (multipart/form-data)

Exemplo de Metadados

Status da Transcrição

Erros Comuns

400 Bad Request

401 Unauthorized

402 Payment Required

413 Payload Too Large

422 Unprocessable Entity

Monitoramento do Processamento

Webhook (Recomendado)

Polling

Limites e Restrições

Limites de Upload

Limites por Plano

Melhores Práticas

🎙️ Qualidade do Áudio

🔧 Integração

📊 Metadados Úteis

Próximos Passos