Introdução
Ambientes e URLs
Primeiros Passos
Autenticação
Endpoints da API
Fluxo de Agendamento
Webhooks
MCP
- Teste Agendamento
- Teste Confirmação
- Teste Webhook
Módulos Adicionais
FAQ

Autenticação

Para usar a API, primeiro você precisa obter um token JWT:

JavaScript

cURL

// Obter token de acesso
const response = await fetch(`${baseURL}/Acesso/login`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    identificacao: 'seu_usuario',
    senha: 'sua_senha',
    isHash: true
  })
});

const data = await response.json();
const token = data.token; // Guarde este token para requisições futuras

curl -X POST "${baseURL}/Acesso/login" \
  -H "Content-Type: application/json" \
  -d '{"identificacao":"seu_usuario","senha":"sua_senha"}'

// Obter token de acesso
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(baseURL);
  
  var loginData = new {
      identificacao = "seu_usuario",
      senha = "sua_senha"
  };
  
  var response = await client.PostAsJsonAsync("Acesso/login", loginData);
  var result = await response.Content.ReadAsAsync();
  string token = result.token; // Guarde este token
}

Renovar Token

O token expira em 24 horas. Use o refresh token para renová-lo:

JavaScript

cURL

// Renovar token
const refreshResponse = await fetch(`${baseURL}/Acesso/refreshToken?refreshToken=SEU_REFRESH_TOKEN&token=SEU_TOKEN`);
const newToken = await refreshResponse.json();

curl -X POST "${baseURL}/Acesso/refreshToken?refreshToken=SEU_REFRESH_TOKEN&token=SEU_TOKEN"

// Renovar token
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(baseURL);
  
  var response = await client.PostAsync($"Acesso/refreshToken?refreshToken={refreshToken}&token={token}", null);
  var result = await response.Content.ReadAsAsync();
  string newToken = result.token; // Novo token para usar
}

Agendamento

Listar Agendamentos

JavaScript

cURL

// Listar agendamentos
const response = await fetch(`${baseURL}/Medware/Agendamento/Listar?codMedico=123&dataInicio=01/10/2023&dataFim=31/10/2023`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const agendamentos = await response.json();
console.log(agendamentos);

curl -X GET "${baseURL}/Medware/Agendamento/Listar?codMedico=123&dataInicio=01/10/2023&dataFim=31/10/2023" \
  -H "Authorization: Bearer SEU_TOKEN"

// Listar agendamentos
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(baseURL);
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = await client.GetAsync("Medware/Agendamento/Listar?codMedico=123&dataInicio=01/10/2023&dataFim=31/10/2023");
  var agendamentos = await response.Content.ReadAsAsync();
}

Criar Agendamento

Para paciente já cadastrado, informe codPaciente. Para paciente novo, omita codPaciente e envie o objeto paciente com os dados mínimos.

JavaScript

cURL

// Criar novo agendamento
const agendamento = {
  codAgenda: 142,
  codMedico: 123,
  codPaciente: 456,
  codProcedimento: 789,
  codPlano: 101,
  codUnidade: 202,
  dataHoraAgendada: "2023-12-31T14:00:00"
};

const response = await fetch(`${baseURL}/Medware/Agendamento/Salvar`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(agendamento)
});

const resultado = await response.json();

curl -X POST "${baseURL}/Medware/Agendamento/Salvar" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{"codAgenda":142,"codMedico":123,"codPaciente":456,"codProcedimento":789,"codPlano":101,"codUnidade":202,"dataHoraAgendada":"2023-12-31T14:00:00"}'

// Criar novo agendamento
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(baseURL);
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var agendamento = new {
      codAgenda = 142,
      codMedico = 123,
      codPaciente = 456,
      codProcedimento = 789,
      codPlano = 101,
      codUnidade = 202,
      dataHoraAgendada = "2023-12-31T14:00:00"
  };
  
  var response = await client.PostAsJsonAsync("Medware/Agendamento/Salvar", agendamento);
  var resultado = await response.Content.ReadAsAsync();
}

Médicos e Especialidades

Listar Médicos

JavaScript

cURL

// Listar médicos
const response = await fetch(`${baseURL}/Medware/Medico/Listar?codunidade=1&codPlano=101&codprocedimento=201&dataInicio=01/01/2023&dataFim=31/12/2023`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const medicos = await response.json();

curl -X GET "${baseURL}/Medware/Medico/Listar?codunidade=1&codPlano=101&codprocedimento=201&dataInicio=01/01/2023&dataFim=31/12/2023" \
  -H "Authorization: Bearer SEU_TOKEN"

// Listar médicos
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(baseURL);
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = await client.GetAsync("Medware/Medico/Listar?codunidade=1&codPlano=101&codprocedimento=201&dataInicio=01/01/2023&dataFim=31/12/2023");
  var medicos = await response.Content.ReadAsAsync();
}

