API documentation
Integrate Passa Personal with a till, access system, chat or your own software – over HTTPS with your own API key.
Getting started
The API lets your other systems talk to Passa Personal: the till sends the day’s sales, the access system clocks people in, and the chat learns when an open shift is posted.
https://your-domain.example/api.phpAPI key: A signed-in manager finds “User-Key / X-Api-Key” under Settings → Till connection, Webhooks & REST API.
Authentication: Send the key in the HTTP header
X-Api-Key: YOUR_KEY. The header is recommended over putting the key in the URL.Responses are always JSON. Errors return an HTTP status and an error field, for example 401 for an invalid key, 409 for a double clock-in and 422 for invalid fields. POST calls must be JSON with Content-Type: application/json.
1. Till connection – send daily sales
?a=posCalled at end-of-day/Z report.TruePOS, Sitoo, Shopify, WooCommerce, Northmill Flo, ExtendaGO, PC-Kassa, HiCore, Loomis Pay, Zettle, SumUp, Square, Ancon, Onslip, Caspeco, Trivec and Bambora are supported. Most fields are optional and common name variants are recognised automatically.
POST /api.php?a=pos
X-Api-Key: YOUR_KEY
Content-Type: application/json
{
"sales": [{
"date": "2026-10-17", "amount": 48250.00,
"net_sales": 38600.00, "vat": 9650.00,
"tx_count": 212, "card": 32800, "swish": 11850,
"cash": 1900, "invoice": 1700, "tips": 940,
"z_nr": "Z-1042", "provider": "truepos"
}]
}| Field | Meaning |
|---|---|
date | Date as YYYY-MM-DD. z_date, business_date and timestamp are also accepted. |
amount | Gross sales including VAT. Variants such as total, gross_sales and amount_ore are handled. |
net_sales, vat | Net and VAT. If missing, net is calculated from the gross amount. |
card, swish, cash, invoice | Payment breakdown and refunds. |
tips | The day’s tips, added to the tips pool. |
hourly, staff_sales | Optional sales per hour or per employee. |
Response: {"ok":true,"saved":1}. The same date can be sent again – the latest value wins. Without the API, SIE4 or CSV files can be imported in the app under Budget & Till.
2. Status – who is in right now?
?a=api_statusPresent staff, break status and today’s sales.GET /api.php?a=api_status
X-Api-Key: YOUR_KEY
{
"org_id": 3, "site": "The Neighbourhood Pub",
"company": "Example Ltd",
"present": [{"staff_id": 12, "name": "Anna Andersson",
"role": "Waiting staff", "since": 1760713200000, "on_break": false}],
"sales_today": 48250.0, "timestamp": 1760734800000
}since and timestamp are milliseconds since the epoch (UTC). The same presence data powers the wall/TV presence board.
3. Clocking via API
?a=api_punchClock staff in or out from an external system.POST /api.php?a=api_punch
X-Api-Key: YOUR_KEY
Content-Type: application/json
{"action": "in", "badge": "A1B2C3D4"}| Field | Meaning |
|---|---|
action | in or out. |
staff_id / badge / pnr | Identify the person with exactly one field: internal id, badge/QR code or personal identity number. |
A successful clocking returns the person, event and timestamp. Already clocked in returns 409 and an unknown person returns 404. Every clocking is written to the staff ledger and can trigger webhooks.
4. Webhooks – real-time events
Configure webhooks under Settings → Webhooks & chat notifications in the app. At every event, JSON is posted to your URL, signed with HMAC-SHA256 so the receiver can verify the sender.
| Event | Triggered when |
|---|---|
checkin | Someone clocks in via punch terminal, app or API. |
checkout | Someone clocks out; the shift then awaits approval. |
break | A break starts or ends (off by default). |
leave | Sick leave or a holiday request is registered. |
POST https://your-server.example/webhook
X-Passa-Event: checkin
X-Passa-Signature: sha256=9f2c…
Content-Type: application/json
{"event":"checkin","org_id":3,"site":"The Neighbourhood Pub",
"company":"Example Ltd","data":{"staff_id":12,
"name":"Anna Andersson","ts":1760713200000,"method":"punch terminal"},
"timestamp":1760713200123,"iso":"2026-10-17T07:00:00+02:00"}Verify the signature (PHP)
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, 'YOUR_SECRET');
if (!hash_equals($expected, $_SERVER['HTTP_X_PASSA_SIGNATURE'] ?? '')) {
http_response_code(403); exit;
}You choose the secret yourself in the settings. Webhooks are sent in the background and only to public https addresses. Build the receiver idempotently – the same event can, in rare cases, be delivered more than once.
Slack, Microsoft Teams & Discord
Put the chat’s incoming webhook URL in the “Slack / Teams / Discord Webhook URL” field, and readable messages are posted to the channel – for example that Anna Andersson clocked in at 07:02.
5. Calendar feed (ICS)
?a=ics&token=PERSONAL_TOKENSubscribe to the schedule in your phone calendar.Every user has a personal calendar link in the app. With &all=1 and a manager token you get the whole unit’s schedule including approved leave. The link is personal – do not share it publicly.
6. Public views per unit
| View | Address | Content |
|---|---|---|
| Clock-in | /incheckning/?k=PUNCH TERMINALTOKEN | Time clock for staff. |
| Presence board | /tavla/?k=PUNCH TERMINALTOKEN | Wall/TV view of who is in right now. |
| Staff ledger | /liggare/?k=LEDGERTOKEN | Read-only control view for the Tax Agency. |
| Schedule viewer | /schema/?k=PUNCH TERMINALTOKEN | View-only schedule. |
The tokens are found in the app under Settings and can be replaced there – old links then stop working.
Security & limits
- Always call over HTTPS. The API key grants access to the unit’s clocking API and must be treated like a password.
- The key is unique per unit and can be rotated if it leaks.
- On network errors the same clocking call can be retried; a double clock-in is rejected with 409.
- Personal identity numbers in api_punch are never logged in plain text.
Want to connect a system?
Email us via the contact form and we will get you started with the right keys and a test call.
Book a demo – 20 minutes