Como Integrar a Agenda da Clínica via API REST
Construir um portal ou app próprio de atendimento exige uma fonte de dados da agenda clínica que seja confiável e atual. Scraping e exportação manual de planilha quebram com qualquer mudança de layout e ficam desatualizados no minuto seguinte. A arquitetura que sustenta esse cenário é uma API dedicada, de preferência com webhook, capaz de entregar dado estruturado e avisar quando algo muda, sem que o sistema consumidor precise ficar perguntando o tempo todo.
O problema real de quem integra agenda clínica não é só ler uma lista de horários. É reagir no momento certo a qualquer mudança, para disparar confirmação, lembrete de preparo, link de telemedicina ou fluxo de triagem sem atraso. Este guia cobre os fundamentos técnicos dessa integração, os critérios para avaliar uma API no mercado brasileiro de software para saúde e os erros de implementação mais comuns.
O que uma API de agendamento clínico precisa entregar?
Uma API adequada para alimentar um sistema próprio de atendimento cobre, no mínimo, três frentes.
Leitura com filtro granular. A API precisa permitir consulta por intervalo de data, status (confirmado, cancelado, remarcado, pendente) e profissional. Sem esses filtros, o sistema consumidor processa volume desnecessário de dado só para extrair o que interessa ao fluxo de atendimento.
Notificação push, não só polling. Polling (consultar a API em intervalo fixo para detectar mudança) consome recurso do servidor e introduz atraso variável entre o evento e a reação do sistema. Uma API madura oferece webhook: notificação enviada de forma ativa para o endpoint do sistema consumidor no instante em que o evento acontece. Isso importa especialmente num contexto clínico, onde um cancelamento de última hora precisa disparar comunicação com o paciente na mesma hora.
Autenticação e documentação técnica de verdade. Chave de API é o padrão esperado numa integração B2B. A documentação precisa cobrir todo endpoint, parâmetro, formato de resposta, comportamento de paginação e o tratamento de caso-limite, como um agendamento que não aparece numa consulta filtrada.
Por que a diferença entre polling e webhook importa para o atendimento ao paciente?
Com polling, o sistema de atendimento só descobre que uma consulta foi cancelada na próxima vez que consulta a API. Isso pode significar minutos ou horas de atraso, dependendo do intervalo configurado. Com webhook, o sistema externo é avisado assim que o evento é registrado na plataforma de origem.
Essa diferença de arquitetura permite que o fluxo seja acionado pelo evento, não por uma checagem programada:
- Cancelamento: aviso imediato ao paciente e liberação do horário no portal próprio.
- Confirmação: disparo automático de link de telemedicina ou instrução de preparo.
- Remarcação: atualização do lembrete já agendado, sem mandar duas mensagens conflitantes ao mesmo paciente.
- Cobrança ou pré-cadastro: início do fluxo financeiro vinculado ao evento de agendamento.
Um erro que aparece com frequência: tratar a ausência de um agendamento no retorno da API como se fosse exclusão. Um agendamento fora da janela de data consultada ou fora do filtro de status usado simplesmente não aparece na lista; ele continua existindo. Confundir os dois casos é o que gera as inconsistências mais graves de sincronização, do tipo que só aparece quando um paciente reclama de ter recebido um lembrete errado.
O que a API do ByDoctor oferece hoje?
A API REST pública do ByDoctor foi lançada em agosto de 2026 para clínicas e fornecedores de software que precisam de acesso programático à agenda clínica. A documentação técnica completa fica em docs.bydoctor.com.br, e a chave de API é gerada pelo próprio administrador da clínica em Minha Clínica → API e Webhooks.
Leitura, sem escrita: por desenho. A API expõe dois endpoints: GET /appointments, para listagem com filtro, e GET /appointments/{id}, para consulta de um agendamento específico por UUID. Não existe POST, PATCH nem DELETE. O ByDoctor trata isso como garantia, não como limitação temporária: quem você conecta lê a agenda, nunca cria, altera ou apaga um agendamento dentro do sistema.
Webhooks com entrega garantida ao menos uma vez. O evento é enviado para o endpoint HTTPS cadastrado assim que um agendamento é criado, atualizado ou cancelado (appointment.created, appointment.updated, appointment.cancelled). A entrega segue o modelo "ao menos uma vez", com reenvio automático quando o endpoint receptor está fora do ar; a documentação não garante ordem entre eventos, então o sistema consumidor deve estar preparado para receber uma notificação de atualização antes da de criação, por exemplo.
Sincronização com updated_since. A consulta a GET /appointments aceita o parâmetro updated_since, em formato ISO 8601, para retornar só o que mudou desde a última verificação. Agendamento cancelado continua na resposta com status: "cancelled" em vez de desaparecer. É o mesmo princípio de "ausência não é exclusão" descrito na seção anterior, agora como comportamento documentado.
| Parâmetro | Tipo | Função |
|---|---|---|
start_date / end_date | data | janela de consulta, limite de 92 dias por requisição |
status | texto | filtra por etapa do agendamento (inclui cancelled) |
professional_id / room_id | número | filtra por profissional ou sala |
updated_since | data e hora (ISO 8601) | retorna só o que mudou desde o valor informado |
cursor / page_size | texto / número | paginação; até 100 registros por página |
O limite de uso é de 60 requisições por minuto e 10.000 por dia por chave. Para o roteiro completo de autenticação e o exemplo de payload de cada evento de webhook, a página de lançamento da API e dos webhooks traz o passo a passo de configuração, e a página para desenvolvedores é o ponto de partida para gerar a chave.
Quais critérios usar para comparar APIs de agendamento no mercado brasileiro?
O mercado brasileiro de software para saúde ganhou maturidade técnica nos últimos anos. Ao decidir qual API usar para alimentar um sistema próprio, cinco critérios ajudam a comparar:
Escopo: leitura, ou leitura e escrita. Algumas APIs só permitem consultar a agenda existente. Outras aceitam criar, cancelar e remarcar consulta programaticamente. A Amplimed, por exemplo, descreve em seu blog uma API de Agendamento que busca horário disponível, cadastra, cancela e altera status de consulta, além de recuperar link de teleatendimento, ou seja, escopo de escrita completo. A API do ByDoctor, na versão pública atual, cobre leitura e notificação via webhook, sem escrita. A escolha certa depende do caso de uso: se o sistema só precisa exibir a agenda e reagir a mudança, leitura mais webhook basta; se ele precisa criar ou cancelar consulta de forma autônoma, escopo de escrita é obrigatório, e vale confirmar isso na documentação antes de começar a integração.
Modelo de notificação. Webhook nativo ou só polling? Para fluxo sensível a tempo, webhook é a escolha certa. Vale também checar o que a documentação diz sobre reenvio em caso de falha de entrega. A comparação entre webhook e polling é um bom ponto de partida para quem ainda está decidindo qual modelo faz sentido para o próprio produto.
Suporte a multi-profissional e multi-unidade. Clínica com vários profissionais ou unidades precisa de uma API que exponha essas dimensões como filtro. Sem isso, o sistema consumidor faz múltiplas chamadas sem garantia de consistência entre elas.
Documentação técnica de verdade. Documentação pública, completa e atualizada é sinal concreto de maturidade. Ela precisa cobrir autenticação, todo endpoint disponível, parâmetro de filtro, formato de resposta, comportamento de paginação, caso-limite de sincronização e exemplo de payload de webhook.
Controle de acesso por clínica. A chave de API deve estar vinculada à clínica, não só ao usuário que a criou, o que garante acesso administrado pela clínica e revogável de forma independente, sem depender de quem gerou a chave originalmente ainda estar na equipe.
Erros comuns ao integrar agendas clínicas
Mesmo com API bem documentada, erro de implementação compromete a sincronização. Os mais frequentes:
- Tratar ausência como exclusão. Um agendamento fora da janela de data ou do filtro de status configurado pode simplesmente não aparecer. Isso não significa que foi excluído. Sistema que interpreta ausência como exclusão remove agendamento ativo do próprio estado local, e isso chega ao paciente como comunicação errada.
- Não mapear todos os status possíveis. Uma agenda clínica raramente tem só dois estados. Além de confirmado e cancelado, existe pendente de confirmação, remarcado, em espera e outros específicos de cada plataforma. Fluxo que dispara só com base em confirmado ou cancelado ignora transição intermediária e manda comunicação no momento errado, ou deixa de mandar quando deveria.
- Ignorar paginação e janela de data. API que devolve muito dado usa paginação. Consumir só a primeira página e apresentar como se fosse a agenda completa é um erro que passa despercebido numa clínica pequena e vira falha grave conforme o volume cresce. Configure janela de data adequada ao caso de uso e implemente paginação corretamente desde o início.
- Não implementar reconciliação periódica. Webhook é eficiente, mas a estratégia robusta combina webhook para reação em tempo próximo do real com reconciliação periódica via
updated_since. Isso recupera evento perdido por falha temporária de entrega, sem depender só do reenvio automático do fornecedor. - Armazenar estado sem versionamento. Se o sistema local guarda cópia do agendamento, ele precisa registrar quando cada registro foi atualizado pela última vez e qual era o estado anterior. Sem isso, diagnosticar uma inconsistência de sincronização vira tentativa e erro.
Perguntas frequentes sobre integração de API de agendamento clínico
A API da ByDoctor permite criar ou cancelar consultas programaticamente?
Não. A API pública do ByDoctor é somente leitura por desenho: dois endpoints, GET /appointments e GET /appointments/{id}, sem POST, PATCH nem DELETE. É uma garantia de segurança, não uma limitação temporária. Quem você conecta lê os agendamentos, nunca altera nem apaga nada dentro do ByDoctor.
Como evitar que meu sistema fique dessincronizado da agenda da clínica?
Combine dois mecanismos: webhook para reagir no momento em que um evento acontece, e reconciliação periódica com o parâmetro updated_since para recuperar o que um webhook não confirmado possa ter perdido. Nunca interprete a ausência de um agendamento numa consulta filtrada como cancelamento: ele pode só estar fora da janela de data ou do filtro de status usado.
Os agendamentos cancelados desaparecem da API do ByDoctor?
Não. Um agendamento cancelado continua aparecendo na listagem, só que com status: "cancelled" em vez de sumir da resposta. Isso é o que permite ao sistema consumidor atualizar o próprio estado local sem confundir "fora do filtro" com "excluído".
Qual o limite de requisições da API do ByDoctor?
60 requisições por minuto e 10.000 por dia, por chave de API, segundo a documentação técnica em docs.bydoctor.com.br. A janela de data de uma consulta (start_date a end_date) também tem limite: no máximo 92 dias por requisição, o que empurra o desenvolvedor a paginar e filtrar em vez de tentar baixar a agenda inteira de uma vez.
Qual o nível técnico necessário para integrar a API do ByDoctor a um sistema existente?
Básico a intermediário. A API segue REST com autenticação por chave (Authorization: Bearer), o padrão mais comum em integração de software. Qualquer desenvolvedor com experiência em consumir API REST consegue começar sozinho usando a documentação em docs.bydoctor.com.br, que traz exemplo de requisição e resposta completa em cada endpoint.
Resumo
Integrar a agenda de uma clínica a um sistema próprio é, antes de tudo, uma decisão de arquitetura: webhook em vez de polling, parâmetro updated_since para reconciliação, e clareza sobre se a API escolhida cobre só leitura ou também escrita. A API do ByDoctor é somente leitura por desenho, com webhook para os três eventos de agendamento e limite de 60 req/min. O roadmap de escopo de escrita não está descrito na documentação pública atual.
Para começar, a página para desenvolvedores é o ponto de partida para gerar sua chave, e a documentação técnica completa cobre autenticação, endpoints, parâmetros e exemplo de payload de webhook.