Criar um agendamento, passo a passo

O exemplo agenda uma consulta para o paciente 3 com o Dr. Silva. Os passos 1 a 5 são de descoberta; o 6 é a gravação.

Registros inativos

Nas listagens de cadastros (executores, locais, tipos de consulta, convênios), o parâmetro somenteAtivos tem padrão false, portanto os registros inativos também são retornados. A criação do agendamento recusa cadastros inativos. Envie somenteAtivos=true nas consultas dos passos seguintes para listar apenas os registros ativos.

1. Encontre o executor

Detalhe completo em Executores de agenda.

curl -G "https://api.clinicanasnuvens.com.br/executor-agenda/lista" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  --data-urlencode "nomeContem=Silva" \
  --data-urlencode "somenteAtivos=true" \
  --data-urlencode "somenteProfissionaisSaude=true"

Guarde os dois números de cada executor: o id (1) serve para consultar a disponibilidade; o idpessoa (42) vai no agendamento. Ver Identificadores.

2. Encontre o local e o tipo de consulta

Detalhe em Locais de agenda e em Tipos de consulta.

curl -G "https://api.clinicanasnuvens.com.br/local-agenda/lista" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  --data-urlencode "somenteAtivos=true"

curl -G "https://api.clinicanasnuvens.com.br/tipo-consulta/lista" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  --data-urlencode "somenteAtivos=true"

No exemplo, o local é 2 e o tipo de consulta é 15.

3. Garanta o convênio do paciente

O agendamento exige o idPacienteConvenio, o vínculo entre o paciente e o convênio, não o convênio da clínica. Detalhe em Convênios do paciente.

curl -G "https://api.clinicanasnuvens.com.br/convenio-paciente/lista" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  --data-urlencode "idPaciente=3" \
  --data-urlencode "somenteAtivos=true"

{
  "lista": [
    {
      "id": 12,
      "idTipoConvenio": 8,
      "nomeTipoConvenio": "Unimed",
      "ativo": true,
      "dataValidade": "2027-12-31",
      "carteirinha": "123456789012"
    }
  ],
  "pagina": 0,
  "totalPaginas": 1
}

Confira se algum item retornado é o convênio que será usado no agendamento, pelo idTipoConvenio ou pelo nomeTipoConvenio. Se o convênio estiver na lista, o id do item é o idPacienteConvenio (no exemplo, 12). Se a lista vier vazia ou não trouxer o convênio desejado, crie o vínculo:

curl -X POST "https://api.clinicanasnuvens.com.br/convenio-paciente/associar" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  -H "Content-Type: application/json" \
  -d '{
    "idPaciente": 3,
    "idTipoConvenio": 8,
    "carteirinha": "123456789012",
    "dataValidade": "2027-12-31"
  }'

O id da resposta é o idPacienteConvenio.

4. Ache um horário livre

Use o id do executor, não o idpessoa:

curl -G "https://api.clinicanasnuvens.com.br/executor-agenda/disponibilidade" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  --data-urlencode "idExecutorAgenda=1" \
  --data-urlencode "data=2026-10-05" \
  --data-urlencode "dataFim=2026-10-10"

[
  { "idTipoConsulta": 15, "data": "2026-10-05", "horaInicio": "08:00:00", "horaFim": "08:30:00" },
  { "idTipoConsulta": 15, "data": "2026-10-05", "horaInicio": "08:30:00", "horaFim": "09:00:00" }
]

O intervalo é limitado a 15 dias. Detalhe em Consultar disponibilidade.

Clínicas com Nova disponibilidade

Se a clínica utiliza a Nova disponibilidade com múltiplos recursos (profissionais, salas ou equipamentos), consulte os horários através do endpoint em Disponibilidade.

5. Confira os valores do procedimento

curl -G "https://api.clinicanasnuvens.com.br/tipo-procedimento/valores-venda" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  --data-urlencode "idTipoConvenio=8" \
  --data-urlencode "idTipoProcedimento=4" \
  --data-urlencode "dataBase=2026-10-05" \
  --data-urlencode "horaBase=08:00:00"

Se houver promoção vigente, o idPromocao retornado deve ser enviado no item de procedimentos. Detalhe em Procedimentos.

6. Crie o agendamento

