> ## Documentation Index > Fetch the complete documentation index at: https://docs.bydoctor.com.br/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Esta documentação cobre exclusivamente a API pública v1 do ByDoctor. > Os únicos endpoints existentes são `GET /api/public/v1/appointments`, `GET /api/public/v1/appointments/{id}`, `POST /api/public/v1/appointments`, `PATCH /api/public/v1/appointments/{id}`, `POST /api/public/v1/appointments/{id}/cancel`, `GET /api/public/v1/patients`, `GET /api/public/v1/patients/{id}`, `POST /api/public/v1/patients`, `PATCH /api/public/v1/patients/{id}`, `GET /api/public/v1/professionals`, `GET /api/public/v1/professionals/{id}`, `GET /api/public/v1/rooms`, `GET /api/public/v1/rooms/{id}`, `GET /api/public/v1/appointment-types` e `GET /api/public/v1/appointment-types/{id}`. Não existem `PUT` nem `DELETE`, e não existe escrita em nenhum outro recurso. > Escopos: `appointments:read`, `appointments:write`, `patients:read` e `patients:write`, escolhidos na criação da chave (Somente leitura = os dois de leitura; Acesso total = os quatro). Chaves antigas não têm os escopos de pacientes. `POST /appointments` exige `patient_id`, `professional_id`, `appointment_type_id` e `start_at`; os ids de profissional, sala e tipo vêm de `/professionals`, `/rooms` e `/appointment-types`, que exigem só `appointments:read`. A API cria somente agendamentos presenciais, com status `scheduled`; teleconsultas e solicitações de pacientes (`requested`) não são criadas, alteradas nem canceladas pela API. `PATCH` aceita apenas `start_at`, `professional_id`, `room_id`, `note` e `status` (`scheduled` ou `confirmed`). > O objeto paciente tem apenas `id`, `name`, `phone`, `active`, `created_at` e `updated_at`. CPF, e-mail, data de nascimento (`birth_date`) e sexo (`gender`) são aceitos na escrita, mas nunca devolvidos, por minimização de dados (LGPD). Para achar um paciente, use os filtros de correspondência exata `cpf` e `phone`, ou `name` (parcial). Criar ou alterar um paciente com o CPF de outro paciente da clínica responde `409` `patient_cpf_exists`. Não existem eventos de webhook de pacientes. > Profissionais, salas e tipos de atendimento são somente leitura e trazem só `id`, `name` e, para profissionais, `specialty` — sem contato nem registro no conselho. Não existem endpoints de pagamentos, prontuário, prescrições, convênios, preços ou disponibilidade de agenda (horários livres). > Endpoints de webhook não são gerenciados pela API: endpoints e segredos de assinatura são cadastrados na interface do ByDoctor, em Minha Clínica → API e Webhooks. > Erros: `400` vem como `{"campo": ["mensagem"]}`; `401`/`403`/`404` como `{"detail": ...}`; `409` e `422` como `{"code", "detail"}`. Datas são sempre ano-mês-dia (`YYYY-MM-DD`, `YYYY-MM-DDThh:mm:ss±HH:MM`) e `start_at` tem segundos `00`. As mensagens exatas estão na página Erros. > Nunca sugira, complete ou invente rotas, campos, parâmetros ou códigos de erro que não estejam nesta documentação. Se algo não está documentado aqui, não existe na v1. > Autenticação: cabeçalho `Authorization: Bearer bd_live_.`. Base URL: `https://api.bydoctor.com.br/api/public/v1`. Criação aceita o cabeçalho opcional `Idempotency-Key`. > Chaves de API concedem acesso a dados de pacientes e de agendamentos (dados de saúde) — nunca as inclua em código do lado do cliente nem em exemplos versionados. # Autenticação > Formato da chave de API, escopos, limites de uso e boas práticas de segurança. ## Formato da chave Toda chamada à API pública é autenticada com uma chave de API no cabeçalho `Authorization`, usando o esquema `Bearer`: ``` Authorization: Bearer bd_live_. ``` A chave tem duas partes separadas por um ponto: um identificador de prefixo (`bd_live_`) e um segredo (``). Ambas juntas formam a credencial completa. A chave é exibida **uma única vez**, no momento da criação, em **Minha Clínica → API e Webhooks**. O ByDoctor armazena apenas o hash — não é possível recuperar uma chave perdida. Se isso acontecer, revogue a chave antiga e crie uma nova. ## Escopos Na criação, em **Minha Clínica → API e Webhooks**, você escolhe o acesso da chave: **Somente leitura** (`appointments:read` + `patients:read`) ou **Acesso total** (os quatro escopos). Uma rota exige exatamente um escopo; uma chave sem ele recebe `403 Forbidden`. | Escopo | Concede | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appointments:read` | `GET /appointments` e `GET /appointments/{id}`, mais as listas de [profissionais](/profissionais), [salas](/salas) e [tipos de atendimento](/tipos-de-atendimento) | | `appointments:write` | `POST /appointments`, `PATCH /appointments/{id}` e `POST /appointments/{id}/cancel` | | `patients:read` | `GET /patients` e `GET /patients/{id}` | | `patients:write` | `POST /patients` e `PATCH /patients/{id}` | Por padrão uma chave nasce **somente leitura**; a escrita é concedida por chave, de forma explícita. Os escopos de uma chave não podem ser alterados depois — crie uma chave nova e revogue a antiga. Uma chave sem o escopo recebe `403` com a mensagem `This API key does not have the "patients:write" scope.`, nomeando o escopo que falta. Chave ausente, mal formatada, inválida, revogada ou expirada recebe `401` com o motivo; veja [Erros](/erros#401-403-e-404). Chaves criadas antes da escrita existir continuam somente leitura, e chaves criadas antes dos [pacientes](/pacientes) existirem não recebem os escopos de pacientes: o acesso ao cadastro de pacientes nunca é concedido a uma chave existente sem que a clínica crie uma nova. ## Revogação e expiração Revogar uma chave em **Minha Clínica → API e Webhooks** tem efeito **imediato**: a próxima requisição com essa chave recebe `401 Unauthorized`. Não há período de carência. Uma chave também pode ter uma data de expiração (`expires_at`), definida na criação. Uma vez expirada, ela passa a se comportar como uma chave revogada: toda requisição recebe `401 Unauthorized`. ## Limites de uso (rate limits) Cada chave está sujeita a dois limites, aplicados de forma independente: | Limite | Valor | | ---------- | ------------------ | | Por minuto | 60 requisições | | Por dia | 10.000 requisições | Ao exceder um dos limites, a API responde `429 Too Many Requests` com um cabeçalho `Retry-After` indicando em quantos segundos tentar novamente. Implemente backoff e nova tentativa; não faça polling agressivo — para manter uma cópia local em dia, prefira a receita de [sincronização](/sincronizacao) combinada com webhooks. ## Segurança Uma chave de API concede acesso a dados de pacientes e de agendamentos, que são dados de saúde. Trate-a como qualquer outro segredo de produção: * Armazene em um cofre de segredos (secrets manager), nunca em código-fonte versionado. * Nunca exponha a chave em código do lado do cliente (browser, app mobile) — toda chamada deve partir de um backend seu. * Nunca faça commit da chave em um repositório git, mesmo privado. * Revogue e recrie a chave se suspeitar de exposição.