ZnanyLekarz Calendars API

openapi: 3.2.0
info:
  title: Docplanner Integrations Calendars 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: Calendars
  description: Simple operations on the calendar belonging to the address
paths:
  /facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/calendar:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    - $ref: '#/components/parameters/addressId'
    get:
      operationId: getCalendar
      description: Gets calendar of the address
      tags:
      - Calendars
      responses:
        '200':
          description: Calendar
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Calendar'
              examples:
                Calendar enabled:
                  $ref: '#/components/examples/CalendarEnabled'
                Calendar disabled:
                  $ref: '#/components/examples/CalendarDisabled'
        '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'
                Address does not belong to facility:
                  $ref: '#/components/examples/AddressDoesNotBelongToFacility'
                Address does not belong to doctor:
                  $ref: '#/components/examples/AddressDoesNotBelongToDoctor'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
                Calendar not found:
                  $ref: '#/components/examples/CalendarNotFound'
      summary: Get calendar
      x-summary-source: derived
  /facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/calendar/enable:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    - $ref: '#/components/parameters/addressId'
    post:
      operationId: enableCalendar
      description: Enable calendar on the address
      tags:
      - Calendars
      responses:
        '200':
          description: Calendar has been enabled
        '400':
          description: Address is disabled
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Disabled address:
                  $ref: '#/components/examples/AddressDisabled'
        '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'
        '409':
          description: Calendar is already enabled
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Already enabled calendar:
                  $ref: '#/components/examples/CalendarAlreadyEnabled'
        '422':
          description: Request cannot be processed
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Doctor/address is not commercial:
                  $ref: '#/components/examples/DoctorOrAddressNotCommercial'
      summary: Enable calendar
      x-summary-source: derived
  /facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/calendar/disable:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    - $ref: '#/components/parameters/addressId'
    post:
      operationId: disableCalendar
      description: Disable calendar on the address
      tags:
      - Calendars
      responses:
        '200':
          description: Calendar has been disabled
        '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'
        '409':
          description: Calendar is already disabled
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Already disabled calendar:
                  $ref: '#/components/examples/CalendarAlreadyDisabled'
      summary: Disable calendar
      x-summary-source: derived
components:
  examples:
    CalendarEditionNotAuthorized:
      value:
        errors: []
        message: You are not authorized to make changes on this calendar
    ObjectNotFound:
      value:
        errors: []
        message: Object not found
    CalendarDisabled:
      value:
        status: disabled
    AddressDisabled:
      value:
        errors: []
        message: Could not enable calendar on disabled address
    CalendarNotFound:
      value:
        errors: []
        message: Calendar does not exist
    AddressNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this address
    AddressDoesNotBelongToFacility:
      value:
        errors: []
        message: This address does not belong to this facility
    FacilityNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this facility
    AddressDoesNotBelongToDoctor:
      value:
        errors: []
        message: This address does not belong to this doctor
    CalendarAlreadyEnabled:
      value:
        errors: []
        message: Calendar already enabled
    CalendarEnabled:
      value:
        status: enabled
    CalendarAlreadyDisabled:
      value:
        errors: []
        message: Calendar already disabled
    DoctorNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this doctor
    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
    Calendar:
      type: object
      properties:
        status:
          type: string
          example: enabled
          enum:
          - enabled
          - disabled
  parameters:
    addressId:
      name: address_id
      in: path
      description: ID of a doctor`s address in a facility
      example: 123
      required: true
      schema:
        type: string
    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"