Excellent Books API

Developer Documentation

v1.0

REST API

/api/1/{Register}

Standard RESTful API for data access and manipulation. Supports GET, POST, PATCH operations on 38+ registers. Use for integrations, data sync, and external system connections.

Base URL https://server:port/api/1/

WebExcellentAPI

/WebExcellentAPI.hal

Action-based API for business workflows and portal operations. Handles approvals, digital signing, attachments, and employee portal features.

Endpoint /WebExcellentAPI.hal?action={action}

API Comparison

Aspect REST API WebExcellentAPI
DesignRESTful (resource-based)RPC-style (action-based)
EndpointsMultiple (per register)Single endpoint
OperationsHTTP methods (GET/POST/PATCH)action parameter
Primary UseData CRUD, integrationsWorkflows, approvals, portal
AuthenticationHTTP Basic Auth / OAuth 2.0HTTP Basic Auth
Response FormatXML (default) or JSONXML

When to Use Which API

⚡

Use REST API for

  • Reading/writing register data
  • External system integrations
  • Data synchronization
  • Bulk data operations
  • Standard CRUD operations
🛠

Use WebExcellentAPI for

  • Approval workflows
  • Digital signing (Dokobit)
  • File attachments
  • Employee portal features
  • Document generation
  • Activity/task management

Best Practices

⚙

Performance Guidelines

  • Large datasets (100,000+ records): Query during off-peak hours
  • Batch requests: Use offset and limit (1000-5000 records per request) with ~1 second pauses
  • Using fields or filter: CPU-intensive. Best with updates_after
  • Query interval: Minimum 20 minutes between sync requests
📈

Performance Benchmarks (v8.5)

2-row financial transactions (POST)~10 per second
1-row invoices with confirmation3-4 per second
10,000 transactions (raw data)~10 sec (30 MB)
10,000 transactions (10 fields)~7 sec (4 MB)

Webhooks

Real-time data change notifications (since 2024)

🔗

Webhook Configuration

Excellent Books supports webhooks for real-time data change notifications. Webhooks send a small JSON payload to a configured external URL when changes occur.

Supported Registers

Items (INVc) Stock Balance Activities Purchase Orders Sales Orders Contacts (CUVc) Quotations Invoices (IVVc) Purchase Invoices Gift Cards

Event Filters

  • Activate for all events: Multiple notifications per record change
  • Selected events: Filter by New, Modified, or Deleted records
  • Field filters: Trigger only when specific field values match (e.g., Group=AUDIO)

Integrations: make.com, Zapier, TikaTaka (custom URLs supported)

OAuth 2.0 Authentication

🔒

OAuth2 via MyStandard

OAuth 2.0 is supported using MyStandard as the Authorization Server. API requests via OAuth2 run on non-primary threads, reducing impact on other users.

Endpoints

  • Authorization: https://standard-id.hansaworld.com/oauth-authorize
  • Token: https://standard-id.hansaworld.com/oauth-token
  • Dev Credentials: https://mystandard.hansaworld.com/edit/devcred

Setup Steps

  1. Create API user in Excellent Books with validated email
  2. Create Developer Credentials in MyStandard
  3. Configure your OAuth client with the endpoints above
  4. Authenticate via MyStandard login page
  5. Exchange authorization code for access tokens

FAQ and Common Tasks

How to use updates_after for incremental sync?

Every response includes a Sequence value. Use this for subsequent requests:

# First request
GET /api/1/INVc
# Response header: Sequence="226655"

# Next request (only changed records)
GET /api/1/INVc?updates_after=226655

Note: After version upgrades, sequence numbers may reset.

How to POST a Credit Invoice?

To credit invoice #200005:

  • PayDeal=K (Credit payment terms)
  • set_row_field.0.stp=3 (Credit row type)
  • set_row_field.0.OrdRow=200005 (Original invoice number)
POST /api/1/IVVc
set_field.InvDate=2021-10-01&
set_field.CustCode=5&
set_field.PayDeal=K&
set_row_field.0.stp=3&
set_row_field.0.OrdRow=200005&
set_row_field.1.ArtCode=1&
set_field.OKFlag=1
How to POST a Purchase Invoice with VAT?

Key VAT handling rules:

  • PayVal = Total including VAT
  • VATVal = VAT amount
  • Sum on rows = Amount excluding VAT
POST /api/1/VIVc
set_field.TransDate=2021-09-24&
set_field.VECode=2&
set_field.PayVal=120.00&
set_field.VATVal=20.00&
set_row_field.0.AccNumber=1010&
set_row_field.0.VATCode=1&
set_row_field.0.Sum=50.00&
set_row_field.1.AccNumber=7410&
set_row_field.1.VATCode=1&
set_row_field.1.Sum=50.00&
set_field.OKFlag=1
Example GET Queries 
# All objects
GET /api/1/ObjVc

# Single object by code
GET /api/1/ObjVc?sort=Code&range=ANNIKA

# Range with specific fields
GET /api/1/ObjVc?sort=Code&range=ANNIKA:KORISTAJA&fields=Code,Comment,OTCode

# Contacts created after date
GET /api/1/CUVc?sort=DateCreated&range=2020-01-01:

# Items with selected fields
GET /api/1/INVc?fields=Code,Name,Unittext,UPrice1
IP Address Restrictions (Since 2025)

Configure in Web Access Settings. Supported formats:

  • Single IP: 90.191.43.252
  • Multiple: 90.191.43.252,213.35.184.82
  • CIDR: 54.124.39.0/24
  • Range: 54.124.39.1-54.124.39.100

Setup Requirements

🔧

Prerequisites

  • Module: Veebipood ja CMS (Web Shop and CMS)
  • Web Port: Configure in Tehnika > Programmiseadistus > Veebiport
  • Web Access: Add API function with SSL enabled
  • User Group: Assign Rest API - Full permission
  • SSL Certificate: Required for HTTPS