Developer overview
How a restaurant, booking or play venue app connects to FloorPlanCraft, pushes live status and shows the live 3D floor inside the app.
Updated · View as Markdown
Live 3D shows a venue's floor plan with live status from the venue's own app: which tables are seated, which rooms and chairs are in use, how many kids are in each play zone. These pages are for the developers of those apps.
These pages describe integration contract v1.7.
Which apps can connect
| Your app | app value | What it reports |
|---|---|---|
| A restaurant POS or table app | "restaurant" | Tables (free, seated or being reset) and kitchen or bar stations |
| A booking app for a salon, clinic or gym | "booking" | Areas: rooms, chairs or basins, staff stations |
| A play venue's ticketing app (POS) | "play" | Play zones and the number of kids in each |
All three use the same endpoints, signing and embeds. Where they differ, these pages say so. The API calls every row tables: a booking app's areas and a play venue's zones travel in the same fields as a restaurant's tables.
How it works
- Your server sends a connect request with the venue's details and gets back an
authorizeUrl. - The venue owner opens that address, signs in to FloorPlanCraft, chooses the plan and approves the connection.
- Your server exchanges the code it gets back for a
connectionIdand aconnectionSecret. - Your server pushes the venue's status, signed with the secret: on every change, and as a heartbeat every 60 seconds.
- Your server asks for a short-lived embed address, and your app shows the live 3D floor in an iframe.
Connect an app covers the first three steps, Live updates the pushes and Embedding the live view the frame. The venue owner's side, from approving to switching on Live 3D, is in Connect your venue app.
Endpoints
Every address is on https://floorplancraft.com, and every request and answer body is JSON.
| What | Request | Signed |
|---|---|---|
| Connect request | POST /api/connect/requests | No |
| Approval | The authorizeUrl, opened in the venue owner's browser | No |
| Code exchange | POST /api/connect/token | No: PKCE proves the install |
| Push status | POST /api/live/ingest | Yes |
| Re-send history | POST /api/live/backfill | Yes |
| Live embed address | POST /api/live/embed-tokens | Yes |
| Add tables to the plan (restaurant only) | POST /api/connections/self/tables | Yes |
| Disconnect | DELETE /api/connections/self | Yes |
| Live embed | /live/embed/<token> in an iframe | No: the token opens it |
| Plan embed | /embed/<shareToken> in an iframe | No |
Signing requests shows how to sign, and Disconnect and errors lists every error and limit.
Ground rules
- Your server calls FloorPlanCraft, and FloorPlanCraft never calls your app. A venue behind a router needs no open port.
- There is no shared API key. Each install proves itself with PKCE when it connects, then signs every request with its own secret.
- Keep the
connectionSecreton your server. Never send it to a browser, put it in an iframe address or write it to a log. - Name tables, areas and zones exactly as the plan's zones are named. Matching ignores case and surrounding spaces.
- The venue owner pays FloorPlanCraft for Live 3D. Your app does no billing.
- Ignore fields you do not know in answers and messages.