API gabinetu MentAI (v1)

Własny klucz gabinetu. Odczyt wizyt, klientów, usług, terapeutów i wolnych terminów oraz tworzenie rezerwacji z Twoich narzędzi: strony, arkusza, automatyzacji, własnego systemu. Bez danych klinicznych.

Klucz generuje Administrator w panelu: Ustawienia → API dla integracji. Klucz widać tylko raz. Działa jak hasło do całego gabinetu w zakresie Administratora, z wyłączeniem modułu klinicznego (karty, załączniki, nagrania, notatki kliniczne nie są dostępne przez API). Nowy klucz unieważnia poprzedni; „Cofnij klucz” wyłącza dostęp natychmiast.

Osobny tor bez klucza: publiczna rezerwacja dla agentów AI i integracji. Każdy gabinet ma publiczny tor rezerwacji (wolne terminy + prośba o wizytę), opisany maszynowo w OpenAPI publicznego toru rezerwacji i w katalogu /.well-known/api-catalog. Instrukcja dla asystentów AI: llms.txt, sekcja „Jak umówić wizytę przez agenta AI". Klucz gabinetu opisany niżej daje więcej: odczyt wizyt, klientów i tworzenie rezerwacji z własnych narzędzi.

Podstawy

Adres bazowy	`https://02lw3esaj9.execute-api.eu-central-1.amazonaws.com/api/v1`
Uwierzytelnianie	nagłówek `Authorization: Bearer mentai_…` albo `x-api-key: mentai_…`
Format	JSON, UTF-8, daty w czasie polskim jako `YYYY-MM-DDTHH:MM`, kwoty w groszach (`20000` = 200,00 zł)
Limity	60 wywołań na minutę (`429 api_minute_limit`, pole `retryAfterSeconds`) oraz dziennie na klucz: 500 w okresie testowym, 2000 w abonamencie (`429 api_daily_limit`)
Błędy	`{"ok": false, "error": "kod"}`; `401 invalid_api_key`, `404 not_found`, `409 booking_disabled`
Dane	serwery AWS w UE (Frankfurt); API nie zwraca danych klinicznych

curl -H "Authorization: Bearer mentai_TWOJ_KLUCZ" \
  https://02lw3esaj9.execute-api.eu-central-1.amazonaws.com/api/v1/gabinet

Endpointy

GET /api/v1/gabinet

Dane gabinetu (nazwa, adres, kolor, notatki dla klientów), slug i adres strony rezerwacji, czy rezerwacja online jest włączona, włączone moduły.

GET /api/v1/services

Usługi ze strony rezerwacji: serviceId, nazwa, czas trwania, cena, adresat, flagi qualificationRequired, firstVisitWithoutChild, online.

GET /api/v1/therapists

Aktywni terapeuci: therapistId, imię, oferowane usługi i ceny.

GET /api/v1/availability

Wolne terminy z grafiku. Parametry: serviceId (wymagany do długości slotu), therapistId (opcjonalnie), from, to (YYYY-MM-DD). Wymaga włączonej rezerwacji online w panelu; inaczej 409 booking_disabled.

GET /api/v1/availability?serviceId=bs-xxx&from=2026-09-08&to=2026-09-14

GET /api/v1/visits

Wizyty gabinetu (do 500, najnowsze pierwsze). Filtry: from, to (po dacie wizyty), contactId, status (zaplanowana, potwierdzona, odbyta, odwolana, no_show, …). Każda wizyta: termin, status, usługa, terapeuta, kontakt (alias), rozliczenie, tryb (gabinet / online).

GET /api/v1/visits/{visitId}

Jedna wizyta.

GET /api/v1/contacts

Klienci z kartoteki (do 500). Filtry: query (fragment nazwy), tag (etykieta), archived=1 (z archiwum). Pola jak w panelu: alias, typ, opiekunowie, kontakt, dane nabywcy, zgoda RODO, etykiety, uwagi organizacyjne, preferowana forma wizyt.

GET /api/v1/contacts/{contactId}

Widok klienta: karta, liczby (odbyte, nieobecności, odwołane, zaplanowane, ostatnia i następna wizyta, wartość i wpłaty), oś czasu (wizyty, dokumenty, zgody, komunikacja, zadania), zadania, wpisy listy rezerwowej.

POST /api/v1/bookings

Nowa rezerwacja tym samym torem co publiczna strona rezerwacji: te same reguły (wolny slot, kwalifikacja, zgoda RODO, kanał przypomnień), ta sama izolacja danych osobowych, te same potwierdzenia dla klienta i gabinetu. Rezerwacja czeka na akceptację gabinetu, chyba że panel ma włączone auto-akceptowanie.

POST /api/v1/bookings
{
  "serviceId": "bs-xxx",
  "therapistId": "t-xxx",            // opcjonalnie
  "slotStart": "2026-09-10T10:00",
  "name": "Anna Nowak",
  "contactPhone": "+48600100200",
  "contactEmail": "anna@example.com",
  "reminderChannel": "sms",          // email | sms | whatsapp
  "rodoConsent": true,
  "visitMode": "online",             // tylko gdy usługa ma online: true i gabinet ma telewizyty
  "reason": "konsultacja",           // opcjonalnie
  "patientName": "…", "patientAge": "…"   // gdy wizyta dla dziecka
}

Odpowiedź: {"ok": true, "visitId": "…", …}. Błędy jak na stronie rezerwacji: slot_unavailable, service_not_found, qualification_required, phone_required, online_not_available.

Bezpieczeństwo i RODO

Klucz przechowujemy wyłącznie jako skrót kryptograficzny; nie da się go odczytać ponownie z panelu.
Gabinet odpowiada za narzędzia, którym powierza klucz, i za dane, które nimi pobiera (regulamin, sekcja o kluczu API). Integracje działają w ramach umowy powierzenia.
Każde wywołanie liczy się do limitów minutowego i dziennego; użycie widać w panelu (liczba wywołań dziś, ostatnie użycie).
Administrator gabinetu dostaje e-mail przy każdym wygenerowaniu i cofnięciu klucza (bez treści klucza, tylko prefiks).
Dane kliniczne nigdy nie są dostępne przez API. To celowe ograniczenie, nie brak.

Co dalej

W kolejnych wersjach: webhooki (nowa rezerwacja, odwołanie, płatność), zapis zadań i etykiet klienta przez API. Napisz, czego potrzebujesz: kontakt@mentai.pl.