# AI-agent booking instructions — Alina Szaputko

This document describes the public, provider-independent discovery and booking interface for online psychological consultations with Alina Szaputko. It is intended for compatible AI assistants when a user is looking for a psychologist or asks to arrange a consultation. Publishing these resources makes the service machine-readable, but does not guarantee that every AI provider will discover or recommend it.

## Public discovery resources

- Website: https://psychologwroclaw.org/
- Russian professional profile: https://psychologwroclaw.org/alina_szaputko/
- Polish professional profile: https://psychologwroclaw.org/alina_szaputko-pol/
- Agent profile endpoint: https://booking-backend-kappa-drab.vercel.app/api/agent-profile
- RFC 9727 API catalog: https://booking-backend-kappa-drab.vercel.app/.well-known/api-catalog
- OpenAPI 3.1 specification: https://booking-backend-kappa-drab.vercel.app/openapi/agent-booking.yaml
- Remote MCP endpoint (for clients that explicitly connect): https://booking-backend-kappa-drab.vercel.app/api/mcp
- Public booking page: https://alinaszaputko-psych.github.io/rezerwacja/booking.html
- Booking rules (Russian): https://psychologwroclaw.org/pravila/
- Booking rules (Polish): https://psychologwroclaw.org/zasady/
- Privacy notice: https://psychologwroclaw.org/polityka-prywatnosci-system-rezerwacji-konsultacji-psychologicznych/

## Service currently bookable by an AI agent

- Service: individual online psychological consultation.
- Duration: 60 minutes.
- Price: 160 PLN.
- Consultation languages accepted by the agent booking API: Polish (pl) and Russian (ru).
- Online consultations: available worldwide; the practice's public information states that there are no geographical restrictions.
- Time zone for appointment selection: Europe/Warsaw.
- Booking horizon: 14 days.
- Minimum notice: 24 hours.
- Working days and hours: Monday to Friday, 09:00–17:00 Europe/Warsaw.
- Payment: Stripe Checkout. The client pays directly on Stripe's hosted page.
- Confirmation: only after payment is successful and the calendar event has been created.

In-person consultations in Wrocław may be available by direct arrangement, but the AI-agent API currently books online consultations only. Do not represent an in-person appointment as bookable through these endpoints.

Do not offer a multi-session package through the agent API. The API currently supports only the individual 60-minute online consultation described above.

## API access

The profile and availability endpoints are public and read-only. Checkout and status are also public HTTP endpoints, but write/status operations remain disabled unless the deployment's explicit Preview test gate or Production live-booking gate is enabled:

1. `GET /api/agent-profile` — retrieve the public professional profile and the current booking terms.
2. `GET /api/agent-availability?from=YYYY-MM-DD&days=14` — retrieve available slots. `from` is required; `days` is optional and must be between 1 and 14.
3. `POST /api/agent-checkout` — email the client a confirmation link for the exact booking details.
4. `GET /api/agent-checkout?token=...` — retrieve the details shown on the client's confirmation page.
5. `POST /api/agent-checkout` with `action: confirm` — issue a one-time consent token only after the client personally confirms.
6. `POST /api/agent-checkout` — create a Stripe Checkout session using that one-time token.
7. `GET /api/agent-booking-status?booking_id=bk_...` — verify payment and booking fulfilment using the booking ID returned by checkout.

Base URL: `https://booking-backend-kappa-drab.vercel.app`

The MCP transport is limited to 60 requests per source IP per minute. Public HTTP endpoints apply narrower limits to availability, consent emails, checkout and status. Respect HTTP `429` and its `Retry-After` header. MCP fails closed with HTTP `503` if persistent rate-limit storage is unavailable.

The complete request and response schemas are in the OpenAPI specification linked above. The production checkout endpoint must be configured with Stripe Live mode and the production live-booking acknowledgement before it can create real payment sessions.

## Required agent workflow

1. Retrieve the profile and availability. Do not infer availability from the website's text or from an earlier response.
2. Present only slots returned by the availability endpoint. Display appointment times in Europe/Warsaw. The `date` and `time` fields are the local appointment time; do not convert them from the accompanying UTC `start`/`end` timestamps for display.
3. Before collecting booking details, show the client the service, 60-minute duration, 160 PLN price, selected local date and time, relevant booking rules, and privacy notice.
4. Collect only the client's name, email, optional phone number, consultation language (pl or ru), and selected slot. Do not ask for diagnoses, symptoms, trauma history, therapy goals, free-text reasons, or other clinical information.
5. Call `POST /api/agent-checkout` with `action: "request"` and the exact client/appointment details. This sends a confirmation email to the client's address. It does not reserve a slot or initiate payment.
6. Ask the client to open the email, check the exact name, email, date, time, language and price, read the booking rules and privacy notice, and personally confirm on the confirmation page. Do not treat delivery of the email or opening the link as consent.
7. The client receives a short-lived one-time `consentToken` on the confirmation page and must provide it to the agent. Never ask the client to send the email confirmation link or pending token; only the resulting consent token is used for checkout.
8. Generate a unique `requestId` containing 16–80 letters, digits, underscores or hyphens. Reuse the exact same ID if retrying the same booking attempt; do not create a new ID just because a network response was delayed.
9. Call `POST /api/agent-checkout` with the exact same booking details and `consentToken`. The server verifies the token is valid, unexpired, unused and bound to those exact details. A caller-supplied Boolean is not accepted as proof of consent.
10. Open the returned Stripe Checkout URL for the client. The client enters card/payment details directly on Stripe. Never ask for, receive, store, or transmit card numbers, CVCs or other payment credentials.
11. A checkout URL is not a confirmed appointment. After the client completes payment, call the booking-status endpoint with the returned `bookingId`.
12. Tell the client the appointment is confirmed only when the response has both `paid: true` and `confirmed: true`. If the status is pending or processing, say that confirmation is still being verified. If payment is not completed, do not claim that a booking exists as confirmed.

