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"}]'

const formData = new FormData();
formData.append('audio', audioFile);
formData.append('name', 'Rex');
formData.append('external_id', 'CLIENTE_123');
formData.append('gender', 'male');
formData.append('metadata', JSON.stringify([
  {"key": "procedimento", "value": "vacina"}
]));

const response = await fetch('https://api.connectvets.com.br/notes', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'cvn_live_abc123def456...'
  },
  body: formData
});

const note = await response.json();

import requests

url = "https://api.connectvets.com.br/notes"
headers = {
    "X-API-KEY": "cvn_live_abc123def456..."
}

files = {
    'audio': ('consulta_rex.wav', open('consulta_rex.wav', 'rb'), 'audio/wav')
}

data = {
    'name': 'Rex',
    'external_id': 'CLIENTE_123',
    'gender': 'male',
    'metadata': '[{"key":"procedimento","value":"vacina"}]'
}

response = requests.post(url, headers=headers, files=files, data=data)
note = response.json()

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

Criar Notes

Envie áudio para transcrição e criação de nota veterinária

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"}]'

const formData = new FormData();
formData.append('audio', audioFile);
formData.append('name', 'Rex');
formData.append('external_id', 'CLIENTE_123');
formData.append('gender', 'male');
formData.append('metadata', JSON.stringify([
  {"key": "procedimento", "value": "vacina"}
]));

const response = await fetch('https://api.connectvets.com.br/notes', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'cvn_live_abc123def456...'
  },
  body: formData
});

const note = await response.json();

import requests

url = "https://api.connectvets.com.br/notes"
headers = {
    "X-API-KEY": "cvn_live_abc123def456..."
}

files = {
    'audio': ('consulta_rex.wav', open('consulta_rex.wav', 'rb'), 'audio/wav')
}

data = {
    'name': 'Rex',
    'external_id': 'CLIENTE_123',
    'gender': 'male',
    'metadata': '[{"key":"procedimento","value":"vacina"}]'
}

response = requests.post(url, headers=headers, files=files, data=data)
note = response.json()

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

OpenAPI

POST /notes

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: [email protected]
    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:
    post:
      tags:
        - Notes
      summary: Criar nova nota
      description: >
        Envie áudio para transcrição e criação de nota veterinária.


        **Rate Limiting**: Este endpoint está sujeito aos limites da sua API Key
        (padrão: 100 req/min, 1000 req/hora).
      operationId: createNote
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - audio
                - name
              properties:
                audio:
                  type: string
                  format: binary
                  description: Arquivo de áudio (WAV/FLAC recomendado)
                  example: consulta_rex_20240214.wav
                name:
                  type: string
                  description: Nome do paciente
                  example: Rex
                external_id:
                  type: string
                  description: ID do seu sistema para referência
                  example: CLIENTE_123
                gender:
                  type: string
                  enum:
                    - male
                    - female
                    - unidentified
                  description: Sexo do paciente
                  example: male
                metadata:
                  type: string
                  description: Metadados adicionais em formato JSON
                  example: '[{"key":"procedimento","value":"vacina"}]'
      responses:
        '201':
          description: Nota criada com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    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'
    Metadata:
      type: object
      properties:
        key:
          type: string
          description: Chave do metadado
          example: procedimento
        value:
          type: string
          description: Valor do metadado
          example: vacina
    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
  responses:
    BadRequest:
      description: Requisição inválida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: bad_request
            message: Invalid audio format
            code: INVALID_AUDIO_FORMAT
            details:
              expected: audio/wav
              received: audio/mp3
    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
    UnprocessableEntity:
      description: Entidade não processável
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unprocessable_entity
            message: Audio file is too large
            code: AUDIO_TOO_LARGE
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key para autenticação

Schemas List

Começar

Conceitos

Integração

Exemplos

API Reference

Create

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

OpenAPI

​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

​OpenAPI

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

OpenAPI