Excellent Books REST API (1.0.34)

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). 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 records by exact field value (multiple filters combine as AND), e.g., filter.Code=12

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

# 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)

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.