Documentacao da API

Visao Geral

A API Publica do AgendouAI permite que sistemas externos (ERPs, CRMs, chatbots) se integrem com sua conta para consultar e criar agendamentos, listar profissionais e servicos, gerenciar clientes e receber redirecionamento de atendimentos de chatbots.

Agendamentos

Crie e consulte agendamentos

Profissionais

Liste profissionais disponiveis

Disponibilidade

Verifique horarios livres

Chatbots

Integre seus chatbots

Autenticacao

Toda requisicao deve incluir uma API Key valida no header. As API Keys podem ser criadas e gerenciadas na pagina de API Keys.

Header de Autenticacao

X-API-Key: lk_sua_api_key_aqui

Exemplo de Requisicao

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

Permissoes: Cada API Key esta vinculada a um projeto especifico e so tem acesso aos dados desse projeto. Apenas administradores podem criar/revogar keys.

Restricoes: Por seguranca, a API NAO permite operacoes de pagamento, contratacao/cancelamento de planos, exclusao de projetos ou desconexao de agendas/WhatsApp.

Ambientes

Ambiente	Base URL
Producao	`https://api.{{DOMAIN}}/api/public/v1`
Desenvolvimento	`https://api-dev.{{DOMAIN}}/api/public/v1`

Rate Limiting

Os limites de requisicoes 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

Codigos de Erro

Codigo	Descricao
200	Sucesso
201	Criado com sucesso
400	Requisicao invalida
401	API Key invalida ou ausente
403	Sem permissao para esta operacao
404	Recurso nao encontrado
409	Conflito (ex: horario indisponivel)
422	Erro de validacao
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.

Parametros Query

Parametro	Tipo	Descricao
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	Pagina (default: 1)
limit	integer	Itens por pagina (default: 50, max: 100)

Exemplo de Requisicao

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	Obrigatorio	Descricao
profissional_id	uuid	Sim	ID do profissional
servico_id	uuid	Sim	ID do servico
cliente_telefone	string	Sim	Telefone do cliente
data_hora	datetime	Sim	Data e hora (ISO 8601)
cliente_nome	string	Nao	Nome do cliente
cliente_email	string	Nao	Email do cliente
observacoes	string	Nao	Observacoes adicionais

Exemplo de Requisicao

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 Possiveis

400	Dados invalidos
409	Horario indisponivel
422	Profissional ou servico nao encontrado

Google Calendar: Se o profissional tiver uma agenda do Google conectada, o evento sera criado automaticamente no calendario.

GET /agendamentos/:id

Busca um agendamento especifico pelo ID.

Parametros Path

Parametro	Tipo	Descricao
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. Nao permite trocar o profissional.

Parametros Path

Parametro	Tipo	Descricao
id	uuid	ID do agendamento

Body (JSON)

Campo	Tipo	Descricao
servico_id	uuid	Novo servico
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 Requisicao

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"
  }
}

Sincronizacao: Se houver um evento no Google Calendar vinculado, ele sera atualizado automaticamente.

DELETE /agendamentos/:id

Cancela um agendamento. O registro nao e excluido, apenas marcado como "cancelado" (soft delete).

Parametros Path

Parametro	Tipo	Descricao
id	uuid	ID do agendamento

Body (JSON - Opcional)

Campo	Tipo	Descricao
motivo	string	Motivo do cancelamento

Exemplo de Requisicao

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 sera deletado automaticamente.

Profissionais

GET /profissionais

Lista todos os profissionais ativos do projeto.

Exemplo de Requisicao

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": "[email protected]",
        "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 serao sincronizados automaticamente.

Servicos

GET /servicos

Lista servicos disponiveis, opcionalmente filtrados por profissional.

Parametros Query

Parametro	Tipo	Descricao
profissional_id	uuid	Filtrar servicos por profissional

Resposta

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

Disponibilidade

GET /horarios-disponiveis

Consulta horarios disponiveis para agendamento em uma data especifica.

Parametros Query (Obrigatorios)

Parametro	Tipo	Descricao
profissional_id Obrigatorio	uuid	ID do profissional
servico_id Obrigatorio	uuid	ID do servico
data Obrigatorio	date	Data para consulta (YYYY-MM-DD)

Exemplo de Requisicao

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.

Parametros Query

Parametro	Tipo	Descricao
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": "[email protected]"
}

Webhook para Chatbots

POST /webhook/chatbot

Endpoint para receber mensagens de chatbots externos e processar acoes automaticamente.

Body (JSON)

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

Acoes Disponiveis

Acao	Descricao
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 Integracao

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));
?>