API pública v1

A forma recomendada de integrar um sistema externo com os dados de uma empresa — leitura autenticada por token de acesso, com escopo e limite de requisição próprios.

Base

https://app.primevisita.com.br/v1

Autenticação

Toda rota exige o header Authorization: Bearer <token>. O token é gerado pela própria empresa em Configurações › API (/configuracoes/api, dentro do painel normal — não é o painel super-admin) — cada token tem um nome, um conjunto de escopos (o que ele pode acessar) e pode ser revogado a qualquer momento por lá. O valor bruto só é mostrado uma única vez, no momento da criação — se for perdido, é preciso criar um token novo (não tem como recuperar o valor de um token já criado, nem pelo próprio painel).

Escopos

Escopo	Libera
doctors:read	GET /v1/doctors e GET /v1/doctors/:id
appointments:read	GET /v1/appointments e GET /v1/appointments/:id

Um token sem o escopo necessário pra rota chamada recebe 403.

Limite de requisições

Cada token tem um limite por minuto e por dia. Por padrão vem do valor definido pra plataforma inteira, mas pode ser sobrescrito por empresa ou até pra uma rota específica (configurado pelo super-admin da plataforma em /painel-admin/api). Toda resposta — inclusive as de erro — inclui estes headers:

• X-RateLimit-Limit-Minute / X-RateLimit-Remaining-Minute
• X-RateLimit-Limit-Day / X-RateLimit-Remaining-Day

Passar do limite devolve 429, com o header Retry-After (segundos até a janela seguinte) quando aplicável.

Rota temporariamente desativada

O super-admin da plataforma pode desligar uma rota específica (manutenção, incidente) sem precisar revogar token nem mexer em escopo — nesse estado, a rota devolve 503 pra qualquer chamada, de qualquer empresa.

Uso e histórico

Toda chamada autenticada (com sucesso ou não) fica registrada. A própria empresa acompanha o uso em /configuracoes/api (requisições recentes, gráfico dos últimos 7 dias, limite atual); o super-admin da plataforma vê o histórico de todas as empresas e controla cada rota — ativar/desativar, limite próprio — em /painel-admin/api.