Requisitos de API - Integração Sistema de Agendamento

Objetivo deste documento: Descrever todas as informações, endpoints e campos que o software de agendamento e prontuário médico da clínica deve fornecer via API para integrar com o chatbot IA do Kommo CRM, permitindo agendamento automatizado 24h via WhatsApp.

Arquitetura do Fluxo

Paciente (WhatsApp)

Envia mensagem solicitando agendamento

Kommo AI Agent (Chatbot)

Identifica intenção, coleta dados do paciente

Cloudflare Worker (Middleware)

Ponte entre Kommo e sistema externo

API do Sistema de Agendamento

Consulta disponibilidade, cria/edita/cancela agendamentos

Calendário Nativo do Kommo

Agendamento refletido na agenda do médico

Por que o Cloudflare Worker e necessário?

O AI Agent do Kommo não faz chamadas HTTP diretas a APIs externas
O Worker recebe webhooks do Kommo, consulta a API externa e devolve a resposta
O Worker também cria o booking no calendário nativo do Kommo via API
Atua como camada de segurança, validação e transformação de dados

1

Requisitos de Infraestrutura da API

1.1 Informações Básicas

Item	Descrição	Exemplo
URL base da API	Endereço raiz de todos os endpoints	`https://api.sistema.com.br/v1`
Protocolo	Obrigatoriamente HTTPS	HTTPS
Formato de dados	JSON (request e response)	`application/json`
Encoding	UTF-8	UTF-8
Raté limit	Quantas requisições por segundo/minuto	60 req/min
Ambiente de testes	URL de sandbox para desenvolvimento	`https://sandbox.sistema.com.br/v1`

1.2 Autenticação

A API precisa informar qual método de autenticação útiliza:

Método	Como Funciona
API Key	Chave fixa enviada no header `X-API-Key: xxx`
OAuth 2.0	Client ID + Client Secret para gerar access token
Bearer Token	Token fixo ou rotativo no header `Authorization: Bearer xxx`
Basic Auth	Usuario e senha codificados em base64

Necessário informar: Credenciais de acesso, validade do token (se expira, como renovar), escopos/permissões necessários (leitura de agenda, escrita de agendamento, etc.)

1.3 Documentação

Item	Necessidade
Documentação da API (Swagger/OpenAPI)	Ideal, mas não obrigatório
Colecao Postman ou Insomnia	Facilita os testes
Exemplos de request/response	OBRIGATÓRIO
Códigos de erro documentados	OBRIGATÓRIO
Contato técnico do fornecedor	OBRIGATÓRIO

2

Endpoints Necessários

GET /professionals EP-01: Listar Profissionais/Médicos

Obter a lista de médicos cadastrados com suas especialidades para mapeamento com usuários do Kommo.

Response esperado

JSON

{
  "data": [
    {
      "id": 101,
      "name": "Dr. Augusto Pereira",
      "crm": "CRM/GO 5892",
      "specialty": "Oftalmologia Geral",
      "specialties": ["Oftalmologia Geral", "Cirurgia Refrativa"],
      "active": true,
      "appointment_duration_minutes": 30
    }
  ]
}

Campos obrigatórios

Campo	Tipo	Descrição
`id`	integer	ID único do profissional	obrigatório
`name`	string	Nome completo do médico	obrigatório
`specialty`	string/array	Especialidade(s) do médico	obrigatório
`active`	boolean	Se está aceitando agendamentos	obrigatório
`appointment_duration_minutes`	integer	Duração padrão da consulta (min)	obrigatório
`crm`	string	Registro no CRM	desejável
`insurance_accepted`	array	Convênios que o médico aceita	desejável
`location_id`	integer	Consultório/sala	desejável

GET /availability EP-02: Consultar Disponibilidade ENDPOINT CRÍTICO

Este é o endpoint MAIS CRÍTICO de toda a integração. Sem ele, não e possível mostrar horários disponíveis ao paciente.

Dado um médico e um intervalo de datas, retornar os horários disponíveis para agendamento.

Query Parameters

