Para quem é este documento: Equipe técnica da empresa fornecedora do software de prontuário eletrônico e agendamento de consultas utilizado pelo Hospital Oftalmológico de Anápolis (HOA).
O que o HOA precisa
O HOA está implementando um chatbot inteligente no WhatsApp para atendimento automatizado de pacientes. Para que esse chatbot funcione integrado ao sistema de agendamento real da clínica, precisamos que o software forneça uma API REST que permita:
| # | Capacidade | Descrição |
|---|
| 1 | Consultar disponibilidade | Verificar horários livres na agenda de cada médico |
| 2 | Criar agendamento | Agendar consulta informando paciente, médico, data e horário |
| 3 | Reagendar consulta | Alterar data/hora de consulta existente |
| 4 | Cancelar consulta | Cancelar agendamento existente |
| 5 | Buscar paciente | Verificar se paciente já está cadastrado (por telefone) |
| 6 | Cadastrar paciente | Registrar novo paciente (nome e telefone no mínimo) |
| 7 | Listar profissionais | Obter médicos com suas especialidades |
| 8 | Listar convênios | Obter convênios aceitos |
| 9 | Listar tipos de consulta | Obter tipos de agendamento com durações |
2
Dois Cenários de Integração
O HOA avalia dois cenários de integração. A API necessária é a mesma em ambos - o que muda é quem consome essa API. O fornecedor do software precisa entregar os mesmos endpoints independentemente do cenário escolhido.
Cenário 1
Kommo Nativo
O próprio Kommo CRM gerencia o chatbot usando o AI Agent nativo + Cloudflare Worker como ponte.
Fluxo:
WhatsApp → Kommo AI Agent → Cloudflare Worker → API do Sistema → Kommo Calendar
Vantagens:
- Menos componentes
- Custo menor
- Configuração mais simples
Limitações:
- Chatbot baseado em menus fixos
- Não entende linguagem natural
- Fluxo rígido de conversa
Cenário 2
Kommo + n8n + IA
O n8n orquestra o fluxo, usando Inteligência Artificial (Claude/GPT) para entender linguagem natural.
Fluxo:
WhatsApp → Kommo → n8n → IA → API do Sistema → n8n → Kommo
Vantagens:
- Entende linguagem natural
- Triagem inteligente por sintomas
- Conversa livre e adaptativa
- Integrações ilimitadas
Limitações:
- Mais componentes para manter
- Custo um pouco maior (~R$ 450/mês)
Conclusão para o fornecedor: Independentemente do cenário, a API que vocês precisam fornecer é exatamente a mesma. Os endpoints, campos e formatos descritos neste documento se aplicam a ambos os cenários.
3
Requisitos de Infraestrutura da API
3.1 Informações básicas necessárias
| 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 |
| Rate limit | Quantas requisições por minuto são permitidas | 60 req/min |
| Ambiente de testes | URL de sandbox para desenvolvimento | https://sandbox.sistema.com.br/v1 |
3.2 Autenticação
Informar qual método de autenticação a API utiliza:
| Método | Como funciona |
|---|
| API Key | Chave fixa no header X-API-Key: xxx |
| OAuth 2.0 | Client ID + Client Secret para gerar access token |
| Bearer Token | Token no header Authorization: Bearer xxx |
| Basic Auth | Usuário e senha codificados em base64 |
Necessário informar: Credenciais de acesso, validade do token (se expira e como renovar), escopos/permissões necessários (leitura de agenda, escrita de agendamento, etc.)
3.3 Documentação
| Item | Necessidade |
|---|
| Documentação da API (Swagger/OpenAPI) | Ideal, mas não obrigatório |
| Coleção 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 |
4
Endpoints Necessários (9 endpoints)
Todos os endpoints abaixo são necessários para ambos os cenários de integração. Os exemplos de JSON mostram o formato esperado - os nomes dos campos podem variar desde que a informação esteja presente.
GET/professionalsEP-01: Listar Profissionais
Retornar a lista de médicos cadastrados com suas especialidades e duração padrão de consulta.
Response esperado
{
"data": [
{
"id": 101,
"name": "Dr. Augusto Pereira",
"crm": "CRM/GO 5892",
"specialties": ["Oftalmologia Geral", "Cirurgia Refrativa"],
"active": true,
"appointment_duration_minutes": 30
}
]
}| Campo | Tipo | Descrição | |
|---|
id | integer | ID único do profissional | obrigatório |
name | string | Nome completo | obrigatório |
specialties | array | Especialidade(s) | obrigatório |
active | boolean | Se está aceitando agendamentos | obrigatório |
appointment_duration_minutes | integer | Duração padrão (minutos) | obrigatório |
crm | string | Registro no CRM | desejável |
insurance_accepted | array | Convênios aceitos | desejável |
GET/availabilityEP-02: Consultar DisponibilidadeENDPOINT CRÍTICO
Este é o endpoint MAIS CRÍTICO de toda a integração. Sem ele, não é 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.
Parâmetros de consulta (query string)
| Parâmetro | Tipo | Descrição | |
|---|
professional_id | integer | ID do médico | obrigatório |
date_start | YYYY-MM-DD | Data inicial | obrigatório |
date_end | YYYY-MM-DD | Data final | obrigatório |
appointment_type_id | integer | Tipo de consulta | opcional |
insurance_id | integer | Convênio | opcional |
Response esperado
{
"professional_id": 101,
"professional_name": "Dr. Augusto Pereira",
"available_slots": [
{
"date": "2026-06-16",
"weekday": "terça",
"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 }
]
}
]
}Regras que o endpoint deve respeitar: Não retornar horários passados; respeitar antecedencia mínima; considerar bloqueios do médico (férias, folgas); considerar duração da consulta; considerar buffer entre consultas.
GET/appointment-typesEP-03: Listar Tipos de Consulta
Retornar os tipos de consulta disponíveis com suas durações.
{
"data": [
{ "id": 1, "name": "Consulta Oftalmologia Geral", "duration_minutes": 30 },
{ "id": 2, "name": "Avaliação Cirurgia Refrativa", "duration_minutes": 45 },
{ "id": 3, "name": "Retorno", "duration_minutes": 15 }
]
}GET/insurancesEP-04: Listar Convênios
Retornar convênios cadastrados com seus IDs para mapeamento.
{
"data": [
{ "id": 1, "name": "IPASGO", "active": true },
{ "id": 2, "name": "Unimed", "active": true },
{ "id": 99, "name": "Particular", "active": true }
]
}GET/patients/searchEP-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* |
*Pelo menos um deve ser informado.
{
"found": true,
"patient": {
"id": 5001,
"name": "João Silva",
"phone": "62991510480",
"insurance_id": 1,
"insurance_name": "IPASGO"
}
}POST/patientsEP-05b: Cadastrar Paciente
Cadastrar novo paciente quando não encontrado na busca.
Request Body
{
"name": "João Silva",
"phone": "62991510480",
"email": "joao@email.com",
"cpf": "123.456.789-00",
"birth_date": "1985-03-15",
"insurance_id": 1
}| Campo | Tipo | |
|---|
name | string | obrigatório |
phone | string | obrigatório |
cpf | string | desejável |
email | string | desejável |
birth_date | YYYY-MM-DD | desejável |
insurance_id | integer | desejável |
POST/appointmentsEP-06: Criar AgendamentoENDPOINT CRÍTICO
Segundo endpoint mais crítico. Efetiva o agendamento no sistema.
Request Body
{
"patient_id": 5001,
"professional_id": 101,
"appointment_type_id": 1,
"date": "2026-06-16",
"start_time": "08:00",
"insurance_id": 1,
"notes": "Agendado via chatbot WhatsApp",
"source": "kommo_chatbot"
}| Campo | Tipo | Descrição | |
|---|
patient_id | integer | ID do paciente | 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 |
source | string | Origem do agendamento | desejável |
Response - Sucesso
{
"success": true,
"appointment": {
"id": 80001,
"professional_name": "Dr. Augusto Pereira",
"date": "2026-06-16",
"start_time": "08:00",
"end_time": "08:30",
"status": "scheduled"
}
}Response - Conflito de horário (409)
{
"success": false,
"error": "slot_unavailable",
"message": "Horário não está mais disponível",
"next_available": [
{ "date": "2026-06-16", "start_time": "09:00" }
]
}PATCH/appointments/{id}/rescheduleEP-07: Reagendar
Alterar data/hora de uma consulta existente.
Request: { "new_date": "2026-06-18", "new_start_time": "10:00" }
Response: {
"success": true,
"appointment": {
"id": 80001, "new_date": "2026-06-18",
"new_start_time": "10:00", "status": "rescheduled"
}
}PATCH/appointments/{id}/cancelEP-08: Cancelar
Cancelar uma consulta existente, liberando o horário.
Request: { "reason": "Paciente solicitou via chatbot" }
Response: { "success": true, "status": "cancelled" }GET/appointmentsEP-09: Listar Agendamentos do Paciente
Listar consultas futuras de um paciente para reagendamento ou cancelamento.
| Parâmetro | Tipo | |
|---|
patient_phone | string | obrigatório* |
patient_id | integer | obrigatório* |
status | string | opcional (scheduled, cancelled, completed) |
{
"data": [
{
"id": 80001,
"date": "2026-06-16",
"start_time": "08:00",
"professional_name": "Dr. Augusto Pereira",
"specialty": "Oftalmologia Geral",
"status": "scheduled"
}
]
}5
Tabelas de Mapeamento (preencher)
Para a integração funcionar, precisamos mapear os dados entre os sistemas. Solicitamos que o fornecedor preencha os campos marcados com "?".
5.1 Mapeamento de Médicos
| Médico | Especialidade | ID no Sistema |
|---|
| Dr. Augusto Pereira | Oftalmologia Geral | ? |
| (preencher) | Oftalmopediatria | ? |
| (preencher) | Retina e Vítreo | ? |
| (preencher) | Glaucoma | ? |
| (preencher) | Córnea | ? |
| (preencher) | Oculoplástica | ? |
| (preencher) | Cirurgia Refrativa | ? |
| (preencher) | Lentes de Contato | ? |
| (preencher) | Cardiologia | ? |
| (preencher) | Odontologia | ? |
5.2 Mapeamento de Convênios
| Convênio | ID no Sistema |
|---|
| AFFEGO | ? |
| Base Aérea | ? |
| Bonfinópolis | ? |
| Bradesco Saúde | ? |
| Caixa Saúde | ? |
| Campo Limpo | ? |
| CASSI | ? |
| CELGMED | ? |
| GEAP | ? |
| IPASGO | ? |
| Postal Saúde | ? |
| Unimed | ? |
| Urban | ? |
| COOTRAME | ? |
| FMS Anápolis | ? |
| Particular | ? |
5.3 Mapeamento de Tipos de Consulta
| Especialidade | Nome no Sistema | ID | Duração |
|---|
| Oftalmologia Geral | ? | ? | ? |
| Oftalmopediatria | ? | ? | ? |
| Retina e Vítreo | ? | ? | ? |
| Glaucoma | ? | ? | ? |
| Córnea | ? | ? | ? |
| Oculoplástica | ? | ? | ? |
| Cirurgia Refrativa | ? | ? | ? |
| Lentes de Contato | ? | ? | ? |
| Cardiologia | ? | ? | ? |
| Odontologia | ? | ? | ? |
O que precisamos (versão simplificada)
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 estão 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 mínimo)
Isso permitirá que nosso chatbot no WhatsApp consulte a agenda real dos médicos em tempo real e agende consultas automaticamente, sem intervenção humana, 24 horas por dia.
Essa integração funcionará tanto no cenário com Kommo nativo quanto no cenário com Kommo + n8n + IA. A API necessária é a mesma em ambos os casos.
Caso a API não esteja disponível, solicitamos informações sobre previsão de implementação ou alternativas de integração que o sistema suporte.