ZnanyLekarz Calendar Breaks API

openapi: 3.2.0
info:
  title: Docplanner Integrations Calendar Breaks API
  description: 'Welcome to Docplanner Integrations REST API!


    This API gives You the ability to build Your own application and integrate it with Docplanner services.'
  version: 1.14.0
  x-logo:
    url: https://docplanner.tech/logo.svg
    backgroundColor: '#012c6d'
    altText: Docplanner Tech
  x-changelog:
    1.14.0: '* Introducing new optional **apply_on_coupled_addresses** field in **AddCalendarBreakRequest** for creating the same break on the doctor''s coupled addresses in the facility

      * **moveCalendarBreak** and **deleteCalendarBreak** now move and remove those coupled breaks together with the break they follow

      '
    1.13.0: '* **moveBooking** may now move a booking to an **address_id** belonging to a different doctor within the same facility, reassigning the booking to that doctor. An address outside the facility named in the path is still rejected with **403**

      * **moveBooking** returns **422 Unprocessable Entity** when the booking still holds money and the target address is billed through a different payment account. Cancel the booking and create a new one instead. A payment that was fully refunded or charged back holds no money, so it does not restrict the move

      '
    1.12.0: '* Documenting **price** in **AddAddressServiceRequest** and **UpdateAddressServiceRequest** as a number with up to 2 decimal places; invalid price formats now return a **400 Bad Request** error

      '
    1.11.0: '* Introducing new **removeAddressIntegration** endpoint for DocplannerPMS API clients

      '
    1.10.0: '* Introducing new optional **custom_name** field in **AddAddressServiceRequest** and **UpdateAddressServiceRequest** for creating and updating address services with custom display names

      '
    1.9.3: '* Adding maximum date range validation of 180 days to **getSlots** endpoint. Requests exceeding this range will return a **400 Bad Request** error

      '
    1.9.2: '* Introducing new optional **specialization_id** query parameter in **getServices** endpoint

      '
    1.9.1: '* Making **price** and **description** fields in **UpdateAddressServiceRequest** nullable as they are not required

      '
    1.9.0: '* Introducing new **confirmBooking** endpoint

      '
    1.8.1: '* Introducing new **insurance_number** field in **Patient** schema for booking related notifications and endpoints

      '
    1.8.0: '* Introducing new **address_service.public_insurance_flow** scope for **getBookings** endpoint

      * Introducing new **address_service.public_insurance_flow** scope for **getBooking** endpoint

      * Introducing new **address_service.public_insurance_flow** scope for **getAddressServices** endpoint

      * Introducing new **address_service.public_insurance_flow** scope for **getAddressService** endpoint

      '
    1.7.1: '* Introducing new optional **insurance_plans** field in **addAddressInsuranceProvider** endpoint

      '
    1.6.1: '* Introducing new **address_service.custom_name** scope for **getAddressService** and **getAddressServices** endpoints.

      '
    1.5.0: '* Introducing new optional **allowed_patients** field with **minimum_age** and **maximum_age** properties in **AddAddressServiceRequest**, **UpdateAddressServiceRequest**, and **AddressService** schema for age restrictions

      '
    1.4.8: '* Improved error message clarity for calendar breaks endpoints.

      '
    1.4.7: '* Fixed **addAddressService** and **addCalendarBreak** response not having body

      '
    1.4.6: '* Documentation: Added IP whitelisting endpoints information for partners receiving webhooks

      '
    1.4.5: "* Marking **name**, **city_name** and **street** fields in **Address** schema as nullable  \n"
    1.4.4: '* Fixed **license_number** field name in **DoctorsWithLicenseNumbers** example for **getDoctors** endpoint

      '
    1.4.3: '* Add **city_name** field information for **Addresses** endpoints.

      '
    1.4.2: '* Fixed issue with **getBooking** endpoint in PHP SDK

      '
    1.4.1: '* Introducing new **booking.confirmation** scope for **getBookings** endpoint

      '
    1.4.0: '* Introducing new **booking.moving** scope for **getBooking** endpoint

      '
    1.3.3: '* Fixing **insurance** schema in booking callback notifications

      '
    1.3.2: '* Introducing new optional **is_recurring** field in **bookSlot** endpoint

      '
    1.3.1: '* Making **price** in **AddAddressServiceRequest** field nullable as it''s not required

      '
    1.3.0: '* Introducing new optional **insurance_provider_id** and **insurance_plan_id** fields in **bookSlot** endpoint

      '
    1.2.0: '* Introducing new optional is_visible field in updateAddressService endpoint

      '
    1.0.40: '* Marking **address_service** and **insurance** fields in **getBooking** endpoint response as nullable             * Marking **address_service** field in **getSlots** endpoint response as nullable * Marking **address_service** and **insurance** fields in booking related callback notifications as nullable

      '
    1.0.39: '* Deprecated **videocall_url** field in **getBookings** endpoint

      '
    1.0.38: '* Deprecated **send_notifications** field in **BookSlot** and **CancelBookingRequest**

      '
    1.0.37: '* Adding 422 response status code in **bookSlot** endpoint

      '
    1.0.36: '* Adding **booking-payment-status-changed** callback

      '
    1.0.35: '* Introducing new optional **comment** field on **bookSlot** endpoint

      '
    1.0.34: '* PHP SDK without dependencies on GuzzleHttp building query method.

      '
    1.0.33: '* Fixed **Error** schema

      '
    1.0.32: '* Added **address-assigned** and **address-unassigned** callbacks

      '
    1.0.31: '* Added optional pagination to **getBookings** endpoint

      '
    1.0.30: '* Changed **errors* field type in the **Error** schema

      '
    1.0.29: '* Adding **address-commercial-type-changed** callback

      '
    1.0.28: '* Introducing new optional **marketing_consent** and **data_privacy_consent** fields on **bookSlot** endpoint

      '
    1.0.27: '* Introducing new optional **label** field on **bookSlot** endpoint

      '
    1.0.26: '* Introducing **address.insurance_support** scope for **getAddress** and **getAddresses** endpoints * Introducing **updateAddress** endpoint for changing insurance support type of an address

      '
    1.0.25: '* Introducing **getCalendar** endpoint for getting calendar status

      '
    1.0.24: '* Introducing **address.commercial_type** scope for **getAddress**, **getAddresses** and **getDoctor** endpoints

      '
    1.0.23: '* Added "address-service-created", "address-service-deleted", "address-service-changed" callbacks

      '
    1.0.22: '* Introducing **doctor.profile_url** scope for **getDoctor** and **getDoctors** endpoints

      '
    1.0.21: '* Added missing **insuranceProviderId** property to **getInsurancePlans** operation  * Renamed **insurance_provider** parameter to **insurance_provider_id** in **deleteAddressInsuranceProvider** operation * Renamed **OAuth 2.0** security scheme to **oauth2** * Fixed minor syntax error * Renamed invalid **docplanner.it** domain to **miodottore.it** in the description

      '
    1.0.20: '* New (optional) property **default_duration** for **AddAddressServiceRequest** and **UpdateAddressServiceRequest**

      '
    1.0.19: '* Added "booking-confirmed" callback

      '
    1.0.18: '* Added support for insurance plans

      '
    1.0.17.1: '* Added missing is_visible property to **AddAddressServiceRequest** example payload

      '
    1.0.17: '* Introduced **Pull Multiple Notifications** endpoint

      '
    1.0.16: '* New (optional) property **is_visible** for **AddAddressServiceRequest**

      '
    1.0.15: '* New (optional) property **reason** for **CancelBookingRequest** (it is now possible to set a reason why booking was canceled)

      '
    1.0.14.1: '* Added missing is_visible property to responses and examples

      '
    1.0.14: '* Added support for custom services and is_visible property of AddressService

      '
    1.0.13: '* Creating calendar in **addCalendarBreak** when it''s missing.

      '
    1.0.12: '* Returning whole Booking on moveBooking action.

      '
    1.0.11: '* Added **insurance_accepted** and **insurance_providers** fields to **ReplaceSlotsRequest** (support for insurances configuration)

      '
    1.0.10: '* Introducing **doctor.license_numbers** scope for **getDoctor** and **getDoctors** endpoints

      '
    1.0.9: '* Added Calendars API * Added methods to enable and disable calendar on the address

      '
    1.0.8: '* New (optional) property **send_notifications** for **CancelBookingRequest** (it is now possible to set if the patient should get notifications on canceling the visit)

      '
    1.0.7: '* Buried notifications can be released: added **releaseNotifications** method

      '
    1.0.6: '* Making **patient.surname** field optional in *BookSlotRequest*

      '
    1.0.5: '* Removing **slot-changed** notification callback.

      '
    1.0.4: '* New (optional) property **address_id** for **MoveBookingRequest** (it is now possible to move booking to another address) * Changed **address_service_id** and **start** properties of **MoveBookingRequest** so they are required (documentation was missing it, they were already required in the API)

      '
    1.0.3: '* New (optional) property **description** for **AddCalendarBreakRequest** * New property **description** for **CalendarBreak**

      '
    1.0.2: '* Calendar breaks can be moved: adding **moveCalendarBreak** method for **CalendarBreaksApi** * New notification callback **break-moved**

      '
    1.0.1: '* Notification callbacks * IDs are now strings instead of integers

      '
