Excellent Books API Documentation

REST API and Portal Web API

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
Design RESTful (resource-based) RPC-style (action-based)
Endpoints Multiple (per register) Single endpoint
Operations HTTP methods (GET/POST/PATCH) action parameter
Primary Use Data CRUD, integrations Workflows, approvals, portal
Authentication HTTP Basic Auth HTTP Basic Auth
Response Format XML (default) or JSON XML

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)

Operation Performance
2-row financial transactions (POST) ~10 per second
1-row invoices with confirmation 3-4 per second
10,000 transactions (raw data) ~10 seconds (30 MB)
10,000 transactions (10 fields) ~7 seconds (4 MB)

Webhooks (Since 2024)

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

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.

OAuth2 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