Listar Especialidades

JavaScript

cURL

// Listar especialidades
const response = await fetch(`${baseURL}/Medware/Especialidade/Listar?codUnidade=1&codMedico=123&codProcedimento=456&dataInicio=01/01/2023&dataFim=31/12/2023`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const especialidades = await response.json();

curl -X GET "${baseURL}/Medware/Especialidade/Listar?codUnidade=1&codMedico=123&codProcedimento=456&dataInicio=01/01/2023&dataFim=31/12/2023" \
  -H "Authorization: Bearer SEU_TOKEN"

// Listar especialidades
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(baseURL);
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = await client.GetAsync("Medware/Especialidade/Listar?codUnidade=1&codMedico=123&codProcedimento=456&dataInicio=01/01/2023&dataFim=31/12/2023");
  var especialidades = await response.Content.ReadAsAsync();
}

Pacientes

Criar/Atualizar Paciente

JavaScript

cURL

// Cadastrar paciente
const paciente = {
  nome: "Maria Oliveira",
  dataNascimento: "25/08/1990",
  email: "maria.oliveira@email.com",
  cpf: "98765432100",
  numeroCelularddd: "11",
  numeroCelular: "987654321"
};

const response = await fetch(`${baseURL}/Medware/Paciente/Atualizar`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(paciente)
});

const codPaciente = await response.json(); // Retorna o ID do paciente

curl -X PUT "${baseURL}/Medware/Paciente/Atualizar" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{"nome":"Maria Oliveira","dataNascimento":"25/08/1990","email":"maria.oliveira@email.com","cpf":"98765432100","numeroCelularddd":"11","numeroCelular":"987654321"}'

// Cadastrar paciente
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(baseURL);
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var paciente = new {
      nome = "Maria Oliveira",
      dataNascimento = "25/08/1990",
      email = "maria.oliveira@email.com",
      cpf = "98765432100",
      numeroCelularddd = "11",
      numeroCelular = "987654321"
  };
  
  var response = await client.PutAsJsonAsync("Medware/Paciente/Atualizar", paciente);
  var codPaciente = await response.Content.ReadAsAsync(); // Retorna o ID do paciente
}

Procedimentos

Listar Procedimentos

JavaScript

cURL

// Listar procedimentos
const response = await fetch(`${baseURL}/Medware/ProcedPlanoOp/Listar?codMedico=123&codPlano=456&codUnidade=789&dataInicio=01/01/2023&dataFim=31/12/2023`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const procedimentos = await response.json();

curl -X GET "${baseURL}/Medware/ProcedPlanoOp/Listar?codMedico=123&codPlano=456&codUnidade=789&dataInicio=01/01/2023&dataFim=31/12/2023" \
  -H "Authorization: Bearer SEU_TOKEN"

// Listar procedimentos
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(baseURL);
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = await client.GetAsync("Medware/ProcedPlanoOp/Listar?codMedico=123&codPlano=456&codUnidade=789&dataInicio=01/01/2023&dataFim=31/12/2023");
  var procedimentos = await response.Content.ReadAsAsync();
}

Dicas Importantes

Sempre inclua o token JWT no cabeçalho Authorization
Trate os erros adequadamente (status 400, 401, 404, etc.)
Implemente renovação automática do token quando estiver perto de expirar
Para produção, armazene credenciais de forma segura (não no código)
Formato de datas: dd/MM/yyyy para parâmetros de URL

Pré-requisito de Licença

Para finalizar um procedimento de agendamento pela API, a clínica deve ter a licença do AgendamentoWeb disponível.

Caso essa licença não esteja habilitada, entre em contato com o comercial da Medware ou com o responsável da clínica antes de seguir com a integração.

Configurações Internas no Clínicas

Para os valores aparecerem na API, algumas configurações devem ser feitas no módulo de bibliotecas do Clínicas, software desktop da Medware.

Agenda e Horários

No módulo Manutenção de Agendas, selecione a agenda que deve ter disponibilidade online. Na janela aberta, na seção Dados, marque a opção Agendamento Web.

Na seção Horários, use a opção Configurar Horário Web e selecione os horários que devem ficar disponíveis.

Médicos

No módulo Manutenção de Médicos, selecione o médico que deve ficar disponível para Agendamento Web. Na janela aberta, na seção Dados, marque a opção Agendamento Web.

Operadora e Plano

No módulo Manutenção de Operadoras, selecione a operadora do plano que deve ficar disponível no Agendamento Web. Acesse a seção Plano, selecione o plano de interesse e, na janela aberta, marque a opção Agendamento Web.

Procedimentos

No módulo Manutenção de Procedimentos, selecione o procedimento que deve ter disponibilidade online. Na janela aberta, na seção Dados, marque a opção Agendamento Web.

Visão Geral do Fluxo