Parâmetro	Tipo	Descrição
`professional_id`	integer	ID do médico	obrigatório
`date_start`	YYYY-MM-DD	Data inicial da busca	obrigatório
`date_end`	YYYY-MM-DD	Data final da busca	obrigatório
`appointment_type_id`	integer	Tipo de consulta (filtra por duração)	opcional
`insurance_id`	integer	Convênio (pode afetar horários)	opcional

Response esperado

JSON

{
  "professional_id": 101,
  "professional_name": "Dr. Augusto Pereira",
  "available_slots": [
    {
      "date": "2026-06-15",
      "weekday": "segunda",
      "slots": [
        { "start_time": "08:00", "end_time": "08:30", "available": true },
        { "start_time": "08:30", "end_time": "09:00", "available": true },
        { "start_time": "09:00", "end_time": "09:30", "available": false, "reason": "occupied" }
      ]
    }
  ]
}

Campos obrigatórios no response

Campo	Tipo	Descrição
`professional_id`	integer	ID do médico consultado
`available_slots`	array	Lista de dias com horários
`available_slots[].date`	string	Data (YYYY-MM-DD)
`available_slots[].slots`	array	Horários daquele dia
`slots[].start_time`	string	Hora de início (HH:MM)
`slots[].end_time`	string	Hora de fim (HH:MM)
`slots[].available`	boolean	Se o horário está livre

Regras de negocio que o endpoint deve respeitar:

Não retornar horários que já passaram
Respeitar antecedência mínima de agendamento
Considerar bloqueios manuais (férias, folgas, intervalos)
Considerar duração do tipo de consulta ao calcular slots
Considerar buffer entre consultas

GET /appointment-types EP-03: Listar Tipos de Consulta

Obter os tipos de consulta disponíveis para mapeamento com as especialidades do Kommo.

JSON Response

{
  "data": [
    {
      "id": 1,
      "name": "Consulta Oftalmologia Geral",
      "duration_minutes": 30,
      "category": "consulta",
      "requires_referral": false,
      "allowed_insurance": ["IPASGO", "Unimed"]
    }
  ]
}

Campo	Tipo	Descrição
`id`	integer	ID único do tipo	obrigatório
`name`	string	Nome do tipo de consulta	obrigatório
`duration_minutes`	integer	Duração em minutos	obrigatório
`category`	string	Categoria (consulta, exame, retorno)	desejável
`allowed_insurance`	array	Convênios aceitos	desejável
`price`	number	Valor particular	desejável

GET /insurances EP-04: Listar Convênios

Obter os convênios cadastrados no sistema para mapeamento com o Kommo.

JSON Response

{
  "data": [
    { "id": 1, "name": "IPASGO", "active": true },
    { "id": 2, "name": "Unimed", "active": true },
    { "id": 3, "name": "Bradesco Saúde", "active": true },
    { "id": 99, "name": "Particular", "active": true }
  ]
}

GET /patients/search EP-05a: Buscar Paciente

Verificar se o paciente já existe no sistema pelo telefone ou CPF.

Parâmetro	Tipo	Descrição
`phone`	string	Telefone do paciente	obrigatório*
`cpf`	string	CPF do paciente	obrigatório*
`name`	string	Nome para busca aproximada	opcional

*Pelo menos um dos campos obrigatórios deve ser informado.

JSON Response

{
  "found": true,
  "patient": {
    "id": 5001,
    "name": "Joao Silva",
    "cpf": "123.456.789-00",
    "phone": "62991510480",
    "email": "joao@email.com",
    "birth_date": "1985-03-15",
    "insurance_id": 1,
    "insurance_name": "IPASGO"
  }
}

POST /patients EP-05b: Cadastrar Paciente

Cadastrar um novo paciente no sistema quando não encontrado na busca.

JSON Request Body

{
  "name": "Joao Silva",
  "phone": "62991510480",
  "email": "joao@email.com",
  "cpf": "123.456.789-00",
  "birth_date": "1985-03-15",
  "insurance_id": 1
}

Campo	Tipo	Descrição
`name`	string	Nome completo	obrigatório
`phone`	string	Telefone com DDD	obrigatório
`cpf`	string	CPF do paciente	desejável
`email`	string	Email	desejável
`birth_date`	YYYY-MM-DD	Data de nascimento	desejável
`insurance_id`	integer	ID do convênio	desejável

