Documentação da API

Visão Geral

A API Pública do AgendouIA permite que sistemas externos (ERPs, CRMs, chatbots) se integrem com sua conta para consultar e criar agendamentos, listar profissionais e serviços, gerenciar clientes e receber redirecionamento de atendimentos de chatbots.

Agendamentos

Crie e consulte agendamentos

Profissionais

Liste profissionais disponíveis

Disponibilidade

Verifique horários livres

Chatbots

Integre seus chatbots

Autenticação

Toda requisição deve incluir uma API Key válida no header. As API Keys podem ser criadas e gerenciadas na página de API Keys.

Header de Autenticação

X-API-Key: lk_sua_api_key_aqui

Exemplo de Requisição

curl -X GET "https://api.{{DOMAIN}}/api/public/v1/agendamentos" \
  -H "X-API-Key: lk_sua_api_key" \
  -H "Content-Type: application/json"

Permissões: Cada API Key está vinculada a um projeto específico e só tem acesso aos dados desse projeto. Apenas administradores podem criar/revogar keys.

Restrições: Por segurança, a API NÃO permite operações de pagamento, contratação/cancelamento de planos, exclusão de projetos ou desconexão de agendas/WhatsApp.

Ambientes

Ambiente	Base URL
Produção	`https://api.{{DOMAIN}}/api/public/v1`
Desenvolvimento	`https://api-dev.{{DOMAIN}}/api/public/v1`

Rate Limiting

Os limites de requisições variam conforme o plano contratado. Ao exceder o limite, a API retorna status 429.

Plano	Req/minuto	Req/dia
Starter	60	1.000
Pro	120	10.000
Enterprise	300	100.000

Headers de Rate Limit

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

Códigos de Erro

Código	Descrição
200	Sucesso
201	Criado com sucesso
400	Requisição inválida
401	API Key inválida ou ausente
403	Sem permissão para esta operação
404	Recurso não encontrado
409	Conflito (ex: horário indisponível)
422	Erro de validação
429	Rate limit excedido
500	Erro interno do servidor

Estrutura de Erro

{
  "success": false,
  "error": "codigo_do_erro",
  "message": "Descricao legivel do erro",
  "details": {
    "campo": "Erro especifico do campo"
  }
}

Agendamentos

GET /agendamentos

Lista agendamentos do projeto com filtros opcionais.

Parâmetros Query

Parâmetro	Tipo	Descrição
data_inicio	date	Data inicial (YYYY-MM-DD)
data_fim	date	Data final (YYYY-MM-DD)
profissional_id	uuid	Filtrar por profissional
status	string	Filtrar por status (agendado, confirmado, cancelado)
page	integer	Página (default: 1)
limit	integer	Itens por página (default: 50, max: 100)

Exemplo de Requisição

curl -X GET "https://api.{{DOMAIN}}/api/public/v1/agendamentos?data_inicio=2025-01-01&data_fim=2025-01-31" \
  -H "X-API-Key: lk_sua_api_key"

Resposta

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "profissional_id": "uuid",
      "profissional_nome": "Dr. Joao",
      "servico_id": "uuid",
      "servico_nome": "Consulta",
      "cliente_nome": "Maria Silva",
      "cliente_telefone": "11999999999",
      "data_hora": "2025-01-15T14:00:00Z",
      "status": "agendado",
      "observacoes": "Primeira consulta",
      "created_at": "2025-01-10T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "total_pages": 3
  }
}

POST /agendamentos

Cria um novo agendamento.

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
profissional_id	uuid	Sim	ID do profissional
servico_id	uuid	Sim	ID do serviço
cliente_telefone	string	Sim	Telefone do cliente
data_hora	datetime	Sim	Data e hora (ISO 8601)
cliente_nome	string	Não	Nome do cliente
cliente_email	string	Não	Email do cliente
observacoes	string	Não	Observações adicionais

Exemplo de Requisição

curl -X POST "https://api.{{DOMAIN}}/api/public/v1/agendamentos" \
  -H "X-API-Key: lk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profissional_id": "uuid-do-profissional",
    "servico_id": "uuid-do-servico",
    "cliente_telefone": "11999999999",
    "cliente_nome": "Maria Silva",
    "data_hora": "2025-01-15T14:00:00Z"
  }'

Resposta (201)

{
  "success": true,
  "data": {
    "id": "uuid-do-agendamento",
    "status": "agendado",
    "data_hora": "2025-01-15T14:00:00Z",
    "created_at": "2025-01-10T10:00:00Z"
  }
}

