Consultar próximo horário disponível
Esta operação localiza rapidamente a primeira data e o primeiro horário (horaInicio e horaFim) com vaga disponível a partir de uma data inicial (ou da data atual, se omitida), evitando a necessidade de varrer múltiplos dias de grade de atendimento.
A busca cobre até um ano à frente e retorna a identificação completa do recurso encontrado (idRecurso, idExecutorAgenda, idPessoaExecutor).
Esta operação é exclusiva para clínicas que possuem o recurso da Nova Disponibilidade habilitado no Clínica nas Nuvens. Se a funcionalidade não estiver ativa na clínica do token autenticado, a chamada retornará erro HTTP 400 Bad Request com a mensagem:
"A busca pela próxima data disponível é uma funcionalidade exclusiva da nova disponibilidade."
curl -G "https://api.clinicanasnuvens.com.br/disponibilidade/proximo-horario" \
-H "Authorization: Basic BASE64_DO_CLIENT_ID_E_SECRET" \
-H "clinicaNasNuvens-cid: SEU_TOKEN_DE_CLINICA" \
--data-urlencode "tipoRecurso=PROFISSIONAL" \
--data-urlencode "codigoRecurso=42" \
--data-urlencode "codigoEspecialidade=3" \
--data-urlencode "data=2026-10-27"
Parâmetros de consulta (Query Params)
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tipoRecurso | Enum | Sim | Tipo do recurso a consultar: PROFISSIONAL, SALA ou EQUIPAMENTO. |
codigoRecurso | Long | Sim | Identificador do recurso específico (idRecurso ou idExecutorAgenda para profissional). |
data | LocalDate (YYYY-MM-DD) | Não | Data inicial da busca. Se omitida, considera a data atual. |
codigoEspecialidade | Long | Não | Especialidade desejada para filtro de profissionais e restrições. |
codigoPlanoConvenio | Long | Não | Plano/convênio do paciente para validação de restrições. |
codigoTipoConsulta | Long | Não | Tipo de consulta para cálculo da duração da vaga e validação de restrições. |
Exemplo de resposta
A resposta devolve diretamente o objeto com o próximo horário livre encontrado:
{
"data": "2026-10-27",
"horaInicio": "08:00:00",
"horaFim": "08:30:00",
"idRecurso": 42,
"idExecutorAgenda": 10,
"idPessoaExecutor": 105,
"nomeRecurso": "Dra. Maria Silva",
"tipoRecurso": "PROFISSIONAL"
}
Caso não haja nenhuma data com horários livres para os critérios informados dentro do período de busca, a operação devolve erro de negócio (400 Bad Request com a mensagem pesquisa.erro.nenhuma.disponibilidade.encontrada), em vez de um objeto vazio.
Próximo passo
Com a data, horário e os identificadores do executor em mãos, prossiga para a gravação da consulta em Criar um agendamento enviando idPessoaExecutor.
Operações relacionadas
- Consultar disponibilidade de horários: Para consultar todos os horários livres de um período dia a dia.
- Listar recursos de disponibilidade: Para consultar os profissionais, salas e equipamentos cadastrados.
Veja na Referência
Os detalhes de cada campo estão em Referência › Disponibilidade › Consultar próximo horário disponível.