POST /appointments EP-06: Criar Agendamento ENDPOINT CRÍTICO

Este é o segundo endpoint MAIS CRÍTICO. Ele efetiva o agendamento no sistema.

Agendar uma consulta no sistema externo, vinculando paciente, médico, data e horário.

Request Body

JSON Request

{
  "patient_id": 5001,
  "professional_id": 101,
  "appointment_type_id": 1,
  "date": "2026-06-15",
  "start_time": "08:00",
  "insurance_id": 1,
  "notes": "Agendado via chatbot Kommo - WhatsApp",
  "source": "kommo_chatbot"
}

Campo	Tipo	Descrição
`patient_id`	integer	ID do paciente no sistema	obrigatório
`professional_id`	integer	ID do médico	obrigatório
`date`	YYYY-MM-DD	Data da consulta	obrigatório
`start_time`	HH:MM	Horário de início	obrigatório
`appointment_type_id`	integer	Tipo de consulta	desejável
`insurance_id`	integer	Convênio	desejável
`notes`	string	Observações	desejável
`source`	string	Origem do agendamento	desejável

Response - Sucesso

{
  "success": true,
  "appointment": {
    "id": 80001,
    "patient_id": 5001,
    "professional_id": 101,
    "professional_name": "Dr. Augusto Pereira",
    "date": "2026-06-15",
    "start_time": "08:00",
    "end_time": "08:30",
    "status": "scheduled"
  }
}

Response - Conflito de Horário

{
  "success": false,
  "error": "slot_unavailable",
  "message": "O horário selecionado não está mais disponível",
  "next_available": [
    { "date": "2026-06-15", "start_time": "09:00" },
    { "date": "2026-06-15", "start_time": "09:30" }
  ]
}

PATCH /appointments/{id}/reschedule EP-07: Reagendar Consulta

Alterar data/hora de uma consulta existente mantendo os demais dados.

JSON Request

{
  "new_date": "2026-06-18",
  "new_start_time": "10:00",
  "reason": "Paciente solicitou reagendamento via chatbot"
}

JSON Response

{
  "success": true,
  "appointment": {
    "id": 80001,
    "old_date": "2026-06-15",
    "old_start_time": "08:00",
    "new_date": "2026-06-18",
    "new_start_time": "10:00",
    "status": "rescheduled"
  }
}

PATCH /appointments/{id}/cancel EP-08: Cancelar Consulta

Cancelar uma consulta existente, liberando o horário na agenda.

JSON Request

{
  "reason": "Paciente solicitou cancelamento via chatbot",
  "cancelled_by": "patient"
}

JSON Response

{
  "success": true,
  "appointment_id": 80001,
  "status": "cancelled",
  "message": "Consulta cancelada com sucesso"
}

GET /appointments EP-09: Listar Agendamentos do Paciente

Listar consultas futuras de um paciente para possibilitar reagendamento ou cancelamento.

Parâmetro	Tipo	Descrição
`patient_id`	integer	ID do paciente	obrigatório*
`patient_phone`	string	Telefone (alternativa ao ID)	obrigatório*
`status`	string	Filtrar: scheduled, cancelled, completed	opcional
`date_from`	YYYY-MM-DD	Data inicial (padrão: hoje)	opcional

JSON Response

{
  "data": [
    {
      "id": 80001,
      "date": "2026-06-15",
      "start_time": "08:00",
      "end_time": "08:30",
      "professional_name": "Dr. Augusto Pereira",
      "specialty": "Oftalmologia Geral",
      "appointment_type": "Consulta Oftalmologia Geral",
      "insurance": "IPASGO",
      "status": "scheduled"
    }
  ]
}

3

Tabelas de Mapeamento

Para a integração funcionar, precisamos mapear os dados entre o Kommo CRM é o sistema externo. Preencha os campos marcados com "?".

3.1 Mapeamento de Médicos

