Endpoints

All requests go to EnvironmentConfig.appengineEndpoint with Authorization: Bearer <token> and an orgid header. Auth in the blocks below is what the server enforces: user means a staff JWT (@Roles(RoleType.User)), customer means any authenticated customer or staff token, public means @PublicRoute().

Auth and profile

The directory lookup is step one of sign-in. It is public — no org header, no token — takes {email}, and answers {orgs: [{orgId, displayName}]}, most recently used first. That is how the app knows which organization to sign into without anyone typing one: an empty list means no such account, one entry is used silently, several are offered as a picker. The orgid header on the sign-in call that follows carries the chosen org.

Sign-in sends {orgId, email, password}; the magic-link GET takes ?email=&type=code and the redirect POST takes {email, code}. Passcode sign-in takes {employeeId, pin?, cardUid?} and uses the org the device last signed into. Delete-self is refused for the org's primary contact.

Passcodes and access cards

Card status is active, revoked or lost. The base-setting document carries data.passcodeLoginSettings {enable, mode}.

Storefront: POS tabs

Open a tab with {businessLocationId, tabLabel?, servicePointId?, customer?}. Settle takes {amount, method?, gateway?, ref?} and returns {order, transaction} — the app unwraps order. Fire is idempotent: lines that already carry a taskId are dropped. Split takes itemIds or parts. Receipt payloads accept ?copy=customer|merchant.

Storefront: payments

Gateways return the provider name and publishable key (StripeProvider, PayPalProvider, HelcimProvider). Terminal intents are created with payment_method_types: ['card_present']; the resulting PaymentIntent id is passed to settle as ref.

Repository (generic records)

Used for sf_product, bm_location_product, sf_order edits, reservation, service_point, location, customer, task, ticket, message. update-partial takes a flat key map that the server $sets verbatim — write data.productItems, not productItems, or the value lands at the record root. It returns a boolean, not the record.

Reservations and service points

The app lists reservations through POST /repository/find/reservation rather than /crm/reservations/get, because the latter returns only the caller's own bookings. create expects flat fields; a {datatype, data} body is rejected as "not new". Slots take {reservationDefinitionId, serviceName?, serviceDate, partySize?}.

Check-in queue

All routes need a JWT but no role. Walk-in requires at least one of name, email or phone. From-reservation accepts {partySize?, businessLocationId?, notes?} and answers 409 while a live task already exists. Assign takes {servicePointId} (name or id; the server writes back by id) and rejects points that are occupied or reserved. Clear takes {finalStatus: 'dirty' | 'available'}.

Workflow

CRM

POST /crm/inbox/update?send=true wraps the message in a record and triggers the send; it is also how the SMS composer sends. Inbox conversations are threaded server-side as contact plus channel.

Chat and presence

Socket.IO namespace /chat, websocket transport, auth {token, orgId, chatId?}. The app emits sendMessage, chat-message, chatRequest, updateMessageStatus, shareStatus, getMessages, set-status, pick-next, transfer-chat, close-chat, takeover-chat, resume-ai, assist-ai, join-chat, leave-chat, and listens for authenticate, message, update, status, messages, ai-stream, chat-stream, presence-change, chat-assigned, chat-transferred, chat-ended, agent-assigned, agent-changed, queue-notification, queue-updated, session-expiring, session-expired, token_expired, chat-inactivity, sms.received.

Phone and softphone

Register with {deviceId, platform, label, capabilities: ['voice','sms'], clientInfo}; the response carries the Twilio access token and assigned numbers. Heartbeat every 60 s against a 90 s server TTL.

Events (staff side)

The whole /events controller is staff-only. The attendee app uses the separate /client/events surface documented under EventOxygen.

Shapes the app depends on:

• POST /events/checkin and POST /events/checkout take {code, zone?, checkpoint?}; checkout also accepts {ticketId}. The code is resolved as a dynamic QR payload (ticketId:timestamp:signature), then as a static ticket code (case-insensitive), then as a credential code. Both answer {success, ticket?, reason?}; a denial is success:false with reason, not an HTTP error.
• GET /events/:id/checkin-stats returns {total, successful, denied, uniqueAttendees, byZone, byHour}. The app's "Checked In" is uniqueAttendees (fallback successful); "Scans" is total.
• GET /events/:id/occupancy returns an object keyed by zone id: {zoneId, zoneName, capacity, currentOccupancy, availableCapacity, percentFull, totalEntranceScans, totalEligibilityScans}. Scans sent without a zone are logged under zone unknown and are not in it.
• GET /events/tickets/:id/qr returns the ticket with a freshly signed data.code; a ticket created without a codeSecret gets one on first call.
• POST /events/:id/tickets needs ticketTypeId; POST /events/tickets/comp needs items:[{ticketTypeId, quantity, holderEmail, holderName?}]; POST /events/tickets/fulfill with walkIn needs walkIn.ticketTypeId. The app loads the choices from GET /events/:id/ticket-types.

Social sync

Related