Voltar Swagger

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": "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 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": "maria@email.com"
}

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