API de Integração

https://app.clinplus.com.br/api/pub/v1

Toda chamada precisa do header Authorization: Bearer <token>. O token é criado pela clínica em Configurações → API / Integrações, com os escopos (módulos) que ele pode acessar.

curl https://app.clinplus.com.br/api/pub/v1/ping \
  -H "Authorization: Bearer SEU_TOKEN"

Feito pra IA / Agentes

Conecte seu bot/assistente em minutos: os endpoints são orientados a intenção e a API é auto-descritível.

Cadastre uma URL em Configurações → API e receba POST assinado quando um agendamento muda (agendamento.criado, .confirmado, .cancelado, .concluido). Valide com X-ClinPlus-Signature: sha256=<hmac>.

Mande o header Idempotency-Key: <único> nos POST — se o agente repetir a chamada, devolvemos o mesmo resultado (não cria dois agendamentos). Em conflito de horário, o erro já traz os proximos_horarios livres.

Lista os médicos/profissionais ativos (filtra por especialidade).

{
  "data": [
    { "id": 36, "nome": "Dr. Roberto Lima", "especialidade": "cardiologia", "crm": "41023 SP" }
  ],
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Lista as especialidades.

{
  "data": [ { "id": 4, "titulo": "Cardiologia", "cbo": "2251-21" } ],
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Lista os convênios.

{
  "data": [ { "id": 29, "titulo": "Bradesco Saúde", "registro_ans": "005711" } ],
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Catálogo de procedimentos (serviços/exames) com preparo e valor particular. Filtre por nome/TUSS (q=) e por tipo (servico|exame). Também em /catalogos/procedimentos/pesquisa?q=.

{
  "data": [
    {
      "id": 181, "nome": "Ultrassom Abdominal", "tipo": "exame",
      "tuss_codigo": "40901114", "tuss_tabela": "22",
      "preparo": "Jejum de 8 horas. Beber 1L de água 1h antes.",
      "valor_particular": 150.00, "duracao_min": 30, "descricao": null
    }
  ],
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Diz se um convênio/plano cobre um procedimento (há tabela de preço cadastrada). convenio aceita id ou nome; procedimento aceita código TUSS ou nome.

{"convenio":"Bradesco Saúde","plano":"Top Nacional","procedimento":"Consulta"}

{
  "data": {
    "aceito": true,
    "motivo": "Procedimento coberto — há tabela de preço cadastrada para este convênio/plano.",
    "convenio": { "id": 29, "titulo": "Bradesco Saúde" },
    "plano": "Top Nacional",
    "procedimento": "Consulta em consultório",
    "tuss": "10101012",
    "valor": 120.00
  },
  "meta": { "request_id": "…", "version": "v1" }
}
// aceito=false quando não há tabela de preço; motivo explica (convênio inativo, sem tabela, etc.).

Testar no playground

Lista as unidades/clínicas.

{
  "data": [ { "id": 1, "nome": "Clínica Viver Bem — Matriz", "sigla": "MATRIZ", "cidade": null, "uf": null } ],
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Agendamentos de um dia.

{
  "data": {
    "data": "2026-08-28",
    "agendamentos": [
      {
        "id": 917,
        "inicio": "2026-08-28T09:15:00-03:00",
        "fim": "2026-08-28T09:45:00-03:00",
        "status": "concluido",
        "titulo": "Consulta cardiológica",
        "descricao": null,
        "paciente": {
          "id": 2056, "nome": "Maria Silva", "telefone": "11900000001",
          "cpf": null, "nascimento": null, "email": "maria@ex.com", "sexo": "feminino"
        },
        "profissional": {
          "id": 36, "nome": "Dr. Roberto Lima", "conselho": "41023/SP", "especialidade": "cardiologia"
        },
        "convenio": { "id": 29, "nome": "Bradesco Saúde" },
        "procedimentos": [
          {
            "item_id": 181, "nome": "Ultrassom Abdominal", "tipo": "exame",
            "tuss_codigo": "40901114", "tuss_tabela": "22", "quantidade": 1,
            "preparo": "Jejum de 8 horas. Beber 1L de água 1h antes."
          }
        ],
        "preparo": "Jejum de 8 horas. Beber 1L de água 1h antes."
      }
    ]
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Horários livres de um profissional num dia.

{
  "data": {
    "data": "2026-09-01",
    "slots": [
      { "hora": "07:00", "disponivel": true, "motivo": null },
      { "hora": "07:45", "disponivel": false, "motivo": "ocupado" }
    ]
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Próximos dias com vaga.

{
  "data": {
    "dias": [
      { "data": "2026-08-29", "dia_semana": 6, "disponiveis": 16 },
      { "data": "2026-08-30", "dia_semana": 0, "disponiveis": 16 }
    ]
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

PRÓXIMO horário livre — varre os profissionais (por especialidade ou todos). Ideal pra IA.

{
  "data": {
    "disponivel": true,
    "proximo": {
      "data": "2026-08-28", "hora": "17:30", "inicio": "2026-08-28T17:30:00-03:00",
      "profissional": { "id": 36, "nome": "Dr. Roberto Lima" }
    }
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Busca horários por vários critérios de uma vez: especialidades (csv), dias_semana (0=dom…6=sáb, csv), turno (manha|tarde|noite), de e dias. Reduz o nº de chamadas.

{
  "data": {
    "total": 2,
    "resultados": [
      {
        "data": "2026-09-02", "hora": "07:00", "inicio": "2026-09-02T07:00:00-03:00",
        "profissional": { "id": 36, "nome": "Dr. Roberto Lima", "especialidade": "cardiologia" }
      },
      {
        "data": "2026-09-02", "hora": "07:45", "inicio": "2026-09-02T07:45:00-03:00",
        "profissional": { "id": 36, "nome": "Dr. Roberto Lima", "especialidade": "cardiologia" }
      }
    ]
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Detalhe de um agendamento.

{
  "data": {
    "id": 917,
    "inicio": "2026-08-28T09:15:00-03:00",
    "fim": "2026-08-28T09:45:00-03:00",
    "status": "concluido",
    "titulo": "Consulta cardiológica",
    "descricao": null,
    "paciente": { "id": 2056, "nome": "Maria Silva", "telefone": "11900000001", "cpf": null, "nascimento": null, "email": null, "sexo": "feminino" },
    "profissional": { "id": 36, "nome": "Dr. Roberto Lima", "conselho": "41023/SP", "especialidade": "cardiologia" },
    "convenio": { "id": 29, "nome": "Bradesco Saúde" },
    "procedimentos": [ { "item_id": 181, "nome": "Ultrassom Abdominal", "tipo": "exame", "tuss_codigo": "40901114", "tuss_tabela": "22", "quantidade": 1, "preparo": "Jejum de 8 horas." } ],
    "preparo": "Jejum de 8 horas."
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Cria um agendamento. convenio_id ausente/null = PARTICULAR. tipo_atendimento = consulta|retorno. procedimentos = ids do catálogo (ou {item_id,qtd}).

{"cliente_id":193,"profissional_id":36,"titulo":"Consulta","inicio":"2026-08-28T14:00:00","fim":null,"tipo_atendimento":"consulta","convenio_id":null,"procedimentos":[181],"descricao":null,"notificar":true}

{
  "data": {
    "id": 940, "status": "agendado", "inicio": "2026-08-28T14:00:00-03:00", "fim": "2026-08-28T15:00:00-03:00",
    "paciente": { "id": 193, "nome": "Maria Silva" }, "profissional": { "id": 36, "nome": "Dr. Roberto Lima" }
  },
  "meta": { "request_id": "…", "version": "v1" }
}
// HTTP 201. Em conflito de horário: HTTP 409 com error.details.proximos_horarios[].

Testar no playground

RESOLVE-ou-CRIA o paciente (telefone/CPF) e agenda numa tacada. Ideal pra bot de WhatsApp.

{"telefone":"11999998888","nome":"Maria Silva","profissional_id":36,"titulo":"Consulta","inicio":"2026-08-28T14:00:00"}

{
  "data": {
    "id": 941, "status": "agendado", "inicio": "2026-08-28T14:00:00-03:00",
    "paciente": { "id": 2058, "nome": "Maria Silva", "ja_existia": false }
  },
  "meta": { "request_id": "…", "version": "v1" }
}
// HTTP 201. Resolve-ou-cria o paciente pelo telefone/CPF e agenda.

Testar no playground

Reagendamento ATÔMICO: move a mesma reserva para outro horário; só muda se a nova vaga estiver livre (senão 409 e o original fica intacto). fim é opcional (mantém a duração).

{"inicio":"2026-08-29T15:00:00","fim":null}

{
  "data": {
    "id": 917, "status": "agendado",
    "inicio": "2026-08-29T15:00:00-03:00", "fim": "2026-08-29T16:00:00-03:00",
    "tipo_atendimento": "retorno",
    "paciente": { "id": 2056, "nome": "Maria Silva" },
    "profissional": { "id": 36, "nome": "Dr. Roberto Lima" }
  },
  "meta": { "request_id": "…", "version": "v1" }
}
// HTTP 409 se a nova vaga estiver ocupada (o agendamento original permanece intacto).

Testar no playground

Cancela um agendamento.

{"motivo":"Paciente remarcou"}

{
  "data": { "id": 917, "status": "cancelado" },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Busca pacientes por nome, telefone ou CPF.

{
  "data": [
    { "id": 2056, "nome": "Maria Silva", "telefone": "11900000001", "cpf": null, "nascimento": null, "sexo": "feminino", "email": null, "pre_cadastro": false }
  ],
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Acha o paciente pelo telefone (o bot já tem o número).

{
  "data": { "id": 2057, "nome": "Maria Silva", "telefone": "11900000002", "cpf": null, "nascimento": null, "sexo": "feminino", "email": "maria@ex.com", "pre_cadastro": false },
  "meta": { "request_id": "…", "version": "v1" }
}
// HTTP 404 quando não encontra.

Testar no playground

Acha o paciente pelo CPF.

{
  "data": { "id": 2057, "nome": "Maria Silva", "telefone": "11900000002", "cpf": "12345678900", "nascimento": "1985-10-01", "sexo": "feminino", "email": null, "pre_cadastro": false },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Paciente + próximos agendamentos numa única chamada (por telefone). Economiza 2 requisições.

{
  "data": {
    "paciente": { "id": 2057, "nome": "Maria Silva", "telefone": "11999998888", "cpf": null, "nascimento": null, "sexo": "feminino", "email": null, "pre_cadastro": false },
    "proximos_agendamentos": [
      { "id": 918, "inicio": "2026-08-29T09:00:00-03:00", "fim": "2026-08-29T09:30:00-03:00", "status": "agendado", "titulo": "Retorno", "tipo_atendimento": "retorno", "profissional": "Dr. Roberto Lima" }
    ]
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Detalhe de um paciente.

{
  "data": { "id": 2057, "nome": "Maria Silva", "telefone": "11900000002", "cpf": null, "nascimento": null, "sexo": "feminino", "email": null, "pre_cadastro": false },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Agendamentos de um paciente.

{
  "data": {
    "agendamentos": [
      { "id": 918, "inicio": "2026-08-28T09:20:00-03:00", "fim": "2026-08-28T09:50:00-03:00", "status": "concluido", "titulo": "Retorno", "profissional": "Dr. Roberto Lima" }
    ]
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Cadastra um paciente.

{"nome":"Maria Silva","telefone":"11999998888","cpf":null,"nascimento":null,"sexo":"feminino","whatsapp":true}

{
  "data": { "id": 2058, "nome": "Maria Silva", "telefone": "11955554444", "cpf": null, "nascimento": null, "sexo": "feminino", "email": null, "pre_cadastro": true, "ja_existia": false },
  "meta": { "request_id": "…", "version": "v1" }
}
// ja_existia=true quando o telefone/CPF já era de um paciente (não duplica).

Testar no playground

Agendamentos que ainda precisam de lembrete.

{
  "data": {
    "janela_horas": 24,
    "total": 1,
    "pendentes": [
      { "agendamento_id": 918, "paciente": "Maria Silva", "telefone": "11900000002", "inicio": "2026-08-29T09:00:00-03:00", "profissional": "Dr. Roberto Lima" }
    ]
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Dispara o lembrete por WhatsApp.

{
  "data": { "agendamento_id": 918, "enviado": true, "canal": "whatsapp" },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Saldo do dia, entradas e saídas (para responder "quanto entrou hoje?"). Opcional data=YYYY-MM-DD.

{
  "data": {
    "data": "2026-09-18", "entradas_dia": 1850.00, "saidas_dia": 420.50,
    "saldo_dia": 1429.50, "saldo_total": 38210.75
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Resumo proativo pronto pra enviar (saldo + contas a vencer/vencidas + inadimplência + insight de IA). Traz um campo "mensagem" já formatado. Agende no Flagy (ex.: 19h).

Testar no playground

Lançamentos acima do limite aguardando aprovação de um admin.

Testar no playground

Aprova (grava) ou rejeita um lançamento que ficou acima do limite.

{"token":"<do preview>","aprovado":true}

Testar no playground

Comprovante por foto: a IA lê a imagem (imagem_url hospedada pelo Flagy), extrai a despesa e devolve o resumo pra confirmar (mesmo /confirmar).

{"telefone":"11999998888","imagem_url":"https://.../nota.jpg"}

Testar no playground

Gera um relatório em PDF sob demanda (hoje: DRE do mês) e devolve um link efêmero pra enviar como documento.

Testar no playground

Passo 1: confere a whitelist do número, a IA interpreta o texto e devolve o resumo pra confirmar (ou opções quando o paciente é ambíguo). NÃO grava ainda.

{"telefone":"11999998888","texto":"lançar despesa de cartucho de impressora, 45 reais","sid":"wamid-123"}

{
  "data": {
    "status": "confirmar",
    "token": "4d7b7f1adeb1aba22c9779205a80d4d2",
    "resumo": "Vou lançar SAÍDA de R$ 45,00 — Cartucho de impressora · categoria Materiais. Confirma? Responda SIM.",
    "lancamento": { "tipo": "saida", "valor": 45, "descricao": "Cartucho de impressora", "data": "2026-09-18" }
  },
  "meta": { "request_id": "…", "version": "v1" }
}
// status pode ser: confirmar | ambiguo (traz opcoes[] de pacientes) | incompleto (pergunta) | limite | sem_permissao.

Testar no playground

Passo 2: com o token do preview (e opcao_id se houver ambiguidade de paciente), grava o lançamento em entradas/saídas.

{"token":"<do preview>","opcao_id":null}

{
  "data": {
    "status": "lancado",
    "comprovante": "✅ Saída de R$ 45,00 lançada — Cartucho de impressora. (a revisar no sistema)",
    "lancamento_id": 12488
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Cancela um lançamento pendente (resposta NÃO).

{"token":"<do preview>"}

Testar no playground

Colunas do funil (id/nome/categoria) — use pra mapear o estágio.

{
  "data": {
    "estagios": [
      { "id": 12, "nome": "Novo", "cor": "#2563eb", "ordem": 1, "categoria": "inicial" },
      { "id": 13, "nome": "Em contato", "cor": "#f59e0b", "ordem": 2, "categoria": "andamento" },
      { "id": 16, "nome": "Fechado (ganho)", "cor": "#10b981", "ordem": 5, "categoria": "ganho" }
    ]
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Lista leads do funil. Filtre por texto (q=), estágio ou origem.

Testar no playground

Acha o lead mais recente pelo telefone (dedup).

{
  "data": {
    "id": 842, "nome": "Maria Silva", "telefone": "11999998888",
    "origem": "campanha", "score": 65, "ref_externa": "flagy-lead-8842",
    "estagio": { "id": 12, "nome": "Novo", "categoria": "inicial" }
  },
  "meta": { "request_id": "…", "version": "v1" }
}

Testar no playground

Detalhe de um lead.

Testar no playground

Cria OU atualiza (upsert) um lead capturado. Casa por ref_externa (id da sua ferramenta) ou telefone; senão cria. Idempotente. Dispara o webhook lead.criado.

{"nome":"Maria Silva","telefone":"11999998888","email":null,"origem":"campanha","interesse":"Ortodontia","valor_estimado":1500,"ref_externa":"flagy-lead-8842"}

{
  "data": {
    "id": 842, "nome": "Maria Silva", "telefone": "11999998888", "email": null,
    "origem": "campanha", "interesse": "Ortodontia", "valor_estimado": 1500.00, "score": 65,
    "ref_externa": "flagy-lead-8842", "cliente_id": null, "convertido_em": null,
    "estagio": { "id": 12, "nome": "Novo", "categoria": "inicial" },
    "ja_existia": false
  },
  "meta": { "request_id": "…", "version": "v1" }
}
// ja_existia=true (HTTP 200) quando casou por ref_externa ou telefone e atualizou o lead existente.

Testar no playground

Testa o token e devolve os escopos dele.

{
  "data": {
    "ok": true,
    "clinica": "Clínica Viver Bem",
    "token": "Bot WhatsApp",
    "escopos": ["agendamentos:ler", "pacientes:ler", "lembretes:enviar"],
    "agora": "2026-08-28T17:12:34-03:00"
  }
}

Testar no playground