Scheduling & Online Booking API

This section describes how to connect your clinic's scheduling system to external applications using the Alpaca Schedule & Online Booking API.
This is useful for developers or integrators setting up online booking, external portals, or integrations with partner platforms.

📎 schedule api_en_1.6.pdf
(This document serves as the full technical reference for developers.)

Scheduling & Online Booking API

Version: 1.6 (03/2025)
Purpose: External systems can retrieve doctors, services, worktime, slot availability, and create/cancel appointments in Alpaca ERP.

This API now supports two use cases:

A) Scheduling API (data extraction)

Used to retrieve schedule-related information for embedding in external apps:

Employee list
Services & pricing
Worktime windows
Available slots
Price types (in detailed endpoints)
Full employee catalog (employees-all)
Available slots by service

B) Online Booking API (actions)

Used to create actual appointments from external portals:

Booking via the selected slot
Advanced booking with price type
Booking cancellation

Authentication

Every API request must include:

CODE

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

The token is taken from the ERP user profile.
All responses return a JSON object with the mandatory field:

Success:

CODE

{ "ok": true, ... }

Error:

CODE

{ "ok": false, "error": "<description>" }

ERP Configuration Requirements

To use Scheduling/Online Booking API v1.6, configure the following in Alpaca ERP:

1. Online Scheduling Settings

Enable:

Online scheduling
Slot depth — number of future days returned in Slot-related endpoints.

2. Employee Directory → Services

For all employees whose schedule will be published to external systems:

Flag	Meaning
To site	Service becomes visible for export via API
Online booking	Service can be booked online
Default	The fallback service if the client does not specify one

Only services marked To site can be marked Online booking.

3. Touch Types Directory

At least one Touch Type must have:

Online booking flag enabled
This Touch Type will be automatically used during booking creation.

API Methods Overview (v1.6)

1. GET /api/schedule/employees

Returns a list of doctors available for online booking and services marked To site and/or Online booking.

Includes:

multilingual fields (locales)
default service flags
online_booking flag per service

Alpaca schedule API v1.6 (2)

2. GET /api/schedule/employees/{id}

Returns detailed doctor information:

Doctor profile
All exportable services
Prices (by price type)
Online booking availability
Default service

Alpaca schedule API v1.6 (2)

3. GET /api/schedule/employees/{id}/worktime

Returns working time windows visible for booking within the Slot Depth configured in ERP.

Considers vacations, absences, custom statuses, and schedule occupancy.

Alpaca schedule API v1.6 (2)

4. GET /api/schedule/employees/{id}/slots/{service_id?}

Returns all available bookable slots for:

doctor {id}
optional: service {service_id}
If omitted, → uses the default service.

Each returned day contains:

slot_duration
one or more slot IDs used for booking
real-time availability

If no slots → schedule not available OR fully occupied.

Alpaca schedule API v1.6 (2)

5. POST /api/schedule/employees/{employee_id}/slots/{slot_id}/make_appointment

Creates a booking and automatically:

creates a new client if no match is found
creates Touch record (based on Touch Type configuration)
sends system notifications to ERP staff
strictly validates the schedule to prevent double booking

Required fields

Field	Required	Description
patient_phone	yes	Patient phone
patient_name	yes	Full name
services[]	no	An array of service IDs. If empty → default service
patient_email	no	Email
birthdate	no	YYYY-MM-DD
comment	no	Booking comment
passport	no	Passport ID

6. POST /api/schedule/employees/{employee_id}/slots/{slot_id}/make_appointment_advanced

Same as method 5, plus:

price_type_id — records price type on the created Counteragent/Touch

Used for partners, agencies, insurers, and multiple price policies.

7. GET /api/schedule/employees-all

Returns all doctors with:

default price type
all services
all metadata

Filtering conditions:

“Use in schedule“ = enabled.
Doctor status = active
Employee state = active

Use case: partner platforms syncing the full catalog.

8. GET /api/schedule/slots/{service_id}

Returns slot availability grouped by doctors for a specific service.

Useful for lab tests/procedures where booking is by service first and doctor second.

Returned structure:

CODE

employees[] → slots[] → slots[]

Slot ID format identical to method 4.

9. POST /api/schedule/slots/{slot_id}/cancel

Cancels a previously created booking.
Performs full ERP-level validations:

payment presence
medical document existence
processing stages
linked actions

Cancelling triggers internal system events and notifications.

Required field:

CODE

reason = <CancellationReasonID>