Excellent Books REST API (1.0.34.3)

Complete list of all available registers and their fields: Standard Booksi registrite loetelu

For more documentation, visit the ERA Confluence Space.

HTTP Basic Authentication

Encode username:password in Base64 for the Authorization header.

Cookie-Based Sessions (Recommended for Performance)

Important: Using Basic Auth on every request creates significant server load. We strongly recommend using cookie-based sessions after the initial authentication.

How it works:

1. Make one request with Basic Auth credentials
2. Server returns HSESSION cookie in the response
3. Use this cookie for all subsequent requests (no Basic Auth needed)
4. Session remains valid for the configured timeout period (e.g., 24 hours)

Server Configuration Required:

• Module General > Settings > Optional Features (2nd tab): Ensure Do not allow Web API sessions is NOT checked
• Module Technical > Registers > Program Settings > Web tab:
  • Max Sessions: Set to a value greater than 0 (e.g., 25)
  • Timeout, minutes: Set session duration (e.g., 1440 for 24 hours)

Example - Initial authentication request:

curl -X GET "https://YOUR-SERVER:PORT/api/1/" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Accept: application/json" -c cookies.txt

Response includes: Set-Cookie: HSESSION=CC1AC3C5-DAC9C590-DA4FD41F-1E820CB7-C1713CC8

Example - Subsequent requests using session cookie:

curl -X GET "https://YOUR-SERVER:PORT/api/1/TRVc" \
  -H "Accept: application/json" \
  -H "Cookie: HSESSION=CC1AC3C5-DAC9C590-DA4FD41F-1E820CB7-C1713CC8"

Benefits:

• Significantly reduced server load
• Improved Excellent Books stability
• Better performance for high-frequency integrations

OAuth 2.0 (via MyStandard)

OAuth 2.0 is supported using MyStandard as the Authorization Server. Requests authenticated with OAuth2 run on non-primary server threads, reducing impact on other users.

Endpoints:

• Authorization: https://standard-id.hansaworld.com/oauth-authorize
• Token: https://standard-id.hansaworld.com/oauth-token

Setup:

1. Create an API user in Excellent Books with a validated email address
2. Register Developer Credentials at mystandard.hansaworld.com/edit/devcred
3. Configure your OAuth client with the endpoints above
4. Authenticate via MyStandard login page
5. Exchange authorization code for access tokens

• Default: XML
• JSON: Add header Accept: application/json

All register endpoints support:

• fields - Comma-separated list of fields to return
• sort - Field to sort by, ascending only (required when using range)
• range - Value range on the sort field (requires sort; without it the server returns HTTP 422). Three forms: from:to (between, inclusive), from: (from value onwards), or value (exact match). E.g., range=2025-01-01:2025-12-31
• limit - Maximum number of records to return
• offset - Number of records to skip (for pagination with limit)
• updates_after - Get records modified after sequence number (Base registers only)
• deletes_after - Get deleted record IDs after sequence number (Base registers only)
• filter.FieldName - Filter on a header field (multiple filters combine as AND). Exact value (filter.Code=12), range from:to (filter.Sum4=100:1000) or upper bound :to. Text fields compare character by character, so filter.Code=1:2 also matches 10 and 1999. An open-ended from: returns no records (unlike range). No >=/<= operators. On a list field such as Objects the whole string must match: filter.Objects=KONTOR does not return KONTOR,JESS
• listfilter.FieldName - Filter on a comma-separated list field such as Objects: returns records whose list contains the value as a whole item. listfilter.Objects=KONTOR returns KONTOR and JESS,KONTOR; listfilter.Objects=KON returns nothing. Several values (listfilter.Objects=KONTOR,JESS) must all be present, in any order (observed on 8.5.56)
• get_links=1 - Include record links; attachment links contain @comment (file name) and a URL such as /api/0/Attach2Vc/1090
• get_attachdata=1 - On GET Attach2Vc, include Base64 file content in attachment (observed on 8.5.56)

Sequence numbers are in the JSON body: data.@sequence and each record's @sequence, not a response header. Use data.@sequence for the next updates_after request.

Unknown parameters are ignored without an error: a misspelled parameter (listfiltr.Objects=X) or an unknown field name (filter.NoSuchField=X) returns the records unfiltered.

Combining Parameters

All query parameters can be combined freely:

# Invoices for customer 10005, sorted by date, in a date range
https://YOUR-SERVER:PORT/api/1/IVVc?filter.CustCode=10005&sort=InvDate&range=2026-01-27:2026-02-28&limit=10

# Approved invoices for customer 10003 in 2025
https://YOUR-SERVER:PORT/api/1/IVVc?filter.CustCode=10003&filter.OKFlag=1&sort=InvDate&range=2025-01-01:2025-12-31

# 2025 invoices that carry object KONTOR among their objects
https://YOUR-SERVER:PORT/api/1/IVVc?listfilter.Objects=KONTOR&sort=InvDate&range=2025-01-01:2025-12-31

# Contacts created from 2020 onwards (open-ended range)
https://YOUR-SERVER:PORT/api/1/CUVc?sort=DateCreated&range=2020-01-01:

# Single object by code (exact match shorthand)
https://YOUR-SERVER:PORT/api/1/ObjVc?sort=Code&range=ANNIKA

Pagination

Use offset and limit together to paginate through large result sets:

# First page (records 0-4)
https://YOUR-SERVER:PORT/api/1/IVVc?offset=0&limit=5

# Second page (records 5-9)
https://YOUR-SERVER:PORT/api/1/IVVc?offset=5&limit=5

# Third page (records 10-14)
https://YOUR-SERVER:PORT/api/1/IVVc?offset=10&limit=5

GET - List records

Returns only fields that contain data (empty fields are omitted).

curl -X GET "https://YOUR-SERVER:PORT/api/1/ObjVc" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Accept: application/json"

GET - With filters

Returns all fields for each record, including empty ones.

curl -X GET "https://YOUR-SERVER:PORT/api/1/INVc?sort=Code&range=104:110&fields=Code,Name,UPrice1" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Accept: application/json"

GET - With pagination

curl -X GET "https://YOUR-SERVER:PORT/api/1/IVVc?offset=0&limit=5" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Accept: application/json"

POST - Create record

curl -X POST "https://YOUR-SERVER:PORT/api/1/ObjVc" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "set_field.Code=NEWOBJ&set_field.Comment=New Object Name"

POST - Create with rows

curl -X POST "https://YOUR-SERVER:PORT/api/1/IVVc" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "set_field.CustCode=C001&set_field.InvDate=2024-01-15&set_row_field.0.ArtCode=ITEM1&set_row_field.0.Quant=2&set_row_field.0.Price=100"

POST - Create multiple records (JSON)

JSON format allows creating multiple records in a single request. The @register field inside the body is optional — the register is identified by the URL and array key.

curl -X POST "https://YOUR-SERVER:PORT/api/1/ObjVc" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -d '{
    "data": {
        "ObjVc": [
            {"Code": "OBJ1", "Comment": "First object"},
            {"Code": "OBJ2", "Comment": "Second object"},
            {"Code": "OBJ3", "Comment": "Third object"}
        ]
    }
}'

POST - Create record with rows (JSON)

For registers with row data (invoices, orders, etc.), include a rows array inside each record — same structure as returned by GET.

curl -X POST "https://YOUR-SERVER:PORT/api/1/IVVc" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -d '{
    "data": {
        "IVVc": [{
            "InvDate": "2026-03-25",
            "TransDate": "2026-03-25",
            "PayDate": "2026-04-01",
            "CustCode": "50",
            "Addr0": "Customer Name",
            "PayDeal": "7",
            "CurncyCode": "EUR",
            "ARAcc": "1210",
            "InvType": "1",
            "rows": [
                {"stp": "1", "ArtCode": "2002", "Quant": "1", "Price": "50.00", "VATCode": "22", "SalesAcc": "3510"},
                {"stp": "1", "ArtCode": "2002", "Quant": "2", "Price": "25.00", "VATCode": "22", "SalesAcc": "3510"}
            ]
        }]
    }
}'

PATCH - Update record

curl -X PATCH "https://YOUR-SERVER:PORT/api/1/ObjVc/MYCODE" \
  -H "Authorization: Basic BASE64_CREDENTIALS" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "set_field.Comment=Updated Name"

Form-encoded (single record)

• Content-Type: application/x-www-form-urlencoded
• Header fields: set_field.FieldName=value
• Row fields: set_row_field.N.FieldName=value (N = row index starting at 0)
• A + in a form-urlencoded value is stored literally; encode spaces as %20.

JSON (single or multiple records)

• Content-Type: application/json; charset=utf-8
• Wrap records in {"data": {"RegisterCode": [{...}, {...}]}}
• The array key must match the register code in the URL
• The @register field inside objects is optional
• Main advantage: batch creation of multiple records in one request

⚠️ Important: JSON POST does not trigger window actions (paste specials). With form-encoded POST, setting e.g. CustCode on an invoice auto-fills customer name, address, payment terms etc. With JSON, no fields are auto-populated — you must provide all required field values explicitly. This matters most for transactional registers (invoices, orders, etc.) where many fields normally auto-fill from master data.

Register a subscription with a logged-in ERP user:

GET https://SERVER:PORT/WebRegisterWebHook.hal?companynr=1&app=ExcellentAPI&name=Example&url=https%3A%2F%2FCALLBACK%3APORT%2Fhook&type=0&period=0
Authorization: Basic <credentials>

Successful registration returns {"id":"<UUID>"}. The handler emits an empty body if registration does not complete. companynr selects the company; app selects the integration/delivery branch; name is the subscription comment; url is the POST destination. period is stored but ignored by the shown scheduler; zero does not disable delivery.

type=0&app=ExcellentAPI uses the broad register/settings sender. Named types are 1 items, 2 stock, 3 activities, 4 gift vouchers, 5 purchase orders, 6 sales orders, 7 contacts, 8 quotations, 9 sales invoices, 10 purchase invoices, 11 receipts, 12 payments, 13 transactions, 14 accounts and 15 prices. Types 11–15 reach the broad delivery fallback only for app=ExcellentAPI; type 4 has a built-in sender only for app=TikiTakaApp. Types 1–10 select specialised payloads.

Optional filter1–filter3 have register-specific meanings, listed in the registration operation. For extra=2, send efilter0=FieldName&eval0=Value&efilter1=OtherField&eval1=OtherValue. Supported extra filters compare header values for exact string equality and must all match. Their support and change-transition conditions vary by register.

Delivery runs through the periodic integration task. The broad sender POSTs JSON arrays of up to 100 pending entries per register. Each entry contains RecordID, Register, ExternalID, APIRecordUUID, UserStr1–UserStr5, Status (created, updated, deleted) and WebHookID. Readable nondeleted entries also contain record, with string field values and optional rows; deleted entries omit record. Specialised senders use the flat payloads listed in the operation.

Callbacks use Content-Type: application/json; charset=utf-8. A successful SendWebRequest result queues clearing the batch's pending update status. A false result leaves entries pending for a later pass; the code does not parse an acknowledgment body.

Remove a subscription in the same company context:

GET https://SERVER:PORT/WebUnRegisterWebHook.hal?id=%7B%22id%22%3A%22%3CUUID%3E%22%7D

The decoded id query value is {"id":"<UUID>"}, not a bare UUID. Removal requires a logged-in user and returns an empty body, including when no record is removed. This handler does not read companynr.

Save validation errors return HTTP 200. Always check the response body for messages and error, for example:

{"messages":["Enter payment term"],"error":{"@code":"1256","@description":"","@field":"PayDeal"}}

The HTTP status alone does not show whether the save succeeded. Row errors may also include @row.

A confirmed record (OKFlag=1) ignores PATCH: HTTP 200 with an empty error object, but no fields change. This was observed on sales invoices and sales orders. Re-read the record to verify updates.

Public webhook subscription management; merge rest_paths into the REST specification's paths.