Overview

Office Maker exposes three product-area REST APIs, powered by 4D. Each area ships with an OpenAPI (Swagger) definition that you can browse here. The API uses HTTPS methods to read, create, update and delete data in an Office Maker application.

OM BusinessBusiness managementManage sales, items and more via REST.OM FinanceAccountingAccess accounts, journals, entries and more via REST.OM StaffPayroll managementManage employees, variables and more via REST.

Authentication & Session Management

Authentication

Authentication is session-based. You sign in using the Authentication REST endpoint documented in each product area. On successful login, the server returns a session cookie which must be sent with subsequent requests. The exact cookie name is defined by the server (e.g., a 4DSID_<app_name> cookie); reuse whatever the login response sets. See the session management section for more info.

These docs are public and do not store credentials. Always authenticate directly against your own Office Maker server over HTTPS.

Setting up a REST user

Before authenticating, create a REST user in your OM product (e.g., OM Business) and grant permissions per endpoint.

  1. Open File ▸ Maintenance in your OM client.
  2. Go to Web ▸ Configure REST users…
  3. Click Add and assign the required permissions (none are granted by default).

Session Management

The API uses a server-managed session identified by a secure HTTP cookie. After successful authentication, the server returns a session cookie that must be included in all subsequent requests to protected endpoints. The REST server automatically closes inactive sessions after 60 minutes by default.

Session Cookie

Upon login, the server returns a cookie similar to:

Set-Cookie: 4DSID_<app_name>=<session_id>;
Path=/;
Max-Age=<max_age>;
SameSite=Strict;
Secure;
HttpOnly
  • Max-Age=<max_age> – Session valid for <max_age> seconds.
  • Secure – Cookie is sent only over HTTPS.
  • HttpOnly – Cookie is not accessible via JavaScript.
  • SameSite=Strict – Cookie is not sent in cross-site requests.

Clients must store and resend this cookie automatically. If cookies are disabled or not persisted by the client, authenticated sessions cannot be maintained.

Example using curl
# 1) Sign in (adjust URL and payload to match your authentication endpoint)
# Note: keep the URL in single quotes so the shell does not expand "$catalog".
curl -c cookies.txt \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '[{"username":"<USERNAME>","password":"<PASSWORD>"}]' \
  'https://<HOST>:<PORT>/rest/$catalog/authentify'

# 2) Call a protected resource using the stored session cookie
# Note: keep the URL in single quotes so the shell does not expand "$limit".
curl -b cookies.txt \
  -H 'Accept: application/json' \
  'https://<HOST>:<PORT>/rest/Employees?$limit=5'
Example using Postman

Postman automatically stores and reuses cookies between requests (if enabled), so the session cookie returned by the login call will be sent on subsequent protected calls.

  1. Sign in
    • Method: POST
    • URL: https://<HOST>:<PORT>/rest/$catalog/authentify
    • Headers:
      • Content-Type: application/json
      • Accept: application/json
    • Body → raw → JSON: 
      [
  {
    "username": "<USERNAME>",
    "password": "<PASSWORD>"
  }
]
  2. Call a protected resource
    • Method: GET
    • URL: https://<HOST>:<PORT>/rest/Employees?$limit=5
    • Headers:
      • Accept: application/json
    • No additional authentication header is required: Postman will reuse the session cookie from the login call (cookies must not be blocked/disabled in Postman).
HTTPS Requirement

The server enforces HTTPS using HTTP Strict Transport Security (HSTS). All requests must be made over HTTPS.

First steps (Quickstart)

Below is a minimal flow you can adapt to any OM API.

  1. Pick an API (Business, Finance, or Staff) and skim the operations list.
  2. Download the OpenAPI spec (using the provided link at the top) to import in Postman or your CI.
  3. Sign in on the REST server using the credentials created in the previous step.

API conventions (common to all areas)

  • Base style: 4D REST. Most resources are exposed as data classes (e.g. /rest/Employees), with standard list/detail operations.

    • Operation symbols

    The following symbols are used throughout this documentation to indicate the type of operation:

    • ▤ Read (GET)
    • ⨁ Create (POST)
    • ✎ Update (POST)
    • ✗ Delete (POST)
  • Identifiers: entities carry a primary key; when present in payloads it is always exposed as __KEY.
  • Errors: write operations return a structured envelope with status, statusText, success, and optional errors/messages. Read operations might also return an error structured with an array __ERROR. 
    {
  "__ERROR": [
    {
      "message": "Cannot find entity with \"1\" key in the \"Employees\" dataclass",
      "componentSignature": "dbmg",
      "errCode": 1542
    }
  ]
}

Common request patterns

  • $filter to query by criteria, e.g. /rest/Invoices?$filter=customerID=1234
  • $orderby to sort, e.g. /rest/Employees?$orderby=lastName
  • $limit and $skip for pagination; $count for totals when available
  • $expand to include related entities where supported 
# Filter + sort + pagination example
curl -b cookies.txt \
  -H "Accept: application/json" \
  'https://<your-server>/rest/Invoices?$filter=status=%22Open%22&$orderby=date DESC&$limit=50&$skip=0'

Versioning & environments

  • OpenAPI versioning: Each product area (OM Business, OM Finance, OM Staff) ships its own OpenAPI with a semantic version. Backward-incompatible changes bump the MAJOR version.
  • Selecting an API version: Use the api-version HTTP header to target a specific API version handled by the server. Example: api-version: 1. If omitted, the server falls back to the latest version.
  • Environments: Use your own Office Maker server base URL (e.g., https://<your-server>). The documentation site is static and never proxies your traffic; all requests go directly from your browser to your server.
  • Base path: 4D REST resources are exposed under /rest as data classes (e.g., /rest/Employees), with list/detail operations and optional query options.
  • Content types: JSON for requests and responses by default (Accept: application/json, Content-Type: application/json unless otherwise noted).
  • Dates & times: Some endpoints expose 4D-formatted dates instead of ISO-8601. Unless otherwise specified in the OpenAPI schema, dates may be represented as DD!MM!YYYY (e.g. 29!04!2025). This format is a string and must be parsed accordingly by the client.

These conventions apply across OM Business, OM Finance and OM Staff. Refer to each area’s OpenAPI for entity-specific rules and examples.

Support & Links