API de agendamentos · v1

Documentação da API

A API da Alibit permite que outros sistemas (ERP, site, app, chatbot) leiam e gravem a agenda de uma empresa: profissionais, serviços, horários livres, clientes e agendamentos. Quando algo muda na agenda, avisamos o seu sistema por webhooks.

Produção e sandbox

Existe uma única URL para testes e para produção. O que muda é a chave de API: cada chave pertence a uma empresa, e a API só enxerga os dados dela.

Diferenças da empresa de sandbox: ela não tem site de agendamento público e não é cobrada. Todo o resto funciona igual.

Início rápido

Com a chave do sandbox em mãos, confira se ela funciona buscando os dados da empresa:

curl https://api.alibit.com.br/v1/companies/me \
  -H "X-Api-Key: $ALIBIT_API_KEY"

Resposta:

{
  "id": "6f1c…",
  "name": "Sandbox – Sua Empresa",
  "slug": "sandbox-sua-empresa",
  "status": "ACTIVE"
}

Em JavaScript (Node 18+), a mesma chamada:

const res = await fetch('https://api.alibit.com.br/v1/companies/me', {
  headers: { 'X-Api-Key': process.env.ALIBIT_API_KEY },
});
if (!res.ok) throw new Error(`Erro ${res.status}: ${await res.text()}`);
const empresa = await res.json();

Depois, siga o fluxo de agendamento para marcar o primeiro horário.

Autenticação

Envie a chave no cabeçalho X-Api-Key de toda requisição. As chaves começam com agd_.

GET /v1/appointments HTTP/1.1
Host: api.alibit.com.br
X-Api-Key: agd_…

• A chave age como o administrador da empresa que a criou e só enxerga os dados dessa empresa.
• Use a chave só no servidor. Nunca a coloque em código que roda no navegador ou no celular do cliente.
• Chave ausente, inválida ou revogada: resposta 401.
• Plano sem API para integrações: resposta 403 com "code": "FEATURE_NOT_IN_PLAN".
• Com a chave não é possível criar outras chaves, cadastrar webhooks nem redefinir senhas: isso é feito no painel.

Limites

Quando o plano tem limite mensal, toda resposta traz X-Api-Quota-Limit (total do mês) e X-Api-Quota-Remaining (quanto ainda resta). Planos sem limite mensal não enviam esses cabeçalhos.

Erros

Os erros vêm em JSON. Alguns trazem um code estável para você tratar no seu sistema; em erros de validação, message é uma lista.

{
  "statusCode": 409,
  "message": "Já existe um agendamento neste horário",
  "error": "Conflict"
}

Datas e fusos

• Data e hora sempre em ISO 8601, em UTC: 2026-10-09T13:00:00.000Z.
• Ao enviar, você pode usar UTC (Z) ou informar o fuso: 2026-10-09T10:00:00-03:00 é o mesmo instante.
• Converta para o fuso da empresa (America/Sao_Paulo) antes de mostrar ao usuário.
• Datas sem hora, como o aniversário do cliente ou o dia consultado em horários livres, usam YYYY-MM-DD.
• Horários de expediente usam HH:mm no fuso da empresa; dias da semana vão de 0 (domingo) a 6 (sábado).

Versionamento

Todas as rotas começam com /v1. Campos novos podem aparecer nas respostas a qualquer momento: ignore o que não conhece. Mudanças que quebram compatibilidade vão para uma nova versão (/v2), com aviso prévio, e a v1 continua funcionando.

Fluxo de agendamento

O caminho mais comum para marcar um horário pela sua integração:

1. Listar profissionais da empresa

   curl https://api.alibit.com.br/v1/team/professionals -H "X-Api-Key: $ALIBIT_API_KEY"

2. Listar serviços de um profissional

   curl "https://api.alibit.com.br/v1/services?professionalId=PROFISSIONAL_ID" \
     -H "X-Api-Key: $ALIBIT_API_KEY"

3. Consultar horários livres no dia

   Já considera expediente, bloqueios, outros agendamentos e a duração do serviço.

   curl "https://api.alibit.com.br/v1/appointments/availability?professionalId=PROFISSIONAL_ID&serviceId=SERVICO_ID&date=2026-10-15" \
     -H "X-Api-Key: $ALIBIT_API_KEY"

   {
     "date": "2026-10-15",
     "slots": ["2026-10-15T12:00:00.000Z", "2026-10-15T12:30:00.000Z", "…"]
   }

4. Criar (ou reaproveitar) o cliente

   O telefone é único por empresa. Se ele já existir, a resposta é 409: busque o cliente em GET /v1/clients e use o id dele.

   curl -X POST https://api.alibit.com.br/v1/clients \
     -H "X-Api-Key: $ALIBIT_API_KEY" -H "Content-Type: application/json" \
     -d '{"name":"Maria Silva","phone":"11988887777","email":"maria@exemplo.com","birthDate":"1992-04-18"}'

5. Criar o agendamento

   Use um dos horários retornados no passo 3. O término é calculado pela duração do serviço.

   curl -X POST https://api.alibit.com.br/v1/appointments \
     -H "X-Api-Key: $ALIBIT_API_KEY" -H "Content-Type: application/json" \
     -d '{"serviceId":"SERVICO_ID","clientId":"CLIENTE_ID","startTime":"2026-10-15T12:00:00.000Z","notes":"Primeira visita"}'

   Se o horário foi ocupado nesse meio tempo, a resposta é 409: consulte os horários livres de novo.

