Consultar disponibilidade de horários

A consulta de grade de disponibilidade permite buscar os horários livres da clínica para múltiplos tipos de recursos (profissionais, salas e equipamentos) dentro de um intervalo de até 15 dias. Os slots de atendimento são calculados dinamicamente com base nas grades de atendimento, tempos médios por tipo de consulta e regras de restrições (especialidade, convênio e tipo de consulta).

Requisito: Nova Disponibilidade

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 de disponibilidade unificada é uma funcionalidade exclusiva da nova disponibilidade."

curl -G "https://api.clinicanasnuvens.com.br/disponibilidade" \
  -H "Authorization: Basic BASE64_DO_CLIENT_ID_E_SECRET" \
  -H "clinicaNasNuvens-cid: SEU_TOKEN_DE_CLINICA" \
  --data-urlencode "dataInicio=2026-10-27" \
  --data-urlencode "dataFim=2026-11-02" \
  --data-urlencode "tipoRecurso=PROFISSIONAL" \
  --data-urlencode "codigoEspecialidade=3" \
  --data-urlencode "codigoTipoConsulta=5"

Parâmetros de consulta (Query Params)

Parâmetro	Tipo	Obrigatório	Descrição
dataInicio	LocalDate (YYYY-MM-DD)	Sim	Data inicial do período de busca.
dataFim	LocalDate (YYYY-MM-DD)	Não	Data final do período de busca (máximo de 15 dias a partir de dataInicio). Se omitida, busca apenas o dia de dataInicio.
tipoRecurso	Enum	Não	Filtra pelo tipo de recurso: PROFISSIONAL, SALA ou EQUIPAMENTO.
codigoRecurso	Long	Não	Identificador do recurso específico. Para profissionais, aceita tanto o idRecurso quanto o idExecutorAgenda. Se omitido, realiza busca aberta entre todos os recursos habilitados do tipo.
codigoEspecialidade	Long	Não	Identificador da especialidade médica para filtrar profissionais e aplicar restrições.
codigoPlanoConvenio	Long	Não	Identificador do plano/convênio para validação de restrições de atendimento.
codigoTipoConsulta	Long	Não	Identificador do tipo de consulta. Define o tempo de atendimento de cada slot e valida restrições.

Exemplo de resposta

[
  {
    "dia": "2026-10-27",
    "totalSlotsDisponiveis": 4,
    "recursos": [
      {
        "idRecurso": 42,
        "idExecutorAgenda": 10,
        "idPessoaExecutor": 105,
        "nomeRecurso": "Dra. Maria Silva",
        "tipoRecurso": "PROFISSIONAL",
        "especialidade": "Cardiologia",
        "idGrupoRecurso": null,
        "nomeGrupoRecurso": null,
        "restricoesDoDia": [
          {
            "tipo": "PERMITIR",
            "referencia": "CONVENIO",
            "idReferencia": 12,
            "descricao": "Unimed",
            "horaInicio": "08:00:00",
            "horaFim": "12:00:00"
          }
        ],
        "slots": [
          {
            "inicio": "08:00:00",
            "fim": "08:30:00",
            "vagasRestantes": 1
          },
          {
            "inicio": "08:30:00",
            "fim": "09:00:00",
            "vagasRestantes": 1
          }
        ]
      }
    ]
  }
]

Como utilizar os identificadores para agendar

Ao agendar uma consulta via POST /agenda/novo:

• Para profissionais, envie o campo idPessoaExecutor (e opcionalmente idExecutorAgenda) obtido no retorno de disponibilidade.
• Para salas ou equipamentos, envie o idRecurso e tipoRecurso na lista de recursos adicionais (recursos: [ { "idRecurso": 88, "tipoRecurso": "SALA" } ]).

Consulte o guia Criar um agendamento para os detalhes do payload de gravação.

Operações relacionadas

• Consultar próximo horário disponível: Para localizar rapidamente a primeira data/hora com vaga livre.
• Listar recursos de disponibilidade: Para descobrir os profissionais, salas e equipamentos habilitados na disponibilidade.

Veja na Referência

Os detalhes técnicos e schemas completos estão em Referência › Disponibilidade › Consultar disponibilidade de horários.