servers:
- url: https://www.{domain}/api/v3/integration
  description: \{domain} - locale of docplanner marketplace ex. znanylekarz.pl
security:
- oauth2:
  - integration
tags:
- name: Calendar Breaks
  description: More information on how we define what a Calendar Breaks is, its use cases and more can be found here.
paths:
  /facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/breaks:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    - $ref: '#/components/parameters/addressId'
    get:
      parameters:
      - name: since
        in: query
        required: true
        schema:
          type: string
          format: date-time
          example: '2021-05-16T14:00:00+01:00'
      - name: till
        in: query
        required: true
        schema:
          type: string
          format: date-time
          example: '2021-05-16T15:00:00+01:00'
      operationId: getCalendarBreaks
      description: Get the list of calendar breaks
      tags:
      - Calendar Breaks
      responses:
        '200':
          description: List of calendar breaks
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CalendarBreaks'
              examples:
                Calendar break:
                  $ref: '#/components/examples/CalendarBreak'
        '403':
          description: You are not authorized to see this resource
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Facility:
                  $ref: '#/components/examples/FacilityNotAuthorized'
                Doctor:
                  $ref: '#/components/examples/DoctorNotAuthorized'
                Address:
                  $ref: '#/components/examples/AddressNotAuthorized'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Calendar not found for this address:
                  $ref: '#/components/examples/CalendarNotFoundForAddress'
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
                Invalid date parameter:
                  $ref: '#/components/examples/InvalidDate'
      summary: Get calendar breaks
      x-summary-source: derived
    post:
      operationId: addCalendarBreak
      description: Add a new break to the calendar
      tags:
      - Calendar Breaks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCalendarBreakRequest'
      responses:
        '201':
          description: Break added to the calendar
          headers:
            Location:
              schema:
                type: string
              description: Resource URL for the new calendar break
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CalendarBreak'
              examples:
                Calendar break:
                  $ref: '#/components/examples/CalendarBreak'
        '400':
          description: Validation of the submitted values wasn't successful
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Parameter required (since):
                  $ref: '#/components/examples/ParameterRequiredSince'
                Parameter required (till):
                  $ref: '#/components/examples/ParameterRequiredTill'
        '403':
          description: You are not authorized to see this resource
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Facility:
                  $ref: '#/components/examples/FacilityNotAuthorized'
                Doctor:
                  $ref: '#/components/examples/DoctorNotAuthorized'
                Address:
                  $ref: '#/components/examples/AddressNotAuthorized'
                Calendar edition:
                  $ref: '#/components/examples/CalendarEditionNotAuthorized'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
        '409':
          description: Request would result in creating conflicted or duplicated resources
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Calendar break:
                  $ref: '#/components/examples/CalendarBreakAlreadyExists'
        '422':
          description: Request cannot be processed
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid date range given:
                  $ref: '#/components/examples/InvalidDateRange'
                Doctor/address is not commercial:
                  $ref: '#/components/examples/DoctorOrAddressNotCommercial'
      summary: Add calendar break
      x-summary-source: derived
  /facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/breaks/{break_id}:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    - $ref: '#/components/parameters/addressId'
    - $ref: '#/components/parameters/breakId'
    get:
      operationId: getCalendarBreak
      description: View a specific calendar break
      tags:
      - Calendar Breaks
      responses:
        '200':
          description: Calendar break
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CalendarBreak'
              examples:
                Calendar break:
                  $ref: '#/components/examples/CalendarBreak'
        '403':
          description: You are not authorized to see this resource
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Facility:
                  $ref: '#/components/examples/FacilityNotAuthorized'
                Doctor:
                  $ref: '#/components/examples/DoctorNotAuthorized'
                Address:
                  $ref: '#/components/examples/AddressNotAuthorized'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Calendar not found for this address:
                  $ref: '#/components/examples/CalendarNotFoundForAddress'
                Break not found:
                  $ref: '#/components/examples/BreakNotFoundForGivenAddress'
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
      summary: Get calendar break
      x-summary-source: derived
    patch:
      operationId: moveCalendarBreak
      description: 'Move the calendar break


        If the break was created with **apply_on_coupled_addresses**, the breaks created alongside it on the doctor''s coupled addresses in this facility are moved to the same new time range.'
      tags:
      - Calendar Breaks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveCalendarBreakRequest'
      responses:
        '204':
          description: Successfully moved calendar break
        '400':
          description: Validation of the submitted values wasn't successful
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Parameter required (since):
                  $ref: '#/components/examples/ParameterRequiredSince'
                Parameter required (till):
                  $ref: '#/components/examples/ParameterRequiredTill'
        '403':
          description: You are not authorized to see this resource
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Facility:
                  $ref: '#/components/examples/FacilityNotAuthorized'
                Doctor:
                  $ref: '#/components/examples/DoctorNotAuthorized'
                Address:
                  $ref: '#/components/examples/AddressNotAuthorized'
                Calendar edition:
                  $ref: '#/components/examples/CalendarEditionNotAuthorized'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Calendar not found for this address:
                  $ref: '#/components/examples/CalendarNotFoundForAddress'
                Break not found:
                  $ref: '#/components/examples/BreakNotFoundForGivenAddress'
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
        '422':
          description: Request cannot be processed
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Same date range:
                  $ref: '#/components/examples/SameDateRange'
                Till cannot be earlier than since:
                  $ref: '#/components/examples/TillEarlierThanSince'
      summary: Move calendar break
      x-summary-source: derived
    delete:
      operationId: deleteCalendarBreak
      description: 'Delete the calendar break


        If the break was created with **apply_on_coupled_addresses**, the breaks created alongside it on the doctor''s coupled addresses in this facility are removed as well.'
      tags:
      - Calendar Breaks
      responses:
        '204':
          description: Successfully removed calendar break
        '403':
          description: You are not authorized to see this resource
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Facility:
                  $ref: '#/components/examples/FacilityNotAuthorized'
                Doctor:
                  $ref: '#/components/examples/DoctorNotAuthorized'
                Address:
                  $ref: '#/components/examples/AddressNotAuthorized'
                Calendar edition:
                  $ref: '#/components/examples/CalendarEditionNotAuthorized'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Calendar not found for this address:
                  $ref: '#/components/examples/CalendarNotFoundForAddress'
                Break not found:
                  $ref: '#/components/examples/BreakNotFoundForGivenAddress'
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
      summary: Delete calendar break
      x-summary-source: derived
