API wizyt (integracja z CRM)

Jeśli prowadzisz własny CRM, ERP lub ekran rezerwacji, możesz sterować wizytami Conviro przez proste API REST. Rezerwacje przez API korzystają z tego samego silnika co rezerwacja w czacie: dostępność jest przeliczana po stronie serwera na podstawie godzin pracy i podłączonego kalendarza (Google, Outlook lub feed ICS), klient otrzymuje e-mail z potwierdzeniem, plikiem kalendarza i linkiem do zarządzania, a Twój zespół — zwykłe powiadomienia.

Wymagania wstępne

1. Wizyty skonfigurowane dla asystenta: Dashboard -> Assistants -> [twój bot] -> Setup -> Scheduling.
2. Podłączony kalendarz: Google Calendar, Outlook / Microsoft 365, feed ICS (Apple/iCloud, Fastmail, Nextcloud, ...) lub wbudowany kalendarz wewnętrzny.
3. Klucz API z odpowiednimi zakresami: Dashboard -> Settings -> API Keys; zaznacz Appointments Read i/lub Appointments Write.

Uwierzytelnianie

Wysyłaj klucz w nagłówku Authorization przy każdym żądaniu:

Authorization: Bearer YOUR_API_KEY

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

1. Pobierz wolne terminy

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

• date (opcjonalnie) — lokalna data (YYYY-MM-DD) w strefie czasowej asystenta; bez niej najbliższy dostępny dzień.
• serviceId (opcjonalnie) — jedna z usług zwróconych w odpowiedzi.

Odpowiedź zawiera timeZone, twoje services oraz slots jako pary { start, end } w formacie ISO UTC.

2. Zarezerwuj wizytę

Wymaga zakresu appointments:write. Rezerwacje przez API są zaufane — nie wysyłamy OTP e-mailem, bo tożsamość klienta jest już w Twoim systemie.

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

Użyj startIso z endpointu terminów. Serwer ponownie waliduje termin przed rezerwacją — jeśli w międzyczasie został zajęty, otrzymasz 400 ("już niedostępny"): odśwież terminy i spróbuj ponownie.

3. Wyświetl wizyty

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

Filtry: status (np. confirmed, cancelled), limit (maks. 200), offset. Wymaga appointments:read.

4. Anuluj wizytę

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

Wymaga appointments:write. Anulowanie usuwa też wydarzenie z podłączonego kalendarza i powiadamia zespół.

Webhooki — synchronizuj swój CRM

Subskrybuj w Dashboard -> Developers -> Webhooks:

• appointment.booked — uruchamia się przy każdej potwierdzonej rezerwacji (czat, widżet rezerwacji lub API)
• appointment.cancelled — uruchamia się przy każdym anulowaniu

Payload zawiera appointmentId, chatbotId, startIso, endIso, timeZone, service, contactName, contactEmail, contactPhone i channel — wszystko, czego potrzeba, by odwzorować rezerwację w CRM.

Opcje kalendarza w skrócie

> Wskazówka: Klucze API mają limit żądań na klucz. Przy dużych wolumenach wybierz webhooki zamiast odpytywania endpointu listy.