Erros Possíveis

400	Dados inválidos
409	Horário indisponível
422	Profissional ou serviço não encontrado

Google Calendar: Se o profissional tiver uma agenda do Google conectada, o evento será criado automaticamente no calendário.

GET /agendamentos/:id

Busca um agendamento específico pelo ID.

Parâmetros Path

Parâmetro	Tipo	Descrição
id	uuid	ID do agendamento

Resposta

{
  "success": true,
  "data": {
    "agendamento": {
      "id": "uuid",
      "profissional_id": "uuid",
      "profissional_nome": "Dr. Joao",
      "servico_id": "uuid",
      "servico_nome": "Consulta",
      "cliente_nome": "Maria Silva",
      "cliente_telefone": "11999999999",
      "data_hora": "2025-01-15T14:00:00Z",
      "data_fim": "2025-01-15T14:30:00Z",
      "status": "agendado",
      "google_event_id": "abc123xyz",
      "google_event_link": "https://calendar.google.com/..."
    }
  }
}

PUT /agendamentos/:id

Atualiza um agendamento existente. Não permite trocar o profissional.

Parâmetros Path

Parâmetro	Tipo	Descrição
id	uuid	ID do agendamento

Body (JSON)

Campo	Tipo	Descrição
servico_id	uuid	Novo serviço
cliente_nome	string	Nome do cliente
cliente_telefone	string	Telefone do cliente
cliente_email	string	Email do cliente
data_hora	datetime	Nova data/hora (ISO 8601)
status	string	Novo status: agendado, confirmado, concluido, cancelado, perdido

Exemplo de Requisição

curl -X PUT "https://api.{{DOMAIN}}/api/public/v1/agendamentos/uuid-do-agendamento" \
  -H "X-API-Key: lk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data_hora": "2025-01-16T15:00:00Z",
    "status": "confirmado"
  }'

Resposta

{
  "success": true,
  "message": "Agendamento atualizado com sucesso",
  "data": {
    "id": "uuid",
    "data_hora": "2025-01-16T15:00:00Z",
    "status": "confirmado"
  }
}

Sincronização: Se houver um evento no Google Calendar vinculado, ele será atualizado automaticamente.

DELETE /agendamentos/:id

Cancela um agendamento. O registro não é excluído, apenas marcado como "cancelado" (soft delete).

Parâmetros Path

Parâmetro	Tipo	Descrição
id	uuid	ID do agendamento

Body (JSON - Opcional)

Campo	Tipo	Descrição
motivo	string	Motivo do cancelamento

Exemplo de Requisição

curl -X DELETE "https://api.{{DOMAIN}}/api/public/v1/agendamentos/uuid-do-agendamento" \
  -H "X-API-Key: lk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "motivo": "Cliente solicitou cancelamento" }'

Resposta

{
  "success": true,
  "message": "Agendamento cancelado com sucesso",
  "data": {
    "id": "uuid",
    "status": "cancelado",
    "cancelled_at": "2025-01-10T12:00:00Z"
  }
}

Google Calendar: Se houver um evento vinculado no Google Calendar, ele será deletado automaticamente.

Profissionais

GET /profissionais

Lista todos os profissionais ativos do projeto.

Exemplo de Requisição

curl -X GET "https://api.{{DOMAIN}}/api/public/v1/profissionais" \
  -H "X-API-Key: lk_sua_api_key"

Resposta

{
  "success": true,
  "data": {
    "profissionais": [
      {
        "id": "uuid",
        "nome": "Dr. Joao Silva",
        "especialidade": "Clinico Geral",
        "email": "joao@email.com",
        "telefone": "11999999999",
        "duracao_padrao": 30,
        "ativo": true,
        "google_calendar_conectado": true
      }
    ]
  }
}

O campo google_calendar_conectado indica se o profissional tem uma agenda Google vinculada. Se true, agendamentos criados para este profissional serão sincronizados automaticamente.

Serviços

GET /servicos

Lista serviços disponíveis, opcionalmente filtrados por profissional.

Parâmetros Query

Parâmetro	Tipo	Descrição
profissional_id	uuid	Filtrar serviços por profissional

Resposta

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "nome": "Consulta",
      "duracao_minutos": 30,
      "valor": 150.00
    }
  ]
}

Disponibilidade

GET /horarios-disponiveis

