ZnanyLekarz Addresses API

openapi: 3.2.0
info:
  title: Docplanner Integrations Addresses 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: Addresses
  description: More information on how we define what a Addresses is, its use cases and more can be found here.
paths:
  /facilities/{facility_id}/doctors/{doctor_id}/addresses:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    get:
      operationId: getAddresses
      description: 'Get a list of addresses of a doctor


        Extensions:

        * `address.online_only` - with this parameter in url, query results will return additional parameter indicating if returned addresses are dedicated to video consultations

        * `address.visit_payment` - with this parameter in url, query results will return additional parameter indicating if visit payments are enabled

        * `address.commercial_type` - with this parameter in url, query results will return additional parameter indicating address commercial type

        * `address.insurance_support` - with this parameter in url, query results will return additional parameter indicating insurance support type of an address'
      tags:
      - Addresses
      parameters:
      - $ref: '#/components/parameters/addressesWith'
      responses:
        '200':
          description: List of addresses
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Addresses'
              examples:
                Addresses:
                  $ref: '#/components/examples/Addresses'
                Addresses with address.online_only:
                  $ref: '#/components/examples/AddressesWithOnlineOnly'
                Addresses with address.visit_payment:
                  $ref: '#/components/examples/AddressesWithVisitPayment'
                Addresses with address.commercial_type:
                  $ref: '#/components/examples/AddressesWithCommercialType'
                Addresses with address.insurance_support:
                  $ref: '#/components/examples/AddressesWithInsuranceSupport'
        '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'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
      summary: Get addresses
      x-summary-source: derived
  /facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    - $ref: '#/components/parameters/addressId'
    get:
      operationId: getAddress
      description: 'Get a single address of a doctor


        Extensions:

        * `address.online_only` - with this parameter in url, query results will return additional parameter indicating if an address is dedicated to video consultations

        * `address.visit_payment` - with this parameter in url, query results will return additional parameter indicating if visit payment isr enabled

        * `address.commercial_type` - with this parameter in url, query results will return additional parameter indicating address commercial type

        * `address.insurance_support` - with this parameter in url, query results will return additional parameter indicating insurance support type of an address'
      tags:
      - Addresses
      parameters:
      - $ref: '#/components/parameters/addressesWith'
      responses:
        '200':
          description: Address data
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Address'
              examples:
                Address:
                  $ref: '#/components/examples/Address'
                Address with address.online_only:
                  $ref: '#/components/examples/AddressWithOnlineOnly'
                Address with address.visit_payment:
                  $ref: '#/components/examples/AddressWithVisitPayment'
                Address with address.commercial_type:
                  $ref: '#/components/examples/AddressWithCommercialType'
                Address with address.insurance_support:
                  $ref: '#/components/examples/AddressWithInsuranceSupport'
        '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:
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
      summary: Get address
      x-summary-source: derived
    patch:
      operationId: updateAddress
      description: Get a single address of a doctor
      tags:
      - Addresses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAddressRequest'
            examples:
              Update address:
                $ref: '#/components/examples/UpdateAddress'
      responses:
        '200':
          description: Address updated
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Address'
              examples:
                Address with insurance support:
                  $ref: '#/components/examples/AddressWithInsuranceSupport'
        '400':
          description: Validation of the submitted values wasn't successful
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid request argument:
                  $ref: '#/components/examples/InvalidArgumentsError'
        '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'
                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'
      summary: Update address
      x-summary-source: derived
  /facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/integration:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    - $ref: '#/components/parameters/addressId'
    delete:
      operationId: removeAddressIntegration
      description: 'Remove the integration mark from a single address.

        After this call, Docplanner will no longer treat the address as integrated with the API client''s system. The address itself is not deleted.

        **Endpoint is dedicated for DocplannerPMS API clients only.**'
      tags:
      - Addresses
      responses:
        '202':
          description: Address integration removal accepted
        '403':
          description: You are not authorized to see this resource
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Feature not enabled:
                  $ref: '#/components/examples/FeatureNotAuthorized'
                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'
      summary: Remove address integration
      x-summary-source: derived