Medico	ID Sistema Externo	Especialidade	ID Usuario Kommo
Dr. Augusto Pereira	?	Oftalmologia Geral	?
(preencher)	?	Oftalmopediatria	?
(preencher)	?	Retina e Vitreo	?
(preencher)	?	Glaucoma	?
(preencher)	?	Cornea	?
(preencher)	?	Oculoplastica	?
(preencher)	?	Cirurgia Refrativa	?
(preencher)	?	Lentes de Contato	?
(preencher)	?	Cardiologia	?
(preencher)	?	Odontologia	?

3.2 Mapeamento de Convênios

Convênio (Kommo)	ID no Sistema Externo
AFFEGO	?
Base Aérea	?
Bonfinopolis	?
Bradesco Saúde	?
Caixa Saúde	?
Campo Limpo	?
CASSI	?
CELGMED	?
GEAP	?
IPASGO	?
Postal Saúde	?
Unimed	?
Urban	?
COOTRAME	?
FMS Anapolis	?
Particular	?

3.3 Mapeamento de Tipos de Consulta

Especialidade (Kommo)	Tipo de Consulta (Sistema Externo)	ID Externo
Oftalmologia Geral	?	?
Oftalmopediatria	?	?
Retina e Vitreo	?	?
Glaucoma	?	?
Cornea	?	?
Oculoplastica	?	?
Cirurgia Refrativa	?	?
Lentes de Contato	?	?
Fisioterapia Ocular	?	?
Cardiologia	?	?
Odontologia	?	?

4

Fluxos Detalhados da Integração

4.1 Fluxo de Agendamento

1

Paciente diz no WhatsApp: "Quero agendar consulta"

2

AI Agent do Kommo identifica intenção de agendamento

3

AI Agent pergunta: especialidade, convênio, preferência de horário

4

AI Agent envia webhook para Cloudflare Worker com os dados coletados

5

Worker chama GET /availability na API externa

6

API retorna horários disponíveis do médico

7

Worker formata e devolve ao AI Agent: "Dr. Augusto tem horários: Seg 15/06 - 08:00, 08:30, 10:00"

8

AI Agent apresenta opcoes ao paciente

9

Paciente escolhe: "08:00 de segunda"

10

Worker chama GET /patients/search pelo telefone do WhatsApp

11

Se não existe: Worker chama POST /patients para cadastrar

12

Worker chama POST /appointments na API externa

13

Worker cria Task tipo Meeting no Kommo (agenda do médico) e move lead para "Consulta Agendada"

14

AI Agent confirma: "Consulta agendada! Dr. Augusto - 15/06 as 08:00"

4.2 Fluxo de Reagendamento

1

Paciente diz: "Quero remarcar minha consulta"

2

Worker chama GET /appointments?patient_phone=...&status=scheduled

3

AI Agent mostra consultas futuras e confirma qual remarcar

4

Worker busca novos horários via GET /availability

5

Paciente escolhe novo horário

6

Worker chama PATCH /appointments/{id}/reschedule

7

Worker atualiza a Task no Kommo com novo horário

4.3 Fluxo de Cancelamento

1

Paciente diz: "Quero cancelar minha consulta"

2

Worker busca agendamentos futuros via GET /appointments

3

AI Agent confirma qual consulta cancelar

4

Worker chama PATCH /appointments/{id}/cancel

5

Worker remove Task do Kommo e move lead no pipeline

6

AI Agent confirma cancelamento ao paciente

5

Requisitos Técnicos - Webhooks

Comunicação entre Kommo e Worker

O Worker usa a API do Kommo para refletir os agendamentos no calendário nativo:

POST  https://{subdomain}.kommo.com/api/v4/tasks        // Criar agendamento
PATCH https://{subdomain}.kommo.com/api/v4/tasks/{id}   // Reagendar
PATCH https://{subdomain}.kommo.com/api/v4/leads/{id}   // Mover lead no pipeline
POST  https://{subdomain}.kommo.com/api/v4/notes        // Adicionar nota com detalhes

6

Tratamento de Erros

Códigos HTTP Esperados

