{"openapi":"3.0.3","info":{"title":"Clínica - API Externa","version":"1.0.0-preview","description":"Especificação pública da API externa para integrações com pacientes, profissionais, serviços, atendimentos, financeiro e agendamento online."},"servers":[{"url":"https://clinica.nortweb.com.br/api/external","description":"Base da API externa"}],"tags":[{"name":"Cadastros","description":"Profissionais, serviços e pacientes da clínica autenticada."},{"name":"Agenda","description":"Atendimentos e solicitações de agendamento online."},{"name":"Financeiro","description":"Resumo consolidado de receitas, despesas e comissões."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"Use o token gerado em Configurações > API."}},"schemas":{"Pagination":{"type":"object","properties":{"total":{"type":"integer","example":24},"limit":{"type":"integer","example":50},"offset":{"type":"integer","example":0},"has_more":{"type":"boolean","example":false}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","example":"Token de API inválido ou expirado"}}},"Professional":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string"},"especialidade":{"type":"string","nullable":true},"conselho_numero":{"type":"string","nullable":true},"telefone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"ativo":{"type":"boolean"},"valor_consulta":{"type":"number","nullable":true},"percentual_repasse":{"type":"number","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Service":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string"},"descricao":{"type":"string","nullable":true},"valor":{"type":"number","nullable":true},"duracao_minutos":{"type":"integer","nullable":true},"categoria":{"type":"string","nullable":true},"ativo":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Patient":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string"},"cpf":{"type":"string","nullable":true},"data_nascimento":{"type":"string","format":"date","nullable":true},"telefone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"endereco":{"type":"string","nullable":true},"observacoes_medicas":{"type":"string","nullable":true},"alergias":{"type":"array","items":{"type":"string"}},"convenio":{"type":"string","nullable":true},"ativo":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Appointment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"paciente_id":{"type":"string","format":"uuid"},"paciente_nome":{"type":"string"},"profissional_id":{"type":"string","format":"uuid"},"profissional_nome":{"type":"string"},"servico_id":{"type":"string","format":"uuid","nullable":true},"servico_nome":{"type":"string","nullable":true},"data":{"type":"string","format":"date"},"hora":{"type":"string","example":"09:00"},"status":{"type":"string","enum":["agendado","confirmado","em_atendimento","concluido","cancelado","faltou"]},"valor":{"type":"number","nullable":true},"forma_pagamento":{"type":"string","nullable":true},"observacoes":{"type":"string","nullable":true},"prontuario":{"type":"string","nullable":true},"retorno_dias":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"BookingRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"paciente_nome":{"type":"string"},"paciente_telefone":{"type":"string","nullable":true},"paciente_email":{"type":"string","nullable":true},"profissional_id":{"type":"string","format":"uuid","nullable":true},"profissional_nome":{"type":"string","nullable":true},"servico_id":{"type":"string","format":"uuid","nullable":true},"servico_nome":{"type":"string","nullable":true},"data":{"type":"string","format":"date"},"hora":{"type":"string","example":"09:00"},"observacoes":{"type":"string","nullable":true},"status":{"type":"string","enum":["pendente","confirmado","recusado","cancelado"]},"created_at":{"type":"string","format":"date-time"}}},"FinancialSummary":{"type":"object","properties":{"period":{"type":"object","properties":{"month":{"type":"string","example":"2026-06"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"totals":{"type":"object","properties":{"revenue":{"type":"number"},"expenses":{"type":"number"},"net":{"type":"number"},"entries":{"type":"integer"},"completed_appointments":{"type":"integer"}}},"commissions":{"type":"array","items":{"type":"object","properties":{"profissional_id":{"type":"string","format":"uuid"},"profissional_nome":{"type":"string"},"percentual_repasse":{"type":"number"},"atendimentos_concluidos":{"type":"integer"},"receita":{"type":"number"},"comissao":{"type":"number"}}}}}},"CreatePatientInput":{"type":"object","required":["nome"],"properties":{"nome":{"type":"string","minLength":2,"maxLength":160},"cpf":{"type":"string","maxLength":30},"data_nascimento":{"type":"string","format":"date"},"telefone":{"type":"string","maxLength":40},"email":{"type":"string","format":"email"},"endereco":{"type":"string","maxLength":500},"observacoes_medicas":{"type":"string","maxLength":5000},"alergias":{"type":"array","items":{"type":"string"}},"convenio":{"type":"string","maxLength":120},"ativo":{"type":"boolean"}}},"CreateAppointmentInput":{"type":"object","required":["paciente_id","profissional_id","data","hora"],"properties":{"paciente_id":{"type":"string","format":"uuid"},"profissional_id":{"type":"string","format":"uuid"},"servico_id":{"type":"string","format":"uuid"},"data":{"type":"string","format":"date"},"hora":{"type":"string","example":"09:00"},"status":{"type":"string","enum":["agendado","confirmado","em_atendimento","concluido","cancelado","faltou"],"default":"agendado"},"valor":{"type":"number"},"forma_pagamento":{"type":"string"},"observacoes":{"type":"string"},"prontuario":{"type":"string"},"retorno_dias":{"type":"integer"}}},"UpdateAppointmentStatusInput":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["agendado","confirmado","em_atendimento","concluido","cancelado","faltou"]}}}}},"paths":{"/":{"get":{"summary":"Metadados da API externa","responses":{"200":{"description":"Informações básicas e links úteis."}}}},"/v1/professionals":{"get":{"tags":["Cadastros"],"summary":"Listar profissionais","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false","all"]}},{"name":"include_inactive","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Lista paginada de profissionais.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Professional"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/services":{"get":{"tags":["Cadastros"],"summary":"Listar serviços","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false","all"]}},{"name":"include_inactive","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Lista paginada de serviços.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/patients":{"get":{"tags":["Cadastros"],"summary":"Listar pacientes","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false","all"]}},{"name":"include_inactive","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Lista paginada de pacientes.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Patient"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Cadastros"],"summary":"Criar paciente","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePatientInput"}}}},"responses":{"201":{"description":"Paciente criado.","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/Patient"}}}}}},"400":{"description":"Dados inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/appointments":{"get":{"tags":["Agenda"],"summary":"Listar atendimentos","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["agendado","confirmado","em_atendimento","concluido","cancelado","faltou"]}},{"name":"professional_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"patient_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Lista paginada de atendimentos.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Appointment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Agenda"],"summary":"Criar atendimento","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAppointmentInput"}}}},"responses":{"201":{"description":"Atendimento criado.","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/Appointment"}}}}}},"400":{"description":"Dados inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Paciente, profissional ou serviço não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflito de horário.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/appointments/{id}/status":{"patch":{"tags":["Agenda"],"summary":"Atualizar status do atendimento","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAppointmentStatusInput"}}}},"responses":{"200":{"description":"Atendimento atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/Appointment"}}}}}},"400":{"description":"Dados inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Atendimento não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/financial/summary":{"get":{"tags":["Financeiro"],"summary":"Obter resumo financeiro","security":[{"bearerAuth":[]}],"parameters":[{"name":"month","in":"query","schema":{"type":"string","example":"2026-06"}}],"responses":{"200":{"description":"Resumo consolidado do período.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialSummary"}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/booking-requests":{"get":{"tags":["Agenda"],"summary":"Listar solicitações do agendamento online","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pendente","confirmado","recusado","cancelado"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Lista paginada das solicitações públicas.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BookingRequest"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}