components:
  examples:
    ParameterRequiredSince:
      value:
        errors: []
        message: Param "since" is required!
    CalendarEditionNotAuthorized:
      value:
        errors: []
        message: You are not authorized to make changes on this calendar
    ObjectNotFound:
      value:
        errors: []
        message: Object not found
    CalendarBreakAlreadyExists:
      value:
        errors: []
        message: Break for given address, date range and description exists
    AddressNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this address
    FacilityNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this facility
    InvalidDate:
      value:
        errors: []
        message: Invalid date given.
    CalendarBreak:
      value:
        id: '567'
        since: '2020-12-16T14:00:00+01:00'
        till: '2020-12-16T14:30:00+01:00'
        description: Optional description
    TillEarlierThanSince:
      value:
        errors: []
        message: Till (%s) cannot be set before since (%s)
    SameDateRange:
      value:
        errors: []
        message: Same Date Range
    BreakNotFoundForGivenAddress:
      value:
        errors: []
        message: Invalid break ID
    CalendarNotFoundForAddress:
      value:
        errors: []
        message: Calendar not found for this address
    ParameterRequiredTill:
      value:
        errors: []
        message: Param "till" is required!
    DoctorNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this doctor
    InvalidDateRange:
      value:
        errors: []
        message: Invalid date range
    DoctorOrAddressNotCommercial:
      value:
        errors: []
        message: Cannot activate calendar on address 123, profile/address is not commercial
  schemas:
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
        message:
          type: string
    CalendarBreak:
      type: object
      properties:
        id:
          type: string
          example: 1714456
        since:
          type: string
          format: date-time
          example: '2021-05-16T14:00:00+01:00'
        till:
          type: string
          format: date-time
          example: '2021-05-16T15:00:00+01:00'
        description:
          type:
          - string
          - 'null'
          example: Optional description
    CalendarBreaks:
      type: object
      properties:
        _items:
          type: array
          items:
            $ref: '#/components/schemas/CalendarBreak'
    AddCalendarBreakRequest:
      type: object
      properties:
        since:
          type: string
          format: date-time
          example: '2021-05-16T14:00:00+01:00'
        till:
          type: string
          format: date-time
          example: '2021-05-16T15:00:00+01:00'
        description:
          type: string
          example: Optional reason for adding this particular break
        apply_on_coupled_addresses:
          type: boolean
          default: false
          description: 'When true, the same break is also created on the coupled addresses of this doctor in this facility - the online-only ones for an offline address and the other way round. Those breaks are moved and removed together with this one. The response describes only the break created on the requested address.

            '
          example: true
      required:
      - since
      - till
    MoveCalendarBreakRequest:
      type: object
      properties:
        since:
          type: string
          format: date-time
          example: '2021-05-16T14:00:00+01:00'
        till:
          type: string
          format: date-time
          example: '2021-05-16T15:00:00+01:00'
      required:
      - since
      - till
  parameters:
    addressId:
      name: address_id
      in: path
      description: ID of a doctor`s address in a facility
      example: 123
      required: true
      schema:
        type: string
    breakId:
      name: break_id
      in: path
      description: ID of the Calendar Break
      required: true
      schema:
        type: string
        example: 123
    doctorId:
      name: doctor_id
      in: path
      description: ID of a doctor in a facility
      example: 123
      required: true
      schema:
        type: string
    facilityId:
      name: facility_id
      in: path
      description: ID of the Facility
      example: 1
      required: true
      schema:
        type: string
  securitySchemes:
    oauth2:
      name: OAuth 2.0
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://www.{domain}/oauth/v2/token
          scopes:
            integration: API integration
      description: "The API utilizes the industry-standard [OAuth 2.0](https://tools.ietf.org/html/rfc6749) protocol.\n\nAll requests to our API must be authenticated and must include a valid access token.\n\n`NOTE! Our SSO Api version is v2 while our Integration Api version is v3`\n\nYou can get a token for testing purposes with cURL\n\n```\ncurl -u {client_id}:{client_secret} https://www.{domain}/oauth/v2/token -d 'grant_type=client_credentials&scope=integration'\n```\n\nA response example you can expect\n\n```\n{\n    \"access_token\": \"03807cb390319329bdf6c777d4dfae9c0d3b3c35\",\n    \"expires_in\": 3600,\n    \"token_type\": \"bearer\",\n    \"scope\": null\n}\n```\n\nAnd then with every request in the `request header` you should add your bearer token like so:\n\n```\nAuthorization: Bearer {access_token}\n```\n"