Skip to main content

​
Autenticação com API Keys 🔐

O ConnectVets Notes usa API Keys para autenticar todas as requisições. É simples, seguro e permite controle granular de acesso.
Todas as requisições para a API ConnectVets Notes devem incluir uma API Key válida no header X-API-KEY.

​
Como funciona

1

Obtenha uma API Key

Crie uma API Key no dashboard do ConnectVets Notes
2

Inclua no header

Adicione o header X-API-KEY em todas as requisições
3

Faça a requisição

Envie sua requisição - a autenticação é automática

​
Criando uma API Key

​
Pelo Dashboard Web

1

Acesse o Dashboard

Faça login em notes.connectvets.com.br
2

Navegue para API Keys

Vá para Configurações → API Keys no menu lateral
3

Crie uma nova chave

Clique em “Nova API Key” e preencha:
  • Nome: Identifique o uso (ex: “Integração Sistema X”)
  • Tipo: Selecione as permissões necessárias
  • Expiração: Defina quando expira (opcional)
4

Copie a chave

⚠️ Importante: Copie a chave imediatamente - ela só aparece uma vez!

​
Via API (para automação)

curl -X POST "https://api-sandbox.connectvets.com.br/notes/v1/api-keys" \
  -H "X-API-KEY: your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integração Sistema X",
    "permissions": ["notes:read", "notes:write"],
    "expires_at": "2024-12-31T23:59:59Z"
  }'

​
Usando API Keys

Inclua sua API Key no header X-API-KEY de todas as requisições: 
curl -X GET "https://api-sandbox.connectvets.com.br/notes/v1/notes" \
  -H "X-API-KEY: cvn_1234567890abcdef" \
  -H "Content-Type: application/json"

​
Tipos de API Keys

Administrador

Permissões: Todas
  • Criar/deletar API Keys
  • Gerenciar usuários
  • Acesso completo às notas

Editor

Permissões: Leitura e escrita
  • Criar notas
  • Atualizar notas existentes
  • Visualizar todas as notas

Visualizador

Permissões: Somente leitura
  • Visualizar notas
  • Buscar e filtrar
  • Sem permissões de escrita

​
Anatomia de uma API Key

As API Keys do ConnectVets seguem um formato específico para facilitar identificação: 
cvn_1234567890abcdef1234567890abcdef
│   │                                
│   └── Chave secreta (32 caracteres hex)
└── Prefixo identificador ConnectVets Notes
  • Prefixo: cvn_ identifica chaves do ConnectVets Notes
  • Comprimento: 36 caracteres total (4 do prefixo + 32 da chave)
  • Formato: Hexadecimal (0-9, a-f)
  • Geração: Cryptographically secure random
  • Encoding: UTF-8

​
Segurança e Boas Práticas

✅ Faça

  • Armazene em variáveis de ambiente
  • Use HTTPS em produção
  • Monitore uso das chaves
  • Rotacione chaves regularmente
  • Use chaves com permissões mínimas

❌ Não faça

  • Commitar chaves no código
  • Logar chaves em arquivos
  • Compartilhar chaves por email/chat
  • Usar chaves de admin para tudo
  • Deixar chaves sem expiração

​
Armazenamento Seguro

# .env
CONNECTVETS_API_KEY=cvn_1234567890abcdef

# .bashrc ou .zshrc
export CONNECTVETS_API_KEY=cvn_1234567890abcdef

​
Rate Limiting

API Keys têm limites de taxa baseados no tipo:

Administrador

1000 req/min Limite mais alto para operações administrativas

Editor

500 req/min Limite moderado para operações normais

Visualizador

200 req/min Limite conservador para consultas

​
Respondendo ao Rate Limiting

Quando você excede o limite, a API retorna 429 Too Many Requests: 
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "details": {
      "limit": 500,
      "remaining": 0,
      "reset_at": "2024-01-15T10:31:00Z"
    }
  }
}

​
Monitoramento e Logs

​
Verificar uso de uma API Key

curl -X GET "https://api-sandbox.connectvets.com.br/notes/v1/api-keys/cvn_1234567890abcdef/usage" \
  -H "X-API-KEY: your_admin_key"

​
Listar todas as API Keys

curl -X GET "https://api-sandbox.connectvets.com.br/notes/v1/api-keys" \
  -H "X-API-KEY: your_admin_key"

​
Rotação de Chaves

Para manter a segurança, rotacione suas API Keys regularmente:
1

Crie uma nova API Key

Gere uma nova chave com as mesmas permissões
2

Atualize seus sistemas

Substitua a chave antiga pela nova em todos os sistemas
3

Teste a integração

Verifique se tudo funciona com a nova chave
4

Revogue a chave antiga

Delete a chave antiga do dashboard
Cuidado: Sempre teste a nova chave antes de revogar a antiga para evitar interrupções no serviço.

​
Resolução de Problemas

Possíveis causas:
  • API Key inválida ou expirada
  • Header X-API-KEY ausente
  • Typo na chave
Soluções:
  • Verifique se a chave está correta
  • Confirme que o header está sendo enviado
  • Regenere a chave se necessário
Possíveis causas:
  • API Key sem permissões suficientes
  • Tentativa de acessar recursos de outro tenant
  • Chave desabilitada
Soluções:
  • Use uma chave com permissões adequadas
  • Verifique se está acessando o tenant correto
  • Confirme se a chave está ativa
Possíveis causas:
  • Limite de rate excedido
  • Muitas requisições simultâneas
Soluções:
  • Implemente retry com backoff
  • Distribua requisições ao longo do tempo
  • Use cache para reduzir chamadas

​
Próximos passos

Fazer primeira requisição

Use sua API Key para processar o primeiro áudio

Explorar endpoints

Veja todos os endpoints disponíveis

Configurar webhooks

Receba notificações automáticas de eventos

Exemplos de integração

Veja implementações práticas