6. Reagendar, confirmar ou cancelar

   # Reagendar
   curl -X PATCH https://api.alibit.com.br/v1/appointments/AGENDAMENTO_ID/reschedule \
     -H "X-Api-Key: $ALIBIT_API_KEY" -H "Content-Type: application/json" \
     -d '{"startTime":"2026-10-16T14:00:00.000Z"}'
   
   # Mudar o status: SCHEDULED, CONFIRMED, COMPLETED ou CANCELLED
   curl -X PATCH https://api.alibit.com.br/v1/appointments/AGENDAMENTO_ID/status \
     -H "X-Api-Key: $ALIBIT_API_KEY" -H "Content-Type: application/json" \
     -d '{"status":"CANCELLED"}'

Atenção: POST /v1/appointments marca na agenda do administrador dono da chave. Para listar a agenda de toda a equipe, use GET /v1/team/appointments.

Webhooks

A empresa cadastra a URL do seu sistema no painel, em Integrações → Webhooks, e escolhe os eventos. A cada mudança na agenda, enviamos um POST com JSON para essa URL.

Exemplo de corpo:

{
  "id": "0d8f6c2e-…",
  "event": "appointment.rescheduled",
  "createdAt": "2026-10-09T13:00:00.000Z",
  "companyId": "6f1c…",
  "data": {
    "appointment": {
      "id": "…", "status": "SCHEDULED", "source": "ADMIN",
      "startTime": "2026-10-16T14:00:00.000Z", "endTime": "2026-10-16T14:30:00.000Z",
      "originalStartTime": "2026-10-15T12:00:00.000Z", "rescheduleCount": 1, "notes": null,
      "professional": { "id": "…", "name": "Ana Souza" },
      "service": { "id": "…", "name": "Corte", "durationMinutes": 30, "price": "50.00" },
      "client": { "id": "…", "name": "Maria Silva", "phone": "11988887777", "email": "maria@exemplo.com" }
    },
    "previousStartTime": "2026-10-15T12:00:00.000Z"
  }
}

Cabeçalhos enviados

Entrega e reenvio

• Responda com status 2xx em até 10 segundos. Qualquer outra resposta conta como falha.
• Em caso de falha, reenviamos depois de 1 min, 5 min, 30 min, 2 h e 12 h.
• Um evento pode chegar mais de uma vez: use o id do evento para descartar repetidos.
• A URL precisa ser https e responder direto: não seguimos redirecionamentos.
• Dica: responda 200 logo e processe o evento em segundo plano.

Conferindo a assinatura

Cada URL cadastrada tem um segredo (whsec_…) mostrado no painel. A assinatura v1 é um HMAC-SHA256, com esse segredo, de "<t>.<corpo cru>". Calcule sobre o corpo exatamente como chegou, antes de converter o JSON, e recuse mensagens com mais de 5 minutos.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function webhookValido(corpoCru, cabecalho, segredo) {
  const { t, v1 } = Object.fromEntries(cabecalho.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // mais de 5 min
  const esperado = createHmac('sha256', segredo).update(`${t}.${corpoCru}`).digest('hex');
  return v1?.length === esperado.length && timingSafeEqual(Buffer.from(v1), Buffer.from(esperado));
}

// Express: leia o corpo cru nesta rota
app.post('/webhooks/alibit', express.raw({ type: 'application/json' }), (req, res) => {
  const corpo = req.body.toString('utf8');
  if (!webhookValido(corpo, req.get('X-Webhook-Signature'), process.env.ALIBIT_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  res.sendStatus(200);
  processarEvento(JSON.parse(corpo)); // em segundo plano
});

import hashlib, hmac, time

def webhook_valido(corpo_cru: bytes, cabecalho: str, segredo: str) -> bool:
    partes = dict(p.split("=", 1) for p in cabecalho.split(","))
    t, v1 = partes.get("t", "0"), partes.get("v1", "")
    if abs(time.time() - int(t)) > 300:  # mais de 5 min
        return False
    esperado = hmac.new(segredo.encode(), f"{t}.".encode() + corpo_cru, hashlib.sha256).hexdigest()
    return hmac.compare_digest(v1, esperado)

# Flask
@app.post("/webhooks/alibit")
def receber():
    if not webhook_valido(request.get_data(), request.headers["X-Webhook-Signature"], SEGREDO):
        return "", 400
    evento = request.get_json()
    return "", 200

<?php
function webhookValido(string $corpoCru, string $cabecalho, string $segredo): bool {
    parse_str(str_replace(',', '&', $cabecalho), $partes);
    $t = (int) ($partes['t'] ?? 0);
    if (abs(time() - $t) > 300) return false; // mais de 5 min
    $esperado = hash_hmac('sha256', $t . '.' . $corpoCru, $segredo);
    return hash_equals($esperado, $partes['v1'] ?? '');
}

$corpo = file_get_contents('php://input');
if (!webhookValido($corpo, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '', getenv('ALIBIT_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit;
}
http_response_code(200);
$evento = json_decode($corpo, true);

Empresa

Profissionais

Serviços

Clientes

Agendamentos

Bloqueios

Períodos em que o profissional não atende (folga, almoço, compromisso). Somem dos horários livres.

Equipe

Visão de toda a empresa, como o administrador vê no painel.