API de marcações (integração CRM)

Se gere o seu próprio CRM, ERP ou ecrã de reservas, pode controlar as marcações do Conviro a partir daí através de uma API REST simples. As reservas via API usam o mesmo motor da reserva no chat: a disponibilidade é recalculada no servidor com base no seu horário e no calendário ligado (Google, Outlook ou feed ICS), o cliente recebe o e-mail de confirmação com ficheiro de calendário e link de gestão, e a sua equipa recebe as notificações habituais.

Pré-requisitos

1. Marcações configuradas para o seu assistente: Dashboard -> Assistants -> [o seu bot] -> Setup -> Scheduling.
2. Um calendário ligado: Google Calendar, Outlook / Microsoft 365, um feed ICS (Apple/iCloud, Fastmail, Nextcloud, ...) ou o calendário interno integrado.
3. Uma chave API com os scopes certos: Dashboard -> Settings -> API Keys; selecione Appointments Read e/ou Appointments Write.

Autenticação

Envie a chave no cabeçalho Authorization em cada pedido:

Authorization: Bearer YOUR_API_KEY

URL base: https://api.conviro.io

1. Listar horários livres

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments/slots?chatbotId=CHATBOT_ID&date=2026-07-15"

• date (opcional) — uma data local (YYYY-MM-DD) no fuso do assistente; se omitida, o próximo dia disponível.
• serviceId (opcional) — um dos serviços devolvidos na resposta.

A resposta contém timeZone, os seus services e slots como pares { start, end } em formato ISO UTC.

2. Marcar uma consulta

Requer o scope appointments:write. As reservas via API são de confiança — não é enviado OTP por e-mail, porque a identidade do cliente já está no seu sistema.

curl -X POST "https://api.conviro.io/v1/api/appointments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotId": "CHATBOT_ID",
    "startIso": "2026-07-15T09:00:00.000Z",
    "contactEmail": "[email protected]",
    "contactName": "Jane Doe",
    "contactPhone": "+31 6 00000000"
  }'

Use um startIso obtido do endpoint de horários. O servidor revalida o horário antes de marcar — se entretanto foi ocupado recebe um 400 ("já não disponível"): atualize os horários e tente de novo.

3. Listar marcações

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments?status=confirmed&limit=50"

Filtros: status (p. ex. confirmed, cancelled), limit (máx. 200), offset. Requer appointments:read.

4. Cancelar uma marcação

curl -X DELETE "https://api.conviro.io/v1/api/appointments/APPOINTMENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Requer appointments:write. Cancelar também remove o evento do calendário ligado e avisa a sua equipa.

Webhooks — mantenha o seu CRM sincronizado

Subscreva em Dashboard -> Developers -> Webhooks:

• appointment.booked — dispara em cada reserva confirmada (chat, widget de reservas ou API)
• appointment.cancelled — dispara em cada cancelamento

O payload inclui appointmentId, chatbotId, startIso, endIso, timeZone, service, contactName, contactEmail, contactPhone e channel — tudo o que precisa para espelhar a reserva no seu CRM.

Opções de calendário num relance

> Dica: As chaves API têm limite de pedidos por chave. Para grandes volumes, prefira webhooks a consultar o endpoint de listagem.