Consulta horários disponíveis para agendamento em uma data específica.

Parâmetros Query (Obrigatórios)

Parâmetro	Tipo	Descrição
profissional_id Obrigatório	uuid	ID do profissional
servico_id Obrigatório	uuid	ID do serviço
data Obrigatório	date	Data para consulta (YYYY-MM-DD)

Exemplo de Requisição

curl -X GET "https://api.{{DOMAIN}}/api/public/v1/horarios-disponiveis?profissional_id=uuid&servico_id=uuid&data=2025-01-15" \
  -H "X-API-Key: lk_sua_api_key"

Resposta

{
  "success": true,
  "data": [
    { "data_hora": "2025-01-15T09:00:00Z", "disponivel": true },
    { "data_hora": "2025-01-15T09:30:00Z", "disponivel": true },
    { "data_hora": "2025-01-15T10:00:00Z", "disponivel": false },
    { "data_hora": "2025-01-15T10:30:00Z", "disponivel": true }
  ]
}

Clientes

GET /clientes

Lista clientes do projeto com filtros opcionais.

Parâmetros Query

Parâmetro	Tipo	Descrição
telefone	string	Buscar por telefone exato
nome	string	Buscar por nome (parcial)

POST /clientes

Cria ou atualiza um cliente (upsert por telefone).

Body (JSON)

{
  "nome": "Maria Silva",
  "telefone": "11999999999",
  "email": "maria@email.com"
}

Webhook para Chatbots

POST /webhook/chatbot

Endpoint para receber mensagens de chatbots externos e processar ações automaticamente.

Body (JSON)

{
  "telefone": "11999999999",
  "mensagem": "Quero agendar uma consulta",
  "contexto": {
    "chatbot_id": "identificador",
    "sessao_id": "uuid-sessao"
  },
  "acao": "agendar"
}

Ações Disponíveis

Ação	Descrição
agendar	Iniciar fluxo de agendamento
consultar	Consultar agendamentos do cliente
cancelar	Cancelar um agendamento
transferir	Transferir atendimento para secretaria

Resposta

{
  "success": true,
  "resposta": "Ola! Vi que voce quer agendar uma consulta. Temos horarios disponiveis...",
  "acao_executada": "agendar",
  "dados": {
    "horarios_sugeridos": [...]
  }
}

Exemplos de Integração

JavaScript / Node.js

const API_KEY = 'lk_sua_api_key';
const BASE_URL = 'https://api.{{DOMAIN}}/api/public/v1';

async function listarAgendamentos(dataInicio, dataFim) {
  const response = await fetch(
    `${BASE_URL}/agendamentos?data_inicio=${dataInicio}&data_fim=${dataFim}`,
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.json();
}

async function criarAgendamento(dados) {
  const response = await fetch(`${BASE_URL}/agendamentos`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(dados)
  });
  return response.json();
}

// Uso
const agendamentos = await listarAgendamentos('2025-01-01', '2025-01-31');
console.log(agendamentos);

Python

import requests

API_KEY = 'lk_sua_api_key'
BASE_URL = 'https://api.{{DOMAIN}}/api/public/v1'

headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
}

# Listar agendamentos
response = requests.get(
    f'{BASE_URL}/agendamentos',
    headers=headers,
    params={'data_inicio': '2025-01-01', 'data_fim': '2025-01-31'}
)
print(response.json())

# Criar agendamento
dados = {
    'profissional_id': 'uuid',
    'servico_id': 'uuid',
    'cliente_telefone': '11999999999',
    'cliente_nome': 'Maria Silva',
    'data_hora': '2025-01-15T14:00:00Z'
}
response = requests.post(f'{BASE_URL}/agendamentos', headers=headers, json=dados)
print(response.json())

PHP

<?php
$apiKey = 'lk_sua_api_key';
$baseUrl = 'https://api.{{DOMAIN}}/api/public/v1';

// Listar agendamentos
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$baseUrl/agendamentos?data_inicio=2025-01-01&data_fim=2025-01-31");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: $apiKey",
    "Content-Type: application/json"
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

// Criar agendamento
$dados = [
    'profissional_id' => 'uuid',
    'servico_id' => 'uuid',
    'cliente_telefone' => '11999999999',
    'cliente_nome' => 'Maria Silva',
    'data_hora' => '2025-01-15T14:00:00Z'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$baseUrl/agendamentos");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($dados));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: $apiKey",
    "Content-Type: application/json"
]);
$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
?>