curl -X POST "https://api.clinicanasnuvens.com.br/agenda/novo" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  -H "Content-Type: application/json" \
  -d '{
    "idPaciente": 3,
    "idPessoaExecutor": 42,
    "idPacienteConvenio": 12,
    "idTipoConsulta": 15,
    "idLocalAgenda": 2,
    "status": "AGENDADO",
    "data": "2026-10-05",
    "horaInicio": "08:00:00",
    "horaFim": "08:30:00",
    "observacoes": "Primeira consulta.",
    "notificarEmailPaciente": true,
    "notificarWhatsappPaciente": true,
    "procedimentos": [
      { "idTipoProcedimento": 4, "quantidade": 1 }
    ],
    "recursos": [
      { "idRecurso": 10, "tipoRecurso": "PROFISSIONAL" },
      { "idRecurso": 2, "tipoRecurso": "SALA" },
      { "idRecurso": 5, "tipoRecurso": "EQUIPAMENTO" }
    ]
  }'

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`idPaciente`	Integer	Sim	Paciente do agendamento
`idPessoaExecutor`	Integer	Conforme a clínica	Executor que vai atender. Ver Identificadores
`idPacienteConvenio`	Integer	Sim	Vínculo entre o paciente e o convênio, obtido em Convênios do paciente
`idTipoConsulta`	Integer	Sim	Tipo de consulta do agendamento
`idLocalAgenda`	Integer	Sim	Local de agenda em que o atendimento acontece
`status`	String	Sim	Situação do agendamento, por exemplo `AGENDADO` ou `CONFIRMADO`
`data`	String	Sim	Data do agendamento, no formato `AAAA-MM-DD`
`horaInicio`	String	Sim	Horário de início, no formato `HH:mm:ss`
`horaFim`	String	Sim	Horário de término, no formato `HH:mm:ss`
`idOrigemPaciente`	Integer	Não	Origem do paciente para este agendamento
`observacoes`	String	Não	Observações do agendamento, com até 500 caracteres
`telefoneCelularPaciente`	String	Não	Telefone celular do paciente, com até 20 caracteres. Atualiza o cadastro do paciente
`emailPaciente`	String	Não	E-mail do paciente. Atualiza o cadastro do paciente
`encaminhamento`	String	Não	Quem encaminhou o paciente, com até 150 caracteres
`idRotulo`	Integer	Não	Rótulo do agendamento
`salaEspera`	String	Não	`CRIAR` cria a sala de espera virtual do agendamento
`notificarSMSPaciente`	Boolean	Não	Envia SMS de aviso ao paciente. Padrão `false`
`notificarSMSProfissional`	Boolean	Não	Envia SMS de aviso ao profissional. Padrão `false`
`notificarEmailPaciente`	Boolean	Não	Envia e-mail de aviso ao paciente. Padrão `false`
`notificarEmailProfissional`	Boolean	Não	Envia e-mail de aviso ao profissional. Padrão `false`
`notificarWhatsappPaciente`	Boolean	Não	Envia mensagem de WhatsApp ao paciente. Padrão `false`
`procedimentos`	Array	Conforme a clínica	Procedimentos previstos para o agendamento
`procedimentos[].idTipoProcedimento`	Integer	Sim, por item	Procedimento que será executado
`procedimentos[].quantidade`	Integer	Não	Quantidade do procedimento
`procedimentos[].idPromocao`	Integer	Não	Promoção aplicada ao item, obtida nos valores de venda do procedimento
`procedimentos[].idEspecialidade`	Integer	Conforme a clínica	Especialidade associada ao procedimento

A resposta traz o agendamento completo, com o id usado nas operações seguintes:

{
  "id": 1001,
  "idPessoaExecutor": 42,
  "idPaciente": 3,
  "idOrigemPaciente": null,
  "idTipoConvenio": 12,
  "idTipoConsulta": 15,
  "idLocalAgenda": 2,
  "status": "AGENDADO",
  "data": "2026-10-05",
  "horaInicio": "08:00:00",
  "horaFim": "08:30:00",
  "observacoes": "Primeira consulta.",
  "telefoneCelularPaciente": null,
  "emailPaciente": null,
  "encaminhamento": null,
  "urlSalaEspera": null,
  "idRotulo": null,
  "procedimentos": [
    { "id": 9001, "idEspecialidade": null, "idPromocao": null, "idTipoProcedimento": 4, "nome": "Consulta", "quantidade": 1 }
  ]
}

Na resposta, o convênio volta no campo idTipoConvenio, com o valor enviado em idPacienteConvenio.

A criação aceita data retroativa, o que permite registrar um atendimento que já aconteceu.

Agendamento com múltiplos recursos

Para clínicas com a Nova disponibilidade ativada, é possível vincular recursos adicionais ao agendamento através do array recursos, combinando itens dos tipos PROFISSIONAL, SALA e EQUIPAMENTO.

Regras sobre os recursos:

Apenas um recurso de cada tipo: Não é permitido incluir mais de um recurso do mesmo tipo por agendamento (por exemplo, 2 recursos do tipo SALA).
Profissional e Executor da agenda:
- Se o recurso PROFISSIONAL for enviado em recursos e o idPessoaExecutor também for informado, o idPessoaExecutor deve ser o mesmo do profissional informado no recurso. Caso sejam diferentes, o agendamento será rejeitado.
- Se idPessoaExecutor for omitido (null) e o recurso PROFISSIONAL for informado, o sistema assume automaticamente este profissional como o executor da agenda.

As notificações não são automáticas

As cinco flags notificar são booleanos com padrão false. Omiti-las significa não avisar ninguém, nem paciente, nem profissional. Se a clínica espera que o paciente receba a confirmação, envie-as explicitamente.

Erros comuns (Bad Request)

Quando a criação é recusada, a API retorna 400 com o motivo em mensagem:

{
  "mensagem": "O profissional selecionado já possui um agendamento nesse horário.",
  "identificador": null,
  "errors": []
}

Situação	Motivo
Recusa em um dos identificadores	O registro existe mas está inativo. Inativos aparecem nas listagens e são recusados aqui
Conflito de horário	Já existe agendamento do profissional ou do paciente naquele horário
Um campo opcional sendo exigido	A clínica tem configuração que torna `idPessoaExecutor`, `procedimentos` ou `idEspecialidade` obrigatórios
Mais de um recurso do mesmo tipo	O array `recursos` contém dois ou mais recursos com o mesmo `tipoRecurso` (ex.: duas salas)
Divergência entre executor e recurso profissional	O `idPessoaExecutor` informado não corresponde ao profissional enviado no array `recursos`

Atenção a um efeito que não fica visível na resposta: o telefone e o e-mail informados no agendamento atualizam os do cadastro do paciente. Preencha esses campos apenas quando desejar atualizar o contato do paciente.

Próximo passo

O agendamento existe. Veja Depois do agendamento para consultar, alterar, mudar status e remarcar.

Registros inativos​

1. Encontre o executor​

2. Encontre o local e o tipo de consulta​

3. Garanta o convênio do paciente​

4. Ache um horário livre​

5. Confira os valores do procedimento​

6. Crie o agendamento​

Campos da requisição​

Agendamento com múltiplos recursos​

Erros comuns (Bad Request)​

Próximo passo​