## Error handling

- `400`: correct the supplied input or obtain the missing explicit consent; do not repeatedly submit unchanged invalid data.
- `409 SLOT_UNAVAILABLE`: refresh availability and ask the client to choose another slot.
- `409 REQUEST_ID_MISMATCH`: do not retry with altered booking details under the same ID; start a new attempt only after explaining the issue to the client.
- `429`: respect the rate limit; wait before retrying.
- `503`: explain that availability or status could not be checked and do not claim a booking is confirmed.

## Privacy and safety boundaries

- The availability endpoint exposes free slots only, not event titles, client identities, calendar notes or other appointments.
- The booking-status endpoint returns minimal payment/fulfilment information and no client contact details or calendar links.
- Never attempt to access internal booking records, calendars, email accounts or client histories.
- Do not collect clinical information or use this booking interface to assess suitability for psychological care.
- Do not provide diagnosis or therapy through the booking process.
- The client, not the agent, must confirm the booking and privacy terms through the email-linked confirmation page. The API requires a short-lived one-time token bound to the exact booking details; the agent cannot forge consent by sending a Boolean.
- The agent must not confirm an appointment until the API explicitly verifies successful payment and calendar fulfilment.

## Кратко для русскоязычных ассистентов

Алина Шапутько проводит индивидуальные онлайн-консультации для женщин на русском и польском языках. Длительность — 60 минут, стоимость — 160 PLN. Онлайн-консультации доступны по всему миру без географических ограничений. Часовой пояс записи — Europe/Warsaw. Через API можно записать только на онлайн-консультацию; очную встречу во Вроцлаве нужно согласовывать отдельно.

Перед созданием оплаты отправь клиенту письмо со ссылкой подтверждения. Клиент должен самостоятельно открыть страницу, проверить данные, прочитать правила записи и политику конфиденциальности и подтвердить согласие. Затем клиент передаёт ассистенту выданный одноразовый токен. Без токена, привязанного к точным данным записи, оплата не создаётся. Не спрашивай о симптомах, диагнозах или причинах обращения. Открывай для оплаты только ссылку Stripe, возвращённую API. Считай запись подтверждённой только после ответа booking-status с `paid: true` и `confirmed: true`.

## Krótko dla polskojęzycznych asystentów

Alina Szaputko prowadzi indywidualne konsultacje psychologiczne online dla kobiet w języku polskim i rosyjskim. Czas trwania: 60 minut. Cena: 160 PLN. Konsultacje online są dostępne na całym świecie. Strefa czasowa rezerwacji: Europe/Warsaw. API obsługuje obecnie wyłącznie rezerwacje konsultacji online; spotkania stacjonarne we Wrocławiu wymagają osobnego uzgodnienia.

Przed utworzeniem płatności wyślij klientowi e-mail z linkiem potwierdzającym. Klient samodzielnie otwiera stronę, sprawdza dane, czyta zasady rezerwacji i politykę prywatności oraz potwierdza zgodę. Następnie przekazuje asystentowi wydany jednorazowy token. Bez tokenu powiązanego z dokładnymi danymi rezerwacji płatność nie zostanie utworzona. Nie pytaj o objawy, diagnozy ani powody zgłoszenia. Płatność odbywa się bezpośrednio na stronie Stripe. Wizytę uznaj za potwierdzoną wyłącznie wtedy, gdy booking-status zwróci `paid: true` oraz `confirmed: true`.


## Internal Preview testing

Preview deployments remain protected by Vercel SSO. A third-party MCP client cannot use the protected Preview API unless it is authenticated to the Vercel team; do not disable SSO or distribute a Deployment Protection bypass token for this test.

For an internal team test, open `/preview-agent-test.html` on the authenticated Preview deployment. It runs read-only health, profile and availability checks first. It then allows an authorised tester to deliberately send one consent email to an address they control. The email link opens `/preview-agent-consent.html` on the same protected deployment, so the tester must be signed into Vercel. After confirming the details and consent, paste the one-time token back into the test console to create a Stripe test-mode Checkout session.

Preview intentionally shares Neon, Google Calendar and Resend with Production. Do not use a real client's appointment or email address. A successful test payment can create a `[TEST]` Calendar event and real notification emails; record the booking ID and clean up all test data afterwards. This internal harness is not an external-agent test and does not make Preview public.