O recurso Agendamento do controller Medware permite que sistemas externos realizem agendamentos de forma integrada. O fluxo completo segue a ordem abaixo — cada passo retorna códigos que serão usados no próximo:

Autenticação — obter o token principal da API
Paciente — usar um codPaciente já existente ou enviar os dados cadastrais no salvar
Operadora — listar operadoras disponíveis → obter codOperadora
Plano — listar planos da operadora → obter codPlano
Especialidade — listar especialidades → obter codEspecialidade
Unidade — listar unidades compatíveis → obter codUnidade
Médico — listar médicos disponíveis → obter codMedico
Procedimento — listar procedimentos → obter codProcedimento
Horários — listar slots disponíveis → obter codAgenda e dataHoraAgendada
Salvar Agendamento — confirmar o agendamento com todos os dados coletados

Importante

Os códigos obrigatórios obtidos nas etapas anteriores devem ser maiores que zero ao salvar. No endpoint /Medware/Agendamento/Salvar, envie codPaciente para paciente já cadastrado ou envie o objeto paciente para criar/identificar o cadastro antes de gravar o agendamento.

Passo 1 — Autenticação

Use o token principal da API. Obtenha-o pelo endpoint de login:

O valor retornado em token deve ser enviado como Bearer no header Authorization em todas as chamadas seguintes.

JavaScript

cURL

