openapi: 3.1.0
info:
  title: Alina Szaputko — public discovery and AI-agent booking API
  version: 1.1.0
  description: >
    Provider-independent public API for discovering the psychologist's professional profile,
    checking free appointment slots, creating a client-authorised Stripe Checkout session,
    and verifying payment and calendar fulfilment. Any compatible AI agent or application
    can use the same API; no provider-specific agent is required. The API never accepts
    card details and never exposes calendar event details or other clients' information.
  contact:
    name: Alina Szaputko
    email: gorbachovaalina@gmail.com
  termsOfService: https://psychologwroclaw.org/zasady/
servers:
  - url: https://booking-backend-kappa-drab.vercel.app
    description: Production API
externalDocs:
  description: Complete human- and agent-readable booking instructions
  url: https://booking-backend-kappa-drab.vercel.app/agent-booking.md
tags:
  - name: Discovery
    description: Public professional and service information.
  - name: Availability
    description: Free appointment slots only; no calendar event details.
  - name: Booking
    description: Client-authorised checkout and minimal booking status.
paths:
  /api/agent-profile:
    get:
      tags: [Discovery]
      operationId: getProfessionalProfile
      summary: Retrieve the public professional profile and bookable service
      description: >
        Returns public professional details, supported languages, service scope,
        booking rules, policy links and safety boundaries. The agent-bookable service
        is an individual 60-minute online consultation in Polish or Russian.
      responses:
        '200':
          description: Public professional profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfessionalProfile'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
  /api/agent-availability:
    get:
      tags: [Availability]
      operationId: listAvailableSlots
      summary: List available online consultation slots
      description: >
        Returns only free slots for the requested date range. Times are local to
        Europe/Warsaw. Availability is indicative: a slot is not held until the
        checkout operation successfully creates a booking hold. Never infer or
        expose calendar event details.
      parameters:
        - in: query
          name: from
          required: true
          description: First date to check, as a Europe/Warsaw local calendar date.
          schema:
            type: string
            format: date
        - in: query
          name: days
          required: false
          description: Number of calendar days to check, from 1 through 14.
          schema:
            type: integer
            minimum: 1
            maximum: 14
            default: 14
      responses:
        '200':
          description: Available slots only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Availability service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
  /api/agent-checkout:
    get:
      tags: [Booking]
      operationId: getPendingConsentDetails
      summary: Retrieve booking details for an email confirmation link
      parameters:
        - in: query
          name: token
          required: true
          schema: { type: string, minLength: 40, maxLength: 60 }
      responses:
        '200':
          description: Exact booking details and links for the client to review
          content:
            application/json:
              schema: { type: object }
        '400':
          $ref: '#/components/responses/BadRequest'
        '410':
          description: Link expired or already used
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags: [Booking]
      operationId: requestConfirmConsentOrCreateCheckout
      summary: Request client consent, confirm it, or create a Stripe Checkout session
      description: >
        Use action=request to email the client, action=confirm to issue a one-time
        token after the client confirms the booking rules, privacy notice and data
        processing consent, or omit action and supply a verified consentToken to
        create Stripe Checkout.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AgentConsentRequest'
                - $ref: '#/components/schemas/AgentConsentConfirmation'
                - $ref: '#/components/schemas/AgentCheckoutRequest'
      responses:
        '200':
          description: Consent token issued or Stripe Checkout URL and opaque booking ID returned
          content:
            application/json:
              schema: { type: object }
        '202':
          description: Confirmation email sent; client action is still required
          content:
            application/json:
              schema: { type: object }
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          description: Consent token is invalid, expired, or does not match the booking details.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '409':
          description: Slot unavailable, request ID conflict, or checkout already in progress.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Consent or checkout operation failed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '503':
          description: Agent booking is disabled or an integration is unavailable.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
  /api/agent-booking-status:
    get:
      tags: [Booking]
      operationId: getPaymentAndBookingStatus
      summary: Verify payment and appointment fulfilment
      description: >
        Use the opaque booking ID returned by the checkout operation. Only bookings
        created through the AI-agent channel can be queried. A booking is confirmed
        only when both paid and confirmed are true. The response contains no contact
        details, payment credentials or calendar links.
      parameters:
        - in: query
          name: booking_id
          required: true
          description: Opaque booking ID returned by agent-checkout.
          schema:
            type: string
            pattern: '^bk_[a-f0-9]{32}$'
      responses:
        '200':
          description: Minimal payment and appointment fulfilment status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Booking not found or not created through the AI-agent channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Booking status temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