Código	Situação	Acao do Sistema
200	Sucesso	Dados retornados / acao realizada
201	Criado	Agendamento ou paciente criado
400	Dados inválidos	Campos obrigatórios faltando ou formato incorreto
401	Não autenticado	Credenciais inválidas ou token expirado
403	Sem permissão	Sem acesso a este recurso
404	Não encontrado	Paciente/agendamento/médico não encontrado
409	Conflito	Horário já ocupado (retornar próximos disponíveis)
422	Regra de negocio	Ex: antecedência mínima não respeitada
429	Raté limit	Muitas requisições, aguardar
500	Erro interno	Erro no servidor do sistema

Formato padrão de erro

{
  "success": false,
  "error": "slot_unavailable",
  "message": "Descrição legivel do erro",
  "details": { "campo": "informação adicional" }
}

7

Checklist para o Fornecedor

Informações de Acesso

URL base da API (produção)
URL base da API (sandbox/testes)
Credenciais de autenticação (tipo + chaves)
Documentação da API (se existir)
Contato técnico para suporte durante integração

Endpoints Necessários

EP-01: Listar médicos/profissionais com especialidades
EP-02: Consultar disponibilidade/horários livres por médico e data
EP-03: Listar tipos de consulta/agendamento
EP-04: Listar convênios cadastrados
EP-05a: Buscar paciente por telefone ou CPF
EP-05b: Cadastrar novo paciente
EP-06: Criar agendamento
EP-07: Reagendar consulta existente
EP-08: Cancelar consulta
EP-09: Listar agendamentos futuros de um paciente

Mapeamento de Dados

Lista completa de médicos com IDs
Lista completa de especialidades com IDs
Lista completa de convênios com IDs
Lista completa de tipos de consulta com IDs e duracoes
Regras de negocio (antecedência mínima, horários por médico, etc.)

Requisitos Técnicos

API aceita requisições em JSON via HTTPS
API retorna respostas em JSON com códigos HTTP padrão
API trata conflitos de horário (retorno 409 com alternativas)
API suporta busca de paciente por telefone
Raté limit documentado

8

Alternativas (caso não tenha API)

Se o software de agendamento atual não possui API e não tem previsão de implementar, estas sao as alternativas viáveis:

1

Kommo Nativo

Usar 100% o calendário do Kommo como agenda principal

Baixa

2

Google Calendar

Integrar Kommo com Google Calendar (sync nativo bidirecional)

Baixa

3

Cal.com

Usar Cal.com como camada de agendamento (tem API e integra com Kommo)

Media

4

Middleware RPA

Usar automacao (Make/Zapier) para interagir com interface do sistema

Alta

5

Trocar de Software

Migrar para sistema com API (Amplimed, Ninsaude, etc.)

Alta

Recomendacao para o HOA:
Curto prazo: Alternativa 1 (Kommo nativo) + entrada manual no sistema externo
Medio prazo: Alternativa 2 ou 3 (Google Calendar ou Cal.com)
Longo prazo: Alternativa 5 (migrar para sistema com API)

9

Resumo Executivo

O que precisamos do fornecedor do software

Precisamos que o software de agendamento da clínica disponibilize uma API (interface de programação) que permita, de forma automatizada:

Consultar quais horários estao livres na agenda de cada médico
Agendar uma consulta informando paciente, médico, data e horário
Reagendar uma consulta existente para novo horário
Cancelar uma consulta existente
Buscar se um paciente já está cadastrado (pelo telefone)
Cadastrar um novo paciente (nome e telefone no minimo)

Isso permitira que nosso chatbot no WhatsApp (via Kommo CRM) consulte a agenda real dos médicos em tempo real e agende consultas automáticamente, sem intervenção humana, 24 horas por dia.

Caso a API não estejá disponível, solicitamos informações sobre previsão de implementação ou alternativas de integração que o sistema suporte.

Requisitos de APISistema de Agendamento Externo

Arquitetura do Fluxo

Requisitos de Infraestrutura da API

Endpoints Necessários

Tabelas de Mapeamento

Fluxos Detalhados da Integração

Requisitos Técnicos - Webhooks

Tratamento de Erros

Checklist para o Fornecedor

Alternativas (caso não tenha API)

Resumo Executivo

O que precisamos do fornecedor do software

Requisitos de API
Sistema de Agendamento Externo