Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mivicall.com/llms.txt

Use this file to discover all available pages before exploring further.

A API Mivicall usa Bearer authentication com API keys. 
Authorization: Bearer miv_live_AbC123def456...

​
Tipos de keys

PrefixoAmbienteUso
miv_test_...Sandbox (em construção)Desenvolvimento, dados fake
miv_live_...ProduçãoDados reais da clínica

​
Gerar API key

Dashboard → Settings → Integrações → API keys → Generate new key:
  1. Dá um label descritivo (ex: “PMS Newsoft”, “n8n automation”)
  2. (Opcional) Restringir scopes — recomendamos princípio do menor privilégio
  3. Click “Create”
  4. Copia a key imediatamente — só é mostrada uma vez
A key é guardada em hash irreversível na nossa DB. Se a perderem, têm de revogar e gerar nova.

​
Scopes disponíveis

Por defeito uma key tem full access. Recomendado restringir:
ScopePermite
appointments:readListar e ler marcações
appointments:writeCriar/editar/cancelar
calls:readListar chamadas e transcripts
calls:read.recordingsAceder a recordings R2
patients:readListar pacientes (PII redacted)
patients:read.fullIncluir telefone descifrado
professionals:readListar médicos
services:readListar tipos de consulta
webhooks:manageCRUD nos próprios webhooks
tenant:readLer config do tenant
tenant:writeEditar config (cuidado)
Exemplos práticos:
  • PMS simples (read-only): appointments:read calls:read
  • PMS bi-direccional: appointments:read appointments:write professionals:read services:read
  • Backup tool: appointments:read calls:read calls:read.recordings

​
Rotação

Recomendamos rotação a cada 6 meses ou imediatamente após:
  • Saída de colaborador com acesso
  • Suspeita de leak
  • Mudança de vendor
Processo:
  1. Gerar nova key com mesmos scopes
  2. Actualizar config no vosso sistema
  3. Aguardar 24h (período de overlap onde ambas funcionam)
  4. Revogar a antiga

​
Revogar

Dashboard → API keys → Revoke. Efeito instantâneo, sem grace period. Após revogação, qualquer chamada com essa key recebe 401 Unauthorized.

​
Limites por key

LimiteDefaultPlano
Requests por minuto300Todos
Requests por segundo (burst)30Todos
Webhooks endpoints5Basic
Webhooks endpoints25Pro+
Ver Rate limits para detalhes.

​
Auditoria

Cada chamada com API key é gravada no audit log: 
{
  "actorType": "integration",
  "actorId": "key_AbC123...",  // hash dos primeiros 8 chars
  "action": "appointment.updated",
  "resourceId": "uuid-...",
  "actorIp": "x.x.x.x",
  "createdAt": "..."
}
Visualizável em Settings → Auditoria. Retenção 6 anos (RGPD Art. 30).

​
Segurança

  • HTTPS obrigatório — Authorization em HTTP plain é rejeitado
  • Server-side only — nunca embeber em código cliente (browser, mobile app público)
  • TLS 1.2+ — TLS 1.0/1.1 recusados
  • IP allowlist (em roadmap) — restringir keys a IPs específicos