components:
  schemas:
    ProfessionalProfile:
      type: object
      required: [schemaVersion, id, name, profession, qualification, location, serviceArea, contact, languages, audience, services, booking, publicUrls, safety]
      properties:
        schemaVersion:
          type: string
          example: '1.0'
        id:
          type: string
          format: uri
          example: https://psychologwroclaw.org/#alina-szaputko
        name:
          type: string
          example: Alina Szaputko
        displayName:
          type: string
          example: Alina Szaputko
        profession:
          type: string
          example: Psychologist
        qualification:
          type: string
          example: Master's degree in psychology
        location:
          type: object
          properties:
            city: { type: string, example: Wrocław }
            region: { type: string, example: Lower Silesia }
            country: { type: string, example: Poland }
            countryCode: { type: string, example: PL }
            inPersonAvailability:
              type: string
              description: In-person service requires direct confirmation and is not bookable through this API.
        serviceArea:
          type: array
          items: { type: string }
          example: [Wrocław, Poland (in-person consultations), Online consultations worldwide]
        contact:
          type: object
          properties:
            email: { type: string, format: email }
        languages:
          type: array
          items: { type: string }
          example: [Polish, Russian]
        audience:
          type: string
        services:
          type: array
          items:
            type: object
            required: [id, name, durationMinutes, price, delivery, languages, bookableByAgent]
            properties:
              id: { type: string, example: individual-online-60 }
              name: { type: string }
              durationMinutes: { type: integer, const: 60 }
              price:
                type: object
                properties:
                  amountMinor: { type: integer, example: 16000 }
                  amount: { type: number, example: 160 }
                  currency: { type: string, example: PLN }
              delivery: { type: string, enum: [online] }
              languages:
                type: array
                items: { type: string, enum: [Polish, Russian] }
              bookableByAgent: { type: boolean, const: true }
        booking:
          type: object
          properties:
            mode: { type: string, example: direct-payment }
            bookingPage: { type: string, format: uri }
            availabilityEndpoint: { type: string }
            checkoutEndpoint: { type: string }
            statusEndpoint: { type: string }
            timeZone: { type: string, example: Europe/Warsaw }
            minimumNoticeHours: { type: integer, example: 24 }
            maximumAdvanceDays: { type: integer, example: 14 }
            workingDays:
              type: array
              items: { type: string }
            workingHours:
              type: object
              properties:
                start: { type: string, example: '09:00' }
                end: { type: string, example: '17:00' }
            paymentProvider: { type: string, example: Stripe }
            paymentRequiredToConfirm: { type: boolean, const: true }
            clientConsentRequired: { type: boolean, const: true }
            bookingScope: { type: string, example: online-consultations-only }
        publicUrls:
          type: object
          additionalProperties: true
          properties:
            website: { type: string, format: uri }
            polishPage: { type: string, format: uri }
            russianPage: { type: string, format: uri }
            bookingPage: { type: string, format: uri }
            bookingRulesPolish: { type: string, format: uri }
            bookingRulesRussian: { type: string, format: uri }
            privacyPolicy: { type: string, format: uri }
            agentBookingInstructions: { type: string, format: uri }
            openApiSpecification: { type: string, format: uri }
        safety:
          type: object
          properties:
            aiAgentsMustNotRequestClinicalHistory: { type: boolean, const: true }
            doNotCollectTherapyReason: { type: boolean, const: true }
            neverExposeCalendarEventsOrOtherClients: { type: boolean, const: true }
            doNotRepresentAvailabilityAsConfirmedUntilCheckoutAndCalendarFulfilmentComplete: { type: boolean, const: true }
        updatedAt:
          type: string
          format: date
    AvailabilityResponse:
      type: object
      required: [serviceId, from, untilExclusive, timeZone, durationMinutes, currency, slots, count, note]
      properties:
        serviceId: { type: string, example: individual-online-60 }
        from: { type: string, format: date }
        untilExclusive: { type: string, format: date }
        timeZone: { type: string, example: Europe/Warsaw }
        durationMinutes: { type: integer, const: 60 }
        currency: { type: string, example: PLN }
        slots:
          type: array
          items:
            type: object
            required: [date, time, start, end, durationMinutes, timeZone]
            properties:
              date: { type: string, format: date, description: Local Europe/Warsaw date. }
              time: { type: string, pattern: '^([01]\d|2[0-3]):[0-5]\d$', description: Local Europe/Warsaw time. }
              start: { type: string, format: date-time, description: UTC timestamp; use date and time for client display. }
              end: { type: string, format: date-time }
              durationMinutes: { type: integer, const: 60 }
              timeZone: { type: string, example: Europe/Warsaw }
        count: { type: integer, minimum: 0 }
        note: { type: string }
    AgentConsentRequest:
      type: object
      additionalProperties: false
      required: [action, name, email, date, time, consultationLanguage]
      properties:
        action: { type: string, const: request }
        name: { type: string, minLength: 2, maxLength: 100 }
        email: { type: string, format: email, maxLength: 254 }
        phone: { type: string, maxLength: 30 }
        date: { type: string, format: date }
        time: { type: string, pattern: '^([01]\d|2[0-3]):[0-5]\d$' }
        consultationLanguage: { type: string, enum: [pl, ru] }
        interfaceLanguage: { type: string, enum: [pl, ru] }
    AgentConsentConfirmation:
      type: object
      additionalProperties: false
      required: [action, pendingToken, accepted, rulesAccepted, privacyAccepted]
      properties:
        action: { type: string, const: confirm }
        pendingToken: { type: string, minLength: 40, maxLength: 60 }
        accepted: { type: boolean, const: true, description: Client explicitly accepts data processing for booking. }
        rulesAccepted: { type: boolean, const: true, description: Client accepts the booking and cancellation rules. }
        privacyAccepted: { type: boolean, const: true, description: Client confirms reading the privacy notice. }
    AgentCheckoutRequest:
      type: object
      additionalProperties: false
      required: [name, email, date, time, consultationLanguage, consentToken, requestId]
      properties:
        name: { type: string, minLength: 2, maxLength: 100 }
        email: { type: string, format: email, maxLength: 254 }
        phone: { type: string, maxLength: 30, description: Optional client phone number. }
        date: { type: string, format: date, description: Appointment date in Europe/Warsaw. }
        time: { type: string, pattern: '^([01]\d|2[0-3]):[0-5]\d$', description: Appointment start time in Europe/Warsaw. }
        consultationLanguage:
          type: string
          enum: [pl, ru]
          description: Language in which the client wants the consultation.
        interfaceLanguage:
          type: string
          enum: [pl, ru]
          description: Optional booking communication/interface language.
        duration: { type: integer, const: 60 }
        consentToken:
          type: string
          minLength: 40
          maxLength: 60
          description: Short-lived, single-use token issued only after the client confirms the exact booking details through the email link. Bound to name, email, phone, date, time and languages.
        requestId:
          type: string
          minLength: 16
          maxLength: 80
          pattern: '^[A-Za-z0-9_-]+$'
          description: Stable unique identifier for one attempt. Reuse unchanged on retries.
    CheckoutResponse:
      type: object
      required: [url, bookingId]
      properties:
        url:
          type: string
          format: uri
          description: Stripe-hosted payment page. Open this for the client; never collect card details.
        bookingId:
          type: string
          pattern: '^bk_[a-f0-9]{32}$'
        reused:
          type: boolean
          description: Present when an earlier idempotent checkout session was reused.
    BookingStatus:
      type: object
      required: [bookingId, status, paid, confirmed, appointment]
      properties:
        bookingId: { type: string, pattern: '^bk_[a-f0-9]{32}$' }
        status:
          type: string
          enum: [payment_pending, payment_processing, confirmed, refunded, expired, cancelled, failed, processing]
        paid: { type: boolean }
        confirmed: { type: boolean }
        appointment:
          type: object
          required: [date, time, durationMinutes, timeZone]
          properties:
            date: { type: string, format: date }
            time: { type: string, pattern: '^([01]\d|2[0-3]):[0-5]\d$' }
            durationMinutes: { type: integer, const: 60 }
            timeZone: { type: string, example: Europe/Warsaw }
    Error:
      type: object
      required: [error, message]
      properties:
        error: { type: string }
        message: { type: string }
  responses:
    BadRequest:
      description: Invalid input, missing consent, or malformed request.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: Too many requests. Respect the rate limit and retry later.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    MethodNotAllowed:
      description: HTTP method not supported.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
