# API pública e webhooks da ByDoctor

A ByDoctor tem uma API REST pública para conectar a agenda da clínica a outros sistemas — ERPs, CRMs, BI interno, apps próprios. Ela foi pensada para o time técnico da clínica ou para parceiros que constroem uma integração sob demanda, sem depender de exportações manuais. A versão atual (v1) lista e consulta agendamentos com filtros, incluindo sincronização incremental por `updated_since`, para saber o que mudou desde a última chamada sem reprocessar tudo. Para reagir a mudanças no momento em que elas acontecem, webhooks assinados notificam criação, atualização e cancelamento de agendamentos. A escrita — criar, reagendar, confirmar ou cancelar uma consulta presencial, e cadastrar o paciente que ainda não existe — é concedida por chave, com as mesmas regras do aplicativo. A autenticação é feita por chave de API, gerada dentro do próprio produto e exibida uma única vez no momento da criação.

URL canônica: https://bydoctor.com.br/desenvolvedores
Última atualização: 18 de setembro de 2026
Documentação técnica completa: https://docs.bydoctor.com.br

## Resumo técnico

| Item | Valor |
|---|---|
| Base URL | https://api.bydoctor.com.br/api/public/v1 |
| Autenticação | Chave de API (Authorization: Bearer bd_live_...) |
| Formato | JSON, UTF-8, horários em America/Sao_Paulo (-03:00) |
| Limites | 60 req/min e 10.000 req/dia por chave |
| Webhooks | appointment.created, appointment.updated, appointment.cancelled |
| Escopos | Somente leitura (appointments:read, patients:read) ou acesso total (+ appointments:write, patients:write), por chave |
| Assinatura | Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature) |

## O que dá para fazer

Com uma única chave de API, uma integração típica cobre estes cenários:

- Listar e filtrar agendamentos por período, profissional, status e paciente
- Sincronizar de forma incremental com o parâmetro `updated_since`, sem precisar reprocessar tudo a cada chamada
- Receber eventos em tempo real por webhook assim que um agendamento é criado, atualizado ou cancelado
- Criar, reagendar, confirmar e cancelar agendamentos presenciais com o escopo opcional `appointments:write`, seguindo as mesmas regras do aplicativo
- Encontrar pacientes por CPF ou telefone e cadastrar os novos, para agendar sem duplicar cadastros — CPF, e-mail e data de nascimento são gravados, mas nunca devolvidos pela API

## Perguntas frequentes

### O ByDoctor tem API?
Sim. A ByDoctor tem uma API REST pública para agendamentos e cadastro de pacientes, e um sistema de webhooks em tempo real, pensados para clínicas que querem integrar a agenda a sistemas próprios ou de terceiros.

### A API permite criar ou alterar agendamentos?
Sim. Com o escopo `appointments:write`, concedido por chave, a API cria, reagenda, confirma e cancela agendamentos presenciais, com as mesmas regras do aplicativo (bloqueios de agenda, salas, prontuário já preenchido). Toda chave nasce somente leitura; a escrita é opcional e explícita. O profissional, o tipo de atendimento e a sala são escolhidos por id, a partir de listas somente leitura da própria API. Teleconsultas e solicitações de pacientes continuam sendo tratadas no aplicativo.

### A API permite cadastrar pacientes?
Sim. Com o escopo `patients:write`, a API cadastra e altera pacientes, e com `patients:read` encontra um paciente pelo CPF ou telefone antes de criar o agendamento. Por minimização de dados (LGPD), CPF, e-mail e data de nascimento são aceitos na escrita, mas nunca devolvidos: a resposta traz só nome, telefone e o id usado para agendar. Chaves criadas antes dos pacientes não recebem esse acesso; é preciso criar uma chave nova.

### Como faço para obter uma chave de API?
Dentro do produto, em Minha clínica → API e Webhooks. A chave (Authorization: Bearer bd_live_...) é exibida uma única vez no momento da criação — copie e guarde-a com segurança.

### Os webhooks são assinados?
Sim. Cada entrega segue o padrão Standard Webhooks, com os cabeçalhos webhook-id, webhook-timestamp e webhook-signature, permitindo validar a autenticidade e a integridade do payload antes de processá-lo.

## Documentação completa

Esta página é um resumo. Endpoints, parâmetros de filtro, exemplos de requisição, esquema completo dos payloads de webhook e o passo a passo de configuração ficam na referência técnica, em https://docs.bydoctor.com.br — atualizada a cada mudança na API.

## Links

- Site: https://bydoctor.com.br
- Documentação da API: https://docs.bydoctor.com.br
- Contato: suporte@bydoctor.com.br

URL canônica: https://bydoctor.com.br/desenvolvedores