// Obter token principal
const response = await fetch(`${baseURL}/Acesso/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    identificacao: 'SEU_USUARIO',
    senha: 'SUA_SENHA',
    isHash: true
  })
});
const { token } = await response.json();

// Usar em todas as chamadas seguintes:
// Authorization: Bearer {token}

curl -X POST "${baseURL}/Acesso/login" \
  -H "Content-Type: application/json" \
  -d '{"identificacao":"SEU_USUARIO","senha":"SUA_SENHA"}'

using System.Net.Http.Json;

using var client = new HttpClient { BaseAddress = new Uri(baseURL) };

var response = await client.PostAsJsonAsync("Acesso/login", new {
    identificacao = "SEU_USUARIO",
    senha = "SUA_SENHA"
});

var result = await response.Content.ReadFromJsonAsync<dynamic>();
string token = result.token;

Token da API

Este fluxo usa o header padrão Authorization com o token principal da API.

Passo 2 — Identificação do Paciente

No fluxo de /Medware/Agendamento/Salvar, há duas opções: enviar somente codPaciente quando o paciente já existir, ou enviar os dados cadastrais no objeto paciente quando for necessário criar/identificar o cadastro.

A consulta abaixo é opcional, útil para localizar o paciente e obter o codPaciente antes de salvar.

JavaScript

cURL

const response = await fetch(`${baseURL}/Medware/Paciente/Listar?cpfPaciente=12345678900`, {
  headers: { 'Authorization': `Bearer ${token}` }
});

const paciente = await response.json();

curl -X GET "${baseURL}/Medware/Paciente/Listar?cpfPaciente=12345678900" \
  -H "Authorization: Bearer SEU_TOKEN"

using var client = new HttpClient { BaseAddress = new Uri(baseURL) };
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

var paciente = await client.GetFromJsonAsync<dynamic>(
    "Medware/Paciente/Listar?cpfPaciente=12345678900");

Se o paciente já existir

Envie o codPaciente na raiz do JSON. Nesse caso, os dados cadastrais do objeto paciente não são obrigatórios.

{
  "codPaciente": 1023
}

Se o paciente ainda não existir

Não há um passo separado obrigatório para criar o paciente antes do agendamento. Informe os dados mínimos no objeto paciente ao salvar o agendamento; a API cria o cadastro e retorna o CodPaciente junto com o CodAgendamento.

{
  "paciente": {
    "nome": "João da Silva",
    "dataNascimento": "1990-01-15",
    "cpf": "12345678901",
    "numeroCelularddd": "11",
    "numeroCelular": "987654321",
    "email": "joao@email.com",
    "sexo": "M"
  }
}

Campos mínimos

Para paciente existente, basta codPaciente. Para criação automática no agendamento, preencha pelo menos nome, dataNascimento, cpf, numeroCelularddd e numeroCelular.

Passos 3, 4 e 5 — Operadora, Plano e Especialidade

Liste as opções disponíveis usando os filtros que já possui. Os endpoints aceitam qualquer combinação de parâmetros — todos são opcionais:

JavaScript

cURL

const headers = { 'Authorization': `Bearer ${token}` };

const operadoras = await fetch(`${baseURL}/Medware/PlanoOperadora/Listar?codUnidade=1&codEspecialidade=5`, { headers })
  .then(r => r.json());

const planos = await fetch(`${baseURL}/Medware/Plano/Listar?codOperadora=2`, { headers })
  .then(r => r.json());

const especialidades = await fetch(`${baseURL}/Medware/Especialidade/Listar?codUnidade=1&codMedico=7`, { headers })
  .then(r => r.json());

curl -X GET "${baseURL}/Medware/PlanoOperadora/Listar?codUnidade=1&codEspecialidade=5" \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X GET "${baseURL}/Medware/Plano/Listar?codOperadora=2" \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X GET "${baseURL}/Medware/Especialidade/Listar?codUnidade=1&codMedico=7" \
  -H "Authorization: Bearer SEU_TOKEN"

using var client = new HttpClient { BaseAddress = new Uri(baseURL) };
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

var operadoras = await client.GetFromJsonAsync<dynamic>(
    "Medware/PlanoOperadora/Listar?codUnidade=1&codEspecialidade=5");
var planos = await client.GetFromJsonAsync<dynamic>(
    "Medware/Plano/Listar?codOperadora=2");
var especialidades = await client.GetFromJsonAsync<dynamic>(
    "Medware/Especialidade/Listar?codUnidade=1&codMedico=7");

Passos 6, 7 e 8 — Unidade, Médico e Procedimento

Refine os resultados combinando os códigos já obtidos:

JavaScript

cURL

const headers = { 'Authorization': `Bearer ${token}` };

const unidades = await fetch(`${baseURL}/Medware/Unidade/Listar?codPlanoOp=3&codEspecialidade=5`, { headers })
  .then(r => r.json());

const medicos = await fetch(`${baseURL}/Medware/Medico/Listar?codUnidade=1&codPlano=3&codEspecialidade=5`, { headers })
  .then(r => r.json());

const procedimentos = await fetch(`${baseURL}/Medware/ProcedPlanoOp/Listar?codPlano=3&codEspecialidade=5&codUnidade=1`, { headers })
  .then(r => r.json());

curl -X GET "${baseURL}/Medware/Unidade/Listar?codPlanoOp=3&codEspecialidade=5" \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X GET "${baseURL}/Medware/Medico/Listar?codUnidade=1&codPlano=3&codEspecialidade=5" \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X GET "${baseURL}/Medware/ProcedPlanoOp/Listar?codPlano=3&codEspecialidade=5&codUnidade=1" \
  -H "Authorization: Bearer SEU_TOKEN"

using var client = new HttpClient { BaseAddress = new Uri(baseURL) };
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

var unidades = await client.GetFromJsonAsync<dynamic>(
    "Medware/Unidade/Listar?codPlanoOp=3&codEspecialidade=5");
var medicos = await client.GetFromJsonAsync<dynamic>(
    "Medware/Medico/Listar?codUnidade=1&codPlano=3&codEspecialidade=5");
var procedimentos = await client.GetFromJsonAsync<dynamic>(
    "Medware/ProcedPlanoOp/Listar?codPlano=3&codEspecialidade=5&codUnidade=1");

Passo 9 — Buscar Horários Disponíveis

Com todos os dados definidos, liste os horários disponíveis. dataInicio, dataFim, horaInicio e horaFim são obrigatórios:

JavaScript

cURL

const url = `${baseURL}/Medware/Horarios/Listar?codMedico=7&codUnidade=1&codPlano=3&codEspecialidade=5&codProcedimento=15&dataInicio=10/06/2026&dataFim=17/06/2026&horaInicio=07:00:00&horaFim=18:00:00`;

const horarios = await fetch(url, {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

curl -X GET "${baseURL}/Medware/Horarios/Listar?codMedico=7&codUnidade=1&codPlano=3&codEspecialidade=5&codProcedimento=15&dataInicio=10/06/2026&dataFim=17/06/2026&horaInicio=07:00:00&horaFim=18:00:00" \
  -H "Authorization: Bearer SEU_TOKEN"

using var client = new HttpClient { BaseAddress = new Uri(baseURL) };
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

var horarios = await client.GetFromJsonAsync<dynamic>(
    "Medware/Horarios/Listar?codMedico=7&codUnidade=1&codPlano=3&codEspecialidade=5&codProcedimento=15&dataInicio=10/06/2026&dataFim=17/06/2026&horaInicio=07:00:00&horaFim=18:00:00");

O retorno inclui o codAgenda e a dataHoraAgendada de cada slot — guarde-os para o próximo passo.

Passo 10 — Salvar o Agendamento

Com todos os dados coletados, confirme o agendamento:

Campos obrigatórios do agendamento (devem ser > 0)

Campo	Descrição	Obtido em
`codAgenda`	Código da agenda do horário escolhido	Horarios/Listar
`codMedico`	Código do médico selecionado	Medico/Listar
`codProcedimento`	Código do procedimento escolhido	ProcedPlanoOp/Listar
`codPlano`	Código do plano selecionado	Plano/Listar
`dataHoraAgendada`	Data e hora do slot escolhido (yyyy-MM-ddTHH:mm:ss)	Horarios/Listar

Identificação do paciente (informe uma das opções)

Campo	Descrição	Quando usar
`codPaciente`	Código do paciente já cadastrado	Paciente existente. Não exige os dados cadastrais.
`paciente`	Dados mínimos do paciente: nome, dataNascimento, cpf, numeroCelularddd e numeroCelular	Paciente novo ou não identificado pelo sistema externo.

Campos opcionais ou recomendados

Campo	Descrição
`codUnidade`	Código da unidade selecionada. Quando informado, ajuda a validar a agenda escolhida.
`codEspecialidade`	Código da especialidade (recomendado quando disponível)

Exemplo de envio com paciente existente

JavaScript

cURL

const agendamento = {
  codAgenda: 142,
  codMedico: 7,
  codPaciente: 1023,
  codProcedimento: 15,
  codPlano: 3,
  codUnidade: 1,
  codEspecialidade: 5,
  dataHoraAgendada: "2026-06-10T09:30:00"
};

const resultado = await fetch(`${baseURL}/Medware/Agendamento/Salvar`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(agendamento)
}).then(r => r.json());

curl -X POST "${baseURL}/Medware/Agendamento/Salvar" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{"codAgenda":142,"codMedico":7,"codPaciente":1023,"codProcedimento":15,"codPlano":3,"codUnidade":1,"codEspecialidade":5,"dataHoraAgendada":"2026-06-10T09:30:00"}'

using var client = new HttpClient { BaseAddress = new Uri(baseURL) };
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

var agendamento = new {
    codAgenda = 142,
    codMedico = 7,
    codPaciente = 1023,
    codProcedimento = 15,
    codPlano = 3,
    codUnidade = 1,
    codEspecialidade = 5,
    dataHoraAgendada = "2026-06-10T09:30:00"
};

var response = await client.PostAsJsonAsync("Medware/Agendamento/Salvar", agendamento);
var resultado = await response.Content.ReadFromJsonAsync<dynamic>();

Exemplo de envio criando/identificando paciente

{
  "codAgenda": 142,
  "codMedico": 7,
  "codProcedimento": 15,
  "codPlano": 3,
  "codUnidade": 1,
  "codEspecialidade": 5,
  "dataHoraAgendada": "2026-06-10T09:30:00",
  "paciente": {
    "nome": "João da Silva",
    "dataNascimento": "1990-01-15",
    "cpf": "12345678901",
    "email": "joao@email.com",
    "sexo": "M",
    "numeroCelularddd": "11",
    "numeroCelular": "987654321"
  }
}

Respostas possíveis

Resultado	Significado
`"OK, Agendamento concluído."`	Sucesso — retorna `CodAgendamento` e `CodPaciente`
`"LIMITADO"`	Horário bloqueado por restrições de agenda (plano, procedimento ou paciente)
`"ERROR"`	Horário não disponível ou dado inválido — verifique a mensagem de erro retornada

Dicas

Sempre percorra o fluxo na ordem correta — horários dependem de médico, unidade e plano já definidos
Nunca envie 0 nos campos obrigatórios: isso indica que o passo anterior não foi concluído
Use o token principal da API obtido em /Acesso/login
Datas nos filtros: formato dd/MM/yyyy. Data de agendamento ao salvar: formato yyyy-MM-ddTHH:mm:ss

Visão Geral do Fluxo

O MedwareWebHookController recebe retornos de integrações externas para gravar confirmações de agendamento e avaliações no Medware. O endpoint tambem fica disponivel na lista do Swagger para consulta tecnica.

Configurar token - definir o token de WebHook da API Medware
Identificar registros - enviar codigoExterno ou codAgendamento
Informar método - escolher confirmacao ou avaliacao
Enviar resposta - informar o valor retornado pela integração
Processar retorno - o Medware atualiza status ou grava a avaliação recebida

Importante

Envie um dos identificadores aceitos. Quando codigoExterno estiver preenchido, ele tem prioridade; caso contrário, o fluxo tenta usar codAgendamento.

Ambiente local do cliente

Cada aplicação Medware é executada no ambiente local do cliente e depende do DNS configurado para esse cliente. A URL do WebHook exibida nesta documentação usa a aplicação atual e deve ser usada somente para a instalação correspondente.

Automação do Paciente Conectado

Ao utilizar a automação no Paciente Conectado, as respostas de confirmação, avaliação, reagendamento ou cancelamento devem ser enviadas pelo WebHook configurado para a aplicação do cliente.

Endpoint Principal

Use o endpoint principal para integrações que enviam JSON. O token configurado na API deve ser enviado no header TokenWebHook.

Rota: POST /MedwareWebHook/MedwareWebHook
URL:
Header obrigatório: TokenWebHook ou tokenwebhook
Configuração da API: ConnectionStrings:TokenWebHook
Resposta esperada: true quando o processamento concluir sem falha de atualização

Confirmação de Agendamento

Para retorno de confirmação, envie metodo igual a confirmacao. Os códigos podem vir separados por vírgula para processar mais de um registro.

Payload

cURL

{
  "codigoExterno": "1001,1002",
  "metodo": "confirmacao",
  "resposta": "SIM"
}

curl -X POST "${baseURL}/MedwareWebHook/MedwareWebHook" \
  -H "Content-Type: application/json" \
  -H "TokenWebHook: SEU_TOKEN_WEBHOOK" \
  -d '{"codigoExterno":"1001,1002","metodo":"confirmacao","resposta":"SIM"}'

Com codigoExterno, o status é atualizado pelo código externo. Com codAgendamento, o status é atualizado pelo código do agendamento.

Avaliação

Para retorno de pesquisa, envie metodo igual a avaliacao. A resposta é convertida para número antes de gravar a avaliação.

{
  "codAgendamento": "12345",
  "metodo": "avaliacao",
  "resposta": "5"
}

codigoExterno e codAgendamento aceitam lista separada por vírgula
metodo diferente de confirmacao ou avaliacao retorna erro
O body enviado e o resultado do processamento são registrados no log de resposta

Estes módulos são telas do cliente que consomem endpoints da API Medware. As URLs abaixo usam o domínio atual do cliente.

CodAgendamento para links de teste

Não autorizado

Para Confirmação e NPS, informe um CodAgendamento real do cliente e clique em Atualizar links. O valor padrão gera um hash de teste, mas só exibirá dados se esse agendamento existir.

Módulo	Como funciona	Acessar
Agendamento	Permite que o paciente faça o próprio agendamento pela internet, seguindo as etapas configuradas pela clínica, como identificação, escolha de atendimento, unidade, convênio, profissional e horário disponível.	Abrir
Confirmação	Permite que o paciente confirme ou cancele um agendamento a partir de um link seguro enviado pela clínica. Precisa de hash no link para abrir os dados corretos.	Abrir
NPS	Exibe a pesquisa de satisfação vinculada ao atendimento do paciente. Precisa de hash após a rota para identificar o agendamento e evitar respostas duplicadas.	Abrir
Validação	Permite validar documentos assinados digitalmente por código ou QR Code, exibindo os dados da assinatura e os arquivos vinculados quando o código é válido.	Abrir

Hash nos links

Os módulos Confirmação e NPS não devem abrir apenas pela rota base. O hash é gerado a partir do CodAgendamento usando a mesma criptografia AES do endpoint /Medware/Avaliacao/GerarLink, permitindo testar com um agendamento real sem criar endpoint adicional.

O que é o MCP?

O MCP (Model Context Protocol) é um protocolo aberto que permite que assistentes de IA, como ChatGPT, Claude, Cursor, Windsurf e outros clientes compatíveis, descubram e utilizem recursos disponibilizados por sistemas externos de forma padronizada.

No Medware, o MCP expõe funcionalidades da API como ferramentas (tools) que podem ser utilizadas diretamente por agentes de IA para consultar informações, executar ações e integrar fluxos clínicos sem necessidade de implementação específica para cada fornecedor de IA.

Como funciona

O fluxo básico é:

Conectar - o cliente MCP estabelece conexão com o servidor MCP do Medware.
Listar ferramentas - o cliente solicita a lista de ferramentas disponíveis.
Selecionar ferramenta - o modelo de IA identifica qual ferramenta pode responder à solicitação do usuário.
Executar - o cliente executa a ferramenta enviando os parâmetros necessários.
Processar - o Medware processa a requisição e retorna o resultado estruturado.
Responder - o modelo utiliza a resposta para compor a resposta final ao usuário.

Exemplo

Usuário: Quais exames o paciente João Silva realizou nos últimos 30 dias?

O modelo identifica a ferramenta ConsultarExamesPaciente.
A ferramenta é executada via MCP.
O Medware retorna os exames encontrados.
O modelo gera a resposta para o usuário utilizando os dados retornados.

Arquitetura de comunicação

O Medware utiliza o transporte SSE (Server-Sent Events), recomendado pela especificação MCP. O cliente mantém uma conexão persistente com o servidor através do endpoint SSE e envia mensagens JSON-RPC para execução das ferramentas.

Endpoints MCP

Endpoint	Finalidade
`GET {URL_DA_API}/mcp/sse`	Abre o canal SSE utilizado pelo cliente MCP.
`POST {URL_DA_API}/mcp/message`	Recebe mensagens JSON-RPC enviadas pelo cliente.
`GET {URL_DA_API}/mcp/tools`	Permite consultar as ferramentas MCP publicadas pela API.

URL da aplicação

Utilize a mesma URL pública usada para acesso à API Medware, como https://api.clinica.com.br ou https://medware.suaclinica.com.br.

Caso a instalação utilize publicação por DNS, proxy reverso ou túnel seguro, os endpoints MCP devem utilizar o mesmo endereço público.

Descoberta de ferramentas

As ferramentas disponíveis podem ser consultadas através do endpoint:

GET {URL_DA_API}/mcp/tools

O retorno contém:

Nome da ferramenta
Descrição
Parâmetros aceitos
Tipos de dados
Campos obrigatórios

Essas informações são utilizadas automaticamente pelos clientes MCP para que o modelo saiba quais recursos estão disponíveis.

Autenticação

O servidor MCP utiliza os mesmos mecanismos de autenticação da API Medware.

Opção 1 - Bearer Token

Envie o token JWT no cabeçalho Authorization:

Authorization: Bearer SEU_TOKEN

Essa é a forma mais simples para testes e integrações internas.

Opção 2 - OAuth 2.1

Para clientes MCP que suportam autenticação OAuth, o Medware disponibiliza os endpoints padronizados para descoberta, registro e autorização.

Operação	Endpoint
Descoberta do servidor	`GET {URL_DA_API}/.well-known/oauth-authorization-server`
Metadados do recurso protegido	`GET {URL_DA_API}/.well-known/oauth-protected-resource`
Registro dinâmico do cliente	`POST {URL_DA_API}/auth/register`
Autorização	`GET {URL_DA_API}/auth/authorize`
Token	`POST {URL_DA_API}/auth/token`

Fluxo resumido:

O cliente registra-se no servidor.
O usuário autoriza o acesso.
O cliente recebe um authorization code.
O código é trocado por um access token.
O token é utilizado nas chamadas MCP.

Exemplo de configuração

SSE Endpoint	`https://api.clinica.com.br/mcp/sse`
Header de autenticação	`Authorization: Bearer eyJhbGciOi...`

Testando com MCP Inspector

O MCP Inspector é uma ferramenta oficial para validação e testes de servidores MCP. A documentação oficial está disponível em modelcontextprotocol.io/docs/tools/inspector .

Campo	Valor
Transport	SSE
URL	`{URL_DA_API}/mcp/sse`
Authorization	Bearer Token (opcional)

Após conectar:

Clique em List Tools.
Verifique as ferramentas disponíveis.
Execute uma ferramenta.
Analise a resposta retornada pelo servidor.

Onde a API fica instalada

A API Medware é uma aplicação instalada no servidor da clínica. Por isso, a disponibilidade do serviço depende diretamente da infraestrutura local da clínica, incluindo internet, energia elétrica, equipamento, sistema operacional, rede interna e configurações de segurança.

Responsabilidade da infraestrutura

Instabilidade de internet, queda de energia, desligamento do servidor, bloqueio de porta, falha no equipamento ou alteração de rede podem deixar a API indisponível externamente.

Requisitos mínimos

Item	Exigência
Sistema operacional	Compatível com .NET 8 e Node.js 24.
Servidor	Equipamento dedicado ou ambiente estável para manter a API em execução.
Rede	Conexão de internet estável e liberação da porta configurada para a API.

Opções de publicação

Opção	Configuração necessária	Observação
DNS via túnel	A clínica precisa ter um DNS apontando para `tunel.medware.com.br`.	Opção recomendada quando a publicação direta do servidor não é desejada ou não é viável.
DNS / IP fixo direto	O DNS ou IP fixo deve ser direcionado para o servidor onde a API está instalada, respeitando a porta configurada.	IP fixo sozinho não cria certificado de segurança. Para HTTPS é necessário configurar domínio e certificado válido.

Segurança

Para acesso externo seguro, a clínica deve usar HTTPS com certificado válido. Quando a publicação for feita por IP fixo direto, o certificado não é criado automaticamente apenas por existir um IP público.

Retorno da automação

Ao utilizar a automação no Paciente Conectado, as respostas de confirmação, avaliação, reagendamento ou cancelamento devem ser enviadas pelo WebHook da aplicação publicada no DNS do cliente.

Dúvidas Comuns

Autenticação e Segurança

Como obtenho minhas credenciais de acesso?

As credenciais são fornecidas após a aprovação do cadastro como desenvolvedor. Entre em contato com nosso suporte técnico para solicitar acesso.

Quanto tempo um token JWT permanece válido?

Por padrão, o token principal da API permanece válido por 24 horas. Esse tempo pode ser personalizado por cliente pela configuração TokenLifetimeMinutes; no código atual não há um teto máximo fixo além do valor configurado. Recomendamos implementar renovação automática antes da expiração.

Posso usar o mesmo token para múltiplas requisições?

Sim, até sua expiração. Porém, para maior segurança, recomendamos gerar novos tokens periodicamente.

Erros e Soluções

Como tratar erros de validação (status 400)?

Erros 400 incluem detalhes dos campos inválidos no corpo da resposta. Sempre verifique a estrutura de erro:

{
  "error": "ValidationError",
  "message": "Dados inválidos",
  "details": [
      {
          "field": "email",
          "message": "Deve ser um email válido"
      }
  ]
}

O que significa o erro 503 (Service Unavailable)?

Indica que nosso serviço está temporariamente indisponível.

Suporte

Como reportar um problema?

Para problemas técnicos, abra um ticket em nosso WhatsApp incluindo: Também é possível acionar o suporte pelo telefone 61 33016575 ou pelo e-mail suporte@medware.com.br.

Endpoint acessado
Parâmetros utilizados
Token de requisição (sem o valor real)
Logs de erro (se aplicável)

Documentação da API Medware

Bem-vindo à documentação da API Medware, uma ferramenta para facilitar a gestão de agendamentos e informações médicas. Nossa API oferece um conjunto abrangente de endpoints que permitem:

Autenticação segura com tokens JWT
Gestão completa de agendamentos médicos com consulta de horários disponíveis
Acesso ao catálogo de médicos e especialidades disponíveis em todas as unidades
Cadastro e atualização de pacientes de forma simples e rápida
Consulta de procedimentos por médico, plano, unidade e especialidade
Obtenção de resultados em formato PDF
Avaliação de atendimento com geração de links para pesquisa de satisfação

REST API

Versão Estável

Atualizado: 01/06/2026

Início Rápido

Comece rapidamente com exemplos de código prontos para uso.

Ver guia

Autenticação

Aprenda a autenticar suas requisições com nossa API.

Ver guia

Como agendar?

Entenda o fluxo completo, usando codPaciente para pacientes existentes ou dados cadastrais para novos pacientes.

Ver guia

Webhook de Integração

Envie confirmações e avaliações de sistemas externos para o Medware.

Ver guia

MCP

Conecte clientes MCP por SSE direto e autentique com Bearer token ou OAuth.

Ver guia

Teste Webhook

Envie um retorno de confirmação ou avaliação com o token da integração.

Abrir teste

Teste de Agendamento

Execute o fluxo público do MedwareController e valide o payload com codPaciente ou dados do paciente.

Abrir teste

Teste Confirmação Agendamento

Liste agendamentos pendentes de um período e processe a alteração de status.

Abrir teste

Módulos da API

Veja as telas públicas e operacionais que consomem a API.

Ver módulos

Forma de Conexão

Entenda os requisitos de infraestrutura e as opções de DNS para publicar a API.

Ver conexão

Autenticação

AUTH /Acesso/login Configuração do Bearer token

Senha

Token JWT

Digite 'Bearer' [espaço] e, em seguida, seu token na entrada de texto.

Teste Confirmação Agendamento

Liste agendamentos com status Agendado em um periodo e processe a alteracao de status para confirmar, cancelar ou marcar como recebido.

MedwareController

Login

POST /Acesso/login

Identificacao

Senha

Payload / Requisicao

{}

Resposta / Erro

{}

1. Listar agendamentos

GET /Medware/Agendamento/Listar

Data inicio (*)

Data fim (*)

Status listado

Agendamento escolhido (*)

Payload / Requisicao

{}

Resposta / Erro

{}

2. Processar status

PUT /Medware/Agendamento/Status

Novo status (*)

Payload / Requisicao

{}

Resposta / Erro

{}

Informacoes

Propriedades com (*) sao obrigatorias. A API retorna true ou false.

Codigos de status: 0 Cancelado pelo centro, 1 Agendado, 2 Confirmado, 3 Recebido, 4 Atendido, 5 Liberado, 6 Faltou, 7 Suspenso, 8 Reagendado, 9 Faltou Sessão.

Status customizados sao a partir do codigo 10.

Teste Webhook

Envie um retorno pela integração Medware usando o token exclusivo do WebHook.

MedwareWebHookController

Uso do body

Para reproduzir o retorno em integrações externas, considere apenas o conteúdo do body exibido no payload. URL e headers são informações auxiliares do teste.

Token da integração

Header TokenWebHook

TokenWebHook (*)

Este token não é o Bearer token do Swagger. Ele é enviado somente no header TokenWebHook.

Enviar retorno

POST /MedwareWebHook/MedwareWebHook

Identificador (*)

Código (*)

Método (*)

Resposta (*)

Payload / Requisição

{}

Resposta / Erro

{}

Informações

Propriedades com (*) são obrigatórias. O teste envia um código numérico por requisição.

Use confirmacao para atualizar status e avaliacao para registrar a nota recebida.

Medware WebApi

Documentação

Documentação da API Medware

Início Rápido

Autenticação

Como agendar?

Webhook de Integração

MCP

Teste Webhook

Teste de Agendamento

Teste Confirmação Agendamento

Módulos da API

Forma de Conexão

Autenticação

Recursos da API

Documentação

Introdução