components:
  examples:
    AddressesWithInsuranceSupport:
      value:
        _items:
        - id: '111'
          name: Example hospital
          post_code: xx-xxx
          street: Some street
          booking_extra_fields:
            birth_date: false
            gender: false
            nin: false
          insurance_support: private
    CalendarEditionNotAuthorized:
      value:
        errors: []
        message: You are not authorized to make changes on this calendar
    AddressWithVisitPayment:
      value:
        id: '111'
        name: Example hospital
        city_name: Some city
        post_code: xx-xxx
        street: Some street
        booking_extra_fields:
          birth_date: false
          gender: false
          nin: false
        visit_payment: true
    ObjectNotFound:
      value:
        errors: []
        message: Object not found
    AddressWithCommercialType:
      value:
        id: '111'
        name: Example hospital
        city_name: Some city
        post_code: xx-xxx
        street: Some street
        booking_extra_fields:
          birth_date: false
          gender: false
          nin: false
        commercial_type: basic
    UpdateAddress:
      value:
        insurance_support: private_and_insurance
    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
    Address:
      value:
        id: '111'
        name: Example hospital
        city_name: Some city
        post_code: xx-xxx
        street: Some street
        booking_extra_fields:
          birth_date: false
          gender: false
          nin: false
    AddressDoesNotBelongToDoctor:
      value:
        errors: []
        message: This address does not belong to this doctor
    Addresses:
      value:
        _items:
        - id: '111'
          name: Example hospital
          city_name: Some city
          post_code: xx-xxx
          street: Some street
          booking_extra_fields:
            birth_date: false
            gender: false
            nin: false
    InvalidArgumentsError:
      value:
        errors: []
        message: Invalid arguments
    AddressesWithOnlineOnly:
      value:
        _items:
        - id: '111'
          name: Example hospital
          city_name: Some city
          post_code: xx-xxx
          street: Some street
          is_online_only: true
          booking_extra_fields:
            birth_date: false
            gender: false
            nin: false
    AddressesWithCommercialType:
      value:
        _items:
        - id: '111'
          name: Example hospital
          city_name: Some city
          post_code: xx-xxx
          street: Some street
          booking_extra_fields:
            birth_date: false
            gender: false
            nin: false
          commercial_type: basic
    AddressWithOnlineOnly:
      value:
        id: '111'
        name: Example hospital
        city_name: Some city
        post_code: xx-xxx
        street: Some street
        is_online_only: true
        booking_extra_fields:
          birth_date: false
          gender: false
          nin: false
    FeatureNotAuthorized:
      value:
        errors: []
        message: You are not authorized to use this feature
    AddressWithInsuranceSupport:
      value:
        id: '111'
        name: Example hospital
        city_name: Some city
        post_code: xx-xxx
        street: Some street
        booking_extra_fields:
          birth_date: false
          gender: false
          nin: false
        insurance_support: private
    DoctorNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this doctor
    AddressesWithVisitPayment:
      value:
        _items:
        - id: '111'
          name: Example hospital
          city_name: Some city
          post_code: xx-xxx
          street: Some street
          booking_extra_fields:
            birth_date: false
            gender: false
            nin: false
          visit_payment: false
  schemas:
    Addresses:
      type: object
      properties:
        _items:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    AddressesScopes:
      type: string
      enum:
      - address.online_only
      - address.visit_payment
      - address.commercial_type
      - address.insurance_support
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
        message:
          type: string
    Address:
      type: object
      properties:
        id:
          type: string
          example: 333
        name:
          type:
          - string
          - 'null'
          example: Test hospital
        city_name:
          type:
          - string
          - 'null'
          example: Testing city
        post_code:
          type:
          - string
          - 'null'
          example: XX-XXX
        street:
          type:
          - string
          - 'null'
          example: Testing street
        is_online_only:
          type: boolean
          example: false
        visit_payment:
          type: boolean
          example: false
        booking_extra_fields:
          type: object
          properties:
            gender:
              type: boolean
              example: true
            nin:
              type: boolean
              example: true
            birth_date:
              type: boolean
              example: true
        commercial_type:
          type: string
          enum:
          - premium
          - saas-only
          - basic
          example: basic
        insurance_support:
          type: string
          enum:
          - private
          - insurance
          - private_and_insurance
          example: private
    UpdateAddressRequest:
      type: object
      properties:
        insurance_support:
          type: string
          enum:
          - private
          - insurance
          - private_and_insurance
  parameters:
    addressesWith:
      name: with
      in: query
      required: false
      style: simple
      schema:
        type: array
        uniqueItems: true
        items:
          $ref: '#/components/schemas/AddressesScopes'
    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"