Skip to main content

Visão Geral da API

Documentação completa da API REST do ConnectVets Notes

Base URL

Produção

Homologação

Frontend da aplicação:

Autenticação

Para todas as requisições utilize o header:
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:

Formato de Resposta

Sucesso

Todas as respostas de sucesso seguem um formato JSON consistente:

Erro

Respostas de erro incluem informações detalhadas:

Códigos de Status HTTP

Endpoints Disponíveis

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

Notes

Transcripts

Tipos de Dados

Note

NoteSection

StatusResult

MetadataItem

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

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

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:

Tratamento de Erros

Rate Limit Exceeded (429)

Quando o rate limit é excedido, você receberá:
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:

Próximo passo: Explore os endpoints de Notes na seção API Endpoints ou veja exemplos práticos.