> ## 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. # Criar um agendamento > Cria um agendamento presencial com `status: "scheduled"` e `origin: "api"`, no tipo de atendimento informado em `appointment_type_id` (veja `GET /appointment-types`) e com o pagador Particular do profissional; o valor vem da tabela de preços da clínica. Requer o escopo `appointments:write`. Envie `Idempotency-Key` para poder repetir a chamada com segurança. Responde `409` com `code` `slot_blocked` (horário bloqueado na agenda do profissional) ou `room_required` (a clínica exige sala e a grade do profissional não tem sala padrão para o horário). O corpo da resposta é o mesmo objeto de `GET`. ## OpenAPI ````yaml /openapi.json post /api/public/v1/appointments openapi: 3.0.3 info: description: >- API REST somente leitura de agendamentos e webhooks em tempo real para integrações de clínicas. title: ByDoctor Public API version: v1 servers: - description: Produção url: https://api.bydoctor.com.br security: [] paths: /api/public/v1/appointments: post: tags: - appointments summary: Criar um agendamento description: >- Cria um agendamento presencial com `status: "scheduled"` e `origin: "api"`, no tipo de atendimento informado em `appointment_type_id` (veja `GET /appointment-types`) e com o pagador Particular do profissional; o valor vem da tabela de preços da clínica. Requer o escopo `appointments:write`. Envie `Idempotency-Key` para poder repetir a chamada com segurança. Responde `409` com `code` `slot_blocked` (horário bloqueado na agenda do profissional) ou `room_required` (a clínica exige sala e a grade do profissional não tem sala padrão para o horário). O corpo da resposta é o mesmo objeto de `GET`. operationId: appointments_create parameters: - description: >- Chave opcional (até 255 caracteres) que torna a criação idempotente: repetir a mesma requisição com a mesma chave em até 24 horas devolve o registro já criado, com o cabeçalho `Idempotent-Replayed: true`, em vez de criar outro. A mesma chave com um corpo diferente, ou em outro endpoint, responde `422`. in: header name: Idempotency-Key schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PublicAppointmentCreate' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PublicAppointmentCreate' multipart/form-data: schema: $ref: '#/components/schemas/PublicAppointmentCreate' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PublicAppointment' description: '' security: - ApiKeyAuth: [] components: schemas: PublicAppointmentCreate: description: >- Corpo para criar um agendamento. O agendamento nasce presencial, com `status: "scheduled"` e `origin: "api"`, no tipo informado e com o pagador Particular do profissional; o valor vem da tabela de preços da clínica. properties: appointment_type_id: description: >- `id` de um tipo de atendimento ativo da clínica (`GET /appointment-types`). type: integer note: description: Observação interna do agendamento, até 2000 caracteres. maxLength: 2000 type: string patient_id: description: '`patient.id` de um paciente ativo da clínica.' type: integer professional_id: description: >- `professional.id` de um profissional ativo da clínica que atende pacientes. type: integer room_id: description: >- `room.id` de uma sala ativa. Omitido, usa a sala padrão da grade do profissional, se houver. nullable: true type: integer start_at: description: >- Início do atendimento, ISO 8601. Sem fuso horário, é lido em America/Sao_Paulo. Os segundos devem ser `00`. format: date-time type: string required: - appointment_type_id - patient_id - professional_id - start_at type: object PublicAppointment: properties: appointment_type: allOf: - $ref: '#/components/schemas/AppointmentTypeSummary' readOnly: true created_at: format: date-time readOnly: true type: string end_at: format: date-time readOnly: true type: string id: format: uuid nullable: true readOnly: true type: string modality: $ref: '#/components/schemas/ModalityEnum' origin: $ref: '#/components/schemas/OriginEnum' patient: allOf: - $ref: '#/components/schemas/PatientSummary' nullable: true readOnly: true professional: allOf: - $ref: '#/components/schemas/ProfessionalSummary' nullable: true readOnly: true room: allOf: - $ref: '#/components/schemas/RoomSummary' nullable: true readOnly: true start_at: format: date-time readOnly: true type: string status: allOf: - $ref: '#/components/schemas/PublicAppointmentStatusEnum' description: >- One of: requested, scheduled, confirmed, checked_in, completed, no_show, cancelled. readOnly: true updated_at: format: date-time readOnly: true type: string required: - appointment_type - created_at - end_at - id - modality - origin - patient - professional - room - start_at - status - updated_at type: object AppointmentTypeSummary: description: Tipo de atendimento do agendamento, como "Consulta" ou "Retorno". properties: id: type: integer name: type: string required: - id - name type: object ModalityEnum: description: |- * `in_person` - Presencial * `telehealth` - Teleconsulta enum: - in_person - telehealth type: string OriginEnum: description: |- * `staff` - Equipe * `patient_booking` - Agendamento online * `api` - API pública enum: - staff - patient_booking - api type: string PatientSummary: description: Paciente do agendamento. properties: id: type: integer name: type: string phone: nullable: true type: string required: - id - name - phone type: object ProfessionalSummary: description: Profissional responsável pelo atendimento. properties: id: type: integer name: type: string specialty: nullable: true type: string required: - id - name - specialty type: object RoomSummary: description: Sala em que o atendimento acontece, quando a clínica usa salas. properties: id: type: integer name: type: string required: - id - name type: object PublicAppointmentStatusEnum: enum: - requested - scheduled - confirmed - checked_in - completed - no_show - cancelled type: string securitySchemes: ApiKeyAuth: description: Chave de API no formato bd_live_xxxxxxxx.xxxx... scheme: bearer type: http ````