Depois do agendamento

Após a criação, o agendamento pode ser consultado, ter o status alterado, ser alterado ou remarcado. Cada operação tem regras próprias.

Qual operação usar

  O que mudou?
      │
      ├── Só a situação (confirmou, faltou, cancelou)
      │       └──► PUT /agenda/alteracao-status
      │            altera apenas o status
      │
      ├── Só a data e o horário
      │       └──► POST /agenda/{id}/remarcar
      │            registra histórico, não aceita data retroativa
      │
      └── Qualquer outro dado (convênio, local, procedimentos)
              └──► PUT /agenda/{id}
                   substituição completa, exige o corpo da requisição inteiro

O endpoint PUT /agenda/alteracao-status altera apenas o status do agendamento. O PUT /agenda/{id} também recebe o status, mas exige os oito campos obrigatórios e aplica regras adicionais conforme a situação do agendamento.

Consultar

São quatro operações de consulta, com respostas diferentes:

Operação	Retorna	Uso
GET /agenda/{id}	Agendamento completo, com procedimentos[]	Consulta antes de uma alteração
GET /agenda/{id}/resumida	Paciente, data, horários, status, contatos	Exibição resumida
GET /agenda/profissional	Agenda resumida de um executor entre a data inicial e a data final	Grade de horários do dia
GET /agenda/lista	Agendamentos completos entre a data inicial e a data final	Sincronização

Campos das operações resumidas. Nas duas operações resumidas, os horários são retornados em horaInicial e horaFinal, e o status é retornado como texto de exibição ("Confirmado"). Esse texto não corresponde aos valores aceitos nas operações de alteração.

No GET /agenda/lista, os parâmetros dataInicial e dataFinal são obrigatórios. O parâmetro dataPor define se o período se aplica à data do agendamento ou à data de criação. A resposta inclui agendamentos em todos os status.

Alterar o status

O identificador é enviado no corpo da requisição, pois esta rota não tem {id} no caminho:

curl -X PUT "https://api.clinicanasnuvens.com.br/agenda/alteracao-status" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  -H "Content-Type: application/json" \
  -d '{ "idAgenda": 1001, "status": "CONFIRMADO" }'

Qualquer status pode ser alterado para qualquer outro.

Saída do status cancelado

Enquanto o agendamento está cancelado, ele não ocupa o horário. Ao alterar o status de um agendamento cancelado, o sistema revalida o conflito de profissional e de paciente, e a alteração é recusada se outro agendamento tiver ocupado aquele horário nesse intervalo.

Alterar agendamento completo

O PUT /agenda/{id} substitui os dados do agendamento pelos enviados no corpo da requisição. Os campos não informados não são preservados; para manter os valores atuais, consulte o agendamento com GET /agenda/{id} antes da alteração e envie o corpo da requisição completo.

A alteração aceita data retroativa.

Cada campo omitido tem um efeito próprio:

Campo omitido	Resultado
procedimentos	Remove todos os procedimentos
Um item de procedimentos sem o id dele	Aquele item é excluído
idOrigemPaciente, idRotulo	Limpam o campo
idPessoaExecutor	Mantém o executor atual
idPaciente idPacienteConvenio idTipoConsulta idLocalAgenda status data horaInicio horaFim	400 Bad Request, pois são obrigatórios

Uma vez definido, o idPessoaExecutor pode ser trocado por outro executor, mas não removido por esta API.

Para preservar os procedimentos existentes, reenvie cada um com o seu id:

{
  "procedimentos": [
    { "id": 9001, "idTipoProcedimento": 4, "quantidade": 1 },
    { "idTipoProcedimento": 7, "quantidade": 2 }
  ]
}

O primeiro item é mantido; o segundo, sem id, é criado.

Remarcar

curl -X POST "https://api.clinicanasnuvens.com.br/agenda/1001/remarcar" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  -H "Content-Type: application/json" \
  -d '{
    "novaData": "2026-10-12",
    "novoHorarioInicial": "09:00:00",
    "novoHorarioFinal": "09:30:00",
    "motivo": "Paciente solicitou outro dia."
  }'

A remarcação não aceita data retroativa. A remarcação registra histórico e incrementa o contador de remarcações do agendamento.

Comportamentos automáticos

Algumas operações atualizam outros registros automaticamente:

Ação	Efeito
Informar telefoneCelularPaciente ou emailPaciente	Atualiza o cadastro do paciente
Criar agendamento para paciente na lista de espera	Remove o paciente da lista de espera, quando o profissional corresponde. Ver Usar a fila
Informar idPromocao	Recalcula os valores do procedimento
Alterar o status	Registra o histórico da mudança e recalcula a situação de faturamento do agendamento

Veja na Referência

Os detalhes de cada operação, campo a campo, estão em Referência › Agenda.