> ## 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_<id>.<secret>`. 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.

# Profissionais

> Listar os profissionais da clínica que atendem pacientes para obter o professional_id usado na criação de agendamentos.

A lista traz os membros ativos da clínica que atendem pacientes: são exatamente os `id` aceitos como `professional_id` em [`POST /appointments`](/agendamentos#criar-um-agendamento). Administradores e equipe que não atendem não aparecem.

| Método | Rota                  | Descrição                                           |
| ------ | --------------------- | --------------------------------------------------- |
| `GET`  | `/professionals`      | Lista os profissionais ativos que atendem pacientes |
| `GET`  | `/professionals/{id}` | Detalhe de um profissional                          |

As duas rotas exigem o escopo `appointments:read`, que toda chave já tem. Não há escrita: profissionais são cadastrados no aplicativo.

## Listar profissionais

```bash theme={null}
curl -H "Authorization: Bearer bd_live_xxxxxxxx.yyyy" \
  "https://api.bydoctor.com.br/api/public/v1/professionals"
```

```json theme={null}
{
  "next": null,
  "previous": null,
  "results": [
    { "id": 12, "name": "Dr. João Souza", "specialty": "Cardiologia" },
    { "id": 15, "name": "Dra. Ana Lima", "specialty": null }
  ]
}
```

A resposta tem o mesmo formato paginado das outras listas (`next`, `previous`, `results`), em ordem de `id`.

| Campo       | Tipo               | Descrição                                                                 |
| ----------- | ------------------ | ------------------------------------------------------------------------- |
| `id`        | `integer`          | Use como `professional_id`. É o mesmo `professional.id` dos agendamentos. |
| `name`      | `string`           | Nome com o título cadastrado, como "Dra. Ana Lima".                       |
| `specialty` | `string` ou `null` | Especialidade principal.                                                  |

## Buscar um profissional

```bash theme={null}
curl -H "Authorization: Bearer bd_live_xxxxxxxx.yyyy" \
  "https://api.bydoctor.com.br/api/public/v1/professionals/12"
```

Um `id` inexistente, inativo ou de outra clínica responde `404 Not Found` com `{"detail": "No professional with this id in your clinic."}`.

## O que a API não devolve

O objeto é o mesmo bloco `professional` que já vem em cada agendamento. Por minimização de dados (LGPD, art. 6º, III), a API não devolve e-mail, telefone, CPF, foto nem número de registro no conselho do profissional: nenhum deles é necessário para agendar.