Service Reference

Complete reference for all available service methods.

Services provide RPC-style function calls. All service calls use POST:

POST /api/services/{serviceName}/{methodName}

The request body is a JSON object with the method parameters. The server waits up to 30 seconds for a response before returning a 504 timeout.

Discovering services

List all registered services and their methods:

curl http://your-server/api/services \
  -H "Authorization: Bearer $TOKEN"

Get info about a specific service:

curl http://your-server/api/services/lab \
  -H "Authorization: Bearer $TOKEN"

{
  "name": "lab",
  "methods": ["addLog", "getLogs", "resetPassword", "addUser", "deleteUser", ...]
}

lab service

The main service for user management, access control and logging.

Method Description Permissions
addUser Create a new user LAB_ADMIN, LAB_MODIFY_USERS
addOrUpdateUser Create or update a user LAB_ADMIN, LAB_MODIFY_USERS
deleteUser Delete a user LAB_ADMIN, LAB_MODIFY_USERS
resetPassword Send a temporary password by email (any valid token)
transferMoney Add/deduct credit LAB_ADMIN, LAB_SERVICE
getUserForCard Look up user by RFID card LAB_ADMIN, LAB_SERVICE, LAB_SEE_USERS
getUserForExternalReference Look up user by external ID LAB_ADMIN, LAB_SERVICE, LAB_SEE_USERS
hasPermission Check access to a resource LAB_SERVICE
getLogs Query log entries LAB_ADMIN, LAB_SERVICE, LAB_SEE_LOGS (or own logs)
addLog Create a log entry LAB_ADMIN, LAB_SERVICE
addGroup Create a new group LAB_ADMIN, LAB_SERVICE, LAB_MODIFY_GROUPS
getAccumulatedCostsForUser Get total costs for a user in a date range LAB_ADMIN, LAB_SERVICE, LAB_SEE_LOGS (or own costs)
addSystemUser Create a system/admin user LAB_ADMIN, IS_ADMIN, LAB_SERVICE
changeUserLevel Change a system user’s role LAB_ADMIN, IS_ADMIN, LAB_SERVICE

See Users, Groups & Permissions, and Logs for detailed examples.

getAccumulatedCostsForUser

Returns the total accumulated costs for a user within a given date range. The server aggregates all log entries matching the user and time range, and returns the summed totalCost.

Unprivileged users (without LAB_ADMIN, LAB_SERVICE, or LAB_SEE_LOGS permission) can only query their own costs — the userID parameter is ignored and automatically set to the authenticated user’s ID.

curl -X POST http://your-server/api/services/lab/getAccumulatedCostsForUser \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userID": "f47ac10b58cc4372a5670e02b2c3d479",
    "from": "2024-01-01T00:00:00.000",
    "to": "2024-02-01T00:00:00.000"
  }'
Parameter Type Required Description
userID string yes UUID of the user to query costs for
from datetime yes Start of the date range (ISO 8601)
to datetime no End of the date range (ISO 8601). Defaults to current time if omitted

Response:

[
  {
    "totalCost": 4250
  }
]
Field Type Description
totalCost int Sum of all price values (in cents) from matching log entries

addSystemUser

Creates or updates a system-level user (for admin panel access).

curl -X POST http://your-server/api/services/lab/addSystemUser \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userID": "f47ac10b58cc4372a5670e02b2c3d479",
    "name": "Admin User",
    "eMail": "admin@fablab.org",
    "level": "admin"
  }'
Parameter Type Required Description
userID string yes UUID of the lab user to promote
name string yes Display name
eMail string yes Email address
level string yes Role level (e.g. admin, viewer)

changeUserLevel

Changes the system role of an existing system user.

curl -X POST http://your-server/api/services/lab/changeUserLevel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userID": "f47ac10b58cc4372a5670e02b2c3d479",
    "level": "viewer"
  }'

payment service

Handles point-of-sale billing operations (used by the 2log PayDesk).

Method Description Permissions
preparebill Validate a shopping cart and calculate totals (any valid token)
bill Execute a bill (deduct balance, create logs) IS_ADMIN, LAB_ADMIN, LAB_SEND_BILLS
getsales Get product sales history for a date range (any valid token)

preparebill

Validates a shopping cart, resolves the user, and calculates totals per accounting code. Does not deduct money.

curl -X POST http://your-server/api/services/payment/preparebill \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cardID": "04:A3:2B:1C:D4:E5:F6",
    "bill": [
      {"name": "Laser time 30min", "price": 500, "accountingCode": "laser"},
      {"name": "Material fee", "price": 200, "accountingCode": "material"}
    ],
    "total": 700
  }'
Parameter Type Required Description
cardID string one of cardID/userID RFID card to identify the user
userID string one of cardID/userID User UUID (alternative to cardID)
bill array yes List of items, each with name, price (cents), accountingCode
total int yes Expected total in cents

Response:

{
  "errcode": 0,
  "errstring": "",
  "userID": "f47ac10b...",
  "name": "Max",
  "surname": "Mustermann",
  "eMail": "max@fablab.org",
  "total": 700,
  "discountTotal": 700,
  "bills": [
    {
      "accountingCode": "laser",
      "totalBrutto": 500,
      "totalNetto": 500,
      "discountPercent": 0,
      "items": [...]
    }
  ]
}

bill

Executes the billing: deducts the amount from the user’s balance, creates log entries, and sends a payment confirmation email.

curl -X POST http://your-server/api/services/payment/bill \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cardID": "04:A3:2B:1C:D4:E5:F6",
    "userID": "f47ac10b58cc4372a5670e02b2c3d479",
    "bills": [
      {
        "accountingCode": "laser",
        "totalNetto": 500,
        "items": [
          {"uuid": "item-1", "name": "Laser time 30min", "price": 500, "newprice": 500, "flat": false}
        ]
      }
    ],
    "total": 500,
    "discountTotal": 500
  }'
Parameter Type Required Description
cardID string one of cardID/userID RFID card ID
userID string one of cardID/userID User UUID
bills array yes Array of bill groups (from preparebill response)
total int yes Original total in cents
discountTotal int yes Final total after discounts in cents
cartID string no Unique cart ID (prevents double billing)

Error codes:

errcode Description
0 Success
-2 Unknown user
-3 Invalid parameters
-4 Cart already paid (duplicate cartID)
-5 Credit limit exceeded

getsales

Returns product sales history for a given date range.

curl -X POST http://your-server/api/services/payment/getsales \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01T00:00:00.000",
    "to": "2024-02-01T00:00:00.000"
  }'

devices service

Manages IoT device mappings and firmware updates.

Method Description
hookWithShortID Map a device to a resource by its short ID
unhookWithShortID Remove a device mapping by its short ID
getDeviceTypeWithShortID Get the device type for a short ID
getDeviceTypeWithID Get the device type for a UUID
checkForUpdates Check for available firmware updates
startUpdate Start a firmware update

hookWithShortID

Maps a physical device (identified by its short ID printed on the hardware) to a logical resource name.

curl -X POST http://your-server/api/services/devices/hookWithShortID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shortID": "AB12",
    "mapping": "laser-cutter-01",
    "force": false,
    "expectedType": "switch"
  }'
Parameter Type Required Description
shortID string yes Short ID of the device
mapping string yes Logical resource name to assign
force bool no Overwrite existing mapping (default: false)
expectedType string no Expected device type; fails if mismatch

Error codes in response:

errorcode Description
0 Success
-11 Device not found
-12 Wrong device type

unhookWithShortID

curl -X POST http://your-server/api/services/devices/unhookWithShortID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shortID": "AB12"}'

getDeviceTypeWithShortID

curl -X POST http://your-server/api/services/devices/getDeviceTypeWithShortID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shortID": "AB12"}'

Response:

{"deviceType": "switch", "errorcode": 0}

getDeviceTypeWithID

curl -X POST http://your-server/api/services/devices/getDeviceTypeWithID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "device-uuid-here"}'

checkForUpdates

curl -X POST http://your-server/api/services/devices/checkForUpdates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mapping": "laser-cutter-01"}'

startUpdate

curl -X POST http://your-server/api/services/devices/startUpdate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mapping": "laser-cutter-01",
    "url": "https://firmware.example.com/update.bin"
  }'

machineControl service

Handles the association between 2log controllers (Switch, Dot) and machines.

Method Description
hookSwitch Assign a 2log Switch to a machine
hookDot Assign a 2log Dot to a machine

hookSwitch

Links a 2log Switch device to a machine controller.

curl -X POST http://your-server/api/services/machineControl/hookSwitch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shortID": "AB12",
    "deviceID": "machine-controller-id",
    "force": false
  }'
Parameter Type Required Description
shortID string yes Short ID of the Switch device
deviceID string yes ID of the machine controller to attach to
force bool no Overwrite existing assignment

hookDot

Links a 2log Dot device to a machine controller.

curl -X POST http://your-server/api/services/machineControl/hookDot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shortID": "CD34",
    "deviceID": "machine-controller-id",
    "force": false
  }'

resources service

Manages 2log resource controllers (the logical representations of machines).

Method Description
newController Create a new resource controller
deleteController Delete a resource controller

newController

curl -X POST http://your-server/api/services/resources/newController \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Laser Cutter",
    "type": "machines",
    "uid": "laser-cutter-01"
  }'
Parameter Type Required Description
name string yes Display name
type string yes Resource type (e.g. machines, suctions)
uid string yes Unique device/resource ID

Response:

{"success": true, "data": {...}}

deleteController

curl -X POST http://your-server/api/services/resources/deleteController \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uid": "laser-cutter-01"}'

codeAuthenticator service

Handles QR-code based authentication (used by the 2log mobile app).

Method Description
authenticate Authenticate a session via a temporary code

authenticate

The 2log app displays a QR code containing a temporary code. When scanned (e.g. by a terminal), this method is called to authenticate the session.

curl -X POST http://your-server/api/services/codeAuthenticator/authenticate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "https://2log.app/AB3F7K9X"}'
Parameter Type Required Description
code string yes The temporary authentication code

Response:

{"errcode": 0}

errcode -1 means the code is unknown or expired.