PracSuite
Audience: Sales, support, engineering · Where in app: Settings → Integrations → Calendars & booking → PracSuite card ("Clinic Calendar") · Plan availability: All plans; the card shows Coming soon and a disabled Connect PracSuite until PRACSUITE_VENDOR_KEY is set
PracSuite (Smartsoft) is allied-health practice-management software. The integration (backend 1ca9a6548, ms-comm 6298093, ms-ai 4a5f3152c, frontend 2d73555a, 2026-11-03) is a deliberate copy of Semble: the clinic ticks appointment types, locations and practitioners, every combination is a "calendar", and the widget and AI agents book through SchedulingService. It is kept as its own code so the two never change each other.
services/pracsuite/endpoints.js was verified against the public docs for availability, reserve, appointment and patient paths only. The business / practitioner / appointment-type list paths, patient filter fields, patient-create body and business timezone location are marked UNVERIFIED — no vendor key or sandbox existed when it shipped. Expect fixes there on the first live clinic.
How it works
Two keys
- Our vendor key (
x-api-key, envPRACSUITE_VENDOR_KEY), issued by PracSuite to approved developers. Without itPracSuiteService.configuredis false:/pracsuite/statusreturnsavailable: false(card shows Coming soon), connect answers 503, andPracSuiteSyncJobdoes nothing. - Each clinic's subscriber key, pasted on the card, validated by listing the clinic's businesses, stored in the credential vault (
provider: 'pracsuite'), never returned.
Rate limit is per vendor key (5 req/s across every clinic), so one shared GhlRateLimiter bucket at 4/s. A daily quota (50,000) is also shared by all clinics, which is why the sync is bounded (below). An auth error on a stored key flips pracsuite.connection_status: 'expired' (card: Reconnect needed, ladder stops offering PracSuite).
Data (companies.pracsuite, strict subdoc)
connected_at, practice_name, practice_timezone, locations[] {id,name} (PracSuite businesses), appointment_types[] {id,name,duration}, clinicians[] {id,name} (practitioners, named to match Semble's shape), enabled, connection_status (ok|error|expired), connection_error, last_verified_at, last_synced_at. Bookable = isPracSuiteBookable (services/pracsuite/choices.js): enabled + ≥1 of each + not expired. Calendar id <typeId>~<businessId>~<practitionerId|any>; "any" appears when more than one practitioner is ticked.
Session bookings: booking_type: 'pracsuite', pracsuite_appointment_id (string; PracSuite ids are integers). Only ids are kept — no patient record on our side.
Routes (routes/pracsuiteRoutes.js)
| Route | Auth | Purpose |
|---|---|---|
POST /pracsuite/connect, /options, /settings, /status, /rotate-key, /disconnect, /backfill | passport (web owner, or agency user with body.company_id in their agency) | Card + modal. settings re-checks ids against PracSuite and enables booking; rotate-key refuses a key whose businesses don't contain the ticked ids; backfill (no UI) re-checks our bookings from 30 days back to 90 ahead |
GET /pracsuite/:company_id/booking-calendars | public | Widget choice list (empty = one choice, skip the picker) |
POST /pracsuite/availability, /pracsuite/book | public, forcePracSuiteCalendar | SchedulingController handlers with calendar_type pinned to pracsuite, same reason as Semble (no BACKEND_API_KEY dependency). Meetings / reschedule / cancel stay on keyed /scheduling/* |
Booking (scheduling/adapters/PracSuiteAdapter.js)
- Times: PracSuite
app_timeis clinic wall-clock with no offset, converted withpractice_timezone(business timezone) else the company's. The card warns when the zone came from the account, not PracSuite (timezone_from_pracsuite: false). - Availability:
available_appointmentsanswers ≤ 7 days and no past dates, so a request is split into ≤ 4 calls (28-day max look-ahead). "Any" merges the ticked practitioners' slots. - Book: email or phone required.
findOrCreatePatient= exact email, then phone tail, else create with name/email/mobile. A retry after a lost success returns the patient's existing appointment at that start (already_booked). Conflict →SLOT_TAKEN; auth →AUTH_EXPIRED. No notes/comments are sent (not in the documented body). - Cancel posts
/appointment/{id}/cancelwith{}— recorded in the patient's attendance history. - Ladder rung: after Semble, before ServiceM8.
Sync back (PracSuiteSyncJob)
PracSuite has no webhooks. Every PRACSUITE_SYNC_INTERVAL_MINUTES (30) on the schedular, for each enabled non-expired company, syncCompany re-reads our upcoming PracSuite bookings one by one (next 30 days, ≤ 200 per company per run) and applies cancels/moves (> 1 min) to bookings[], the meetings mirror and notifications. Per-company errors are isolated.
Widget, ms-comm, ms-ai
- Widget reuses the Semble choice picker for
bookingType === 'pracsuite'and fetches choices from/pracsuite/:company_id/booking-calendars. - ms-comm:
SchedulingClientHelper.isPracSuiteBookingEnabledrung,routeForsends availability/book to the public/pracsuite/*,MessageController.getPracSuiteAvailableSlots+_pracsuiteSlotsFailed. - ms-ai: PracSuite goes through backend scheduling like Semble; the choice prompt lists the three option lists and voice webhooks apply the same choice gate.
Configuration & environment
| Env (backend + schedular) | Default | Notes |
|---|---|---|
PRACSUITE_VENDOR_KEY | — | Our vendor key; empty = integration shown as Coming soon |
PRACSUITE_REQUEST_TIMEOUT_MS | 30000 | |
PRACSUITE_RATE_LIMIT_MAX / _WINDOW_MS | 4 / 1000 | Shared across all clinics |
PRACSUITE_SYNC_INTERVAL_MINUTES | 30 | Each run costs one call per upcoming booking against the shared daily quota |
As of 2026-11-16 no flux environment sets PRACSUITE_VENDOR_KEY, so PracSuite is Coming soon everywhere. PracSuiteService is always loaded (global pracsuite); clinic keys live in the vault, so SECRET_ENCRYPTION_KEY must match between backend and schedular.
Technical implementation
- backend:
services/PracSuiteService.js,services/pracsuite/{PracSuiteClient,endpoints,choices,errors}.js,scheduling/adapters/PracSuiteAdapter.js,controllers/PracSuiteController.js,middlewares/forcePracSuiteCalendar.js,jobs/PracSuiteSyncJob.js,configs/pracsuite.js. Specs:pracsuite-client,pracsuite-scheduling-adapter. - frontend:
components/integrations/PracSuiteCard.vue,PracSuiteModal.vue(vee-validate + zod key form).
Related
- Semble — the model this copies · Bookings — Sources & Unified View