WebExcellentAPI - Portal API (1.0.1)

Download OpenAPI specification:

Action-based Web API for Excellent Books ERP Portal operations.

How This API Works

Unlike traditional REST APIs with multiple endpoints, WebExcellentAPI uses a single endpoint with an action parameter that determines the operation:

GET/POST /WebExcellentAPI.hal?action={action_name}&{parameters}

Base URL Example

https://your-server:port/WebExcellentAPI.hal

Authentication

HTTP Basic Authentication (same credentials as REST API)

curl -u username:password "https://server:port/WebExcellentAPI.hal?action=login"

Cookie-Based Sessions (Recommended for Performance): After initial Basic Auth, use the returned HSESSION cookie for subsequent requests to reduce server load significantly.

# Initial request with Basic Auth - save cookies
curl -u username:password "https://server:port/WebExcellentAPI.hal?action=login" -c cookies.txt

# Subsequent requests - use cookie only
curl "https://server:port/WebExcellentAPI.hal?action=pastespecial&register=INVc&id=laptop" \
  -H "Cookie: HSESSION=CC1AC3C5-DAC9C590-DA4FD41F-1E820CB7-C1713CC8"

See REST API documentation for full session configuration details.

Response Format

All responses are XML format
Success responses wrapped in <data> or <res> elements
Errors returned as <error> element or errstr attribute

Quick Reference - Example URLs

Authentication

?action=login
?action=deactivate&usercode=API

Record Operations

?action=delete&register=IVVc&id=12345
?action=deleterow&register=IVVc&id=12345:2,3        (id format: {SerNr}:{rows})
?action=insertrow&register=IVVc&id=12345:1:1       (id format: {SerNr}:{afterRow}:{rowType})
?action=posttext&register=MailVc&id=12345  (POST with body)

Document Generation

?action=document&register=IVVc&id=12345&doccode=INV
?action=document&register=ORVc&id=54321&doccode=ORD&language=est

Attachments (action=action with sub-action in register)

?action=action&register=doupload&regname=IVVc&id=12345  (POST with file)
?action=action&register=getattachlist&regname=IVVc&id=12345
?action=action&register=getfile&regname=IVVc&id=12345&file={uuid}
?action=action&register=deleteattachment&regname=IVVc&id=12345&file={uuid}

Approvals

?action=action&register=checkapprovalstatus&regname=ActVc&id=12345
?action=action&register=sendforapproval&regname=IVVc&id=12345
?action=action&register=approveactivity&id=12345&usercode=JOHN
?action=action&register=rejectactivity&id=12345&usercode=JOHN
?action=action&register=cancelapproval&regname=IVVc&id=12345

Digital Signing (Dokobit)

?action=action&register=createsigningactivity&regname=ORVc&id=12345
?action=action&register=createsigningsess&id=12345
?action=action&register=startsigning&id=12345
?action=action&register=cancelsigning&id=12345&regname=ActVc

Activities & Tasks

?action=action&register=getactivitydata&id=12345
?action=action&register=getcomments&id=12345
?action=action&register=addcomment&id=12345  (POST with comment)
?action=action&register=settaskdescription&id=12345  (POST with text)

Lookups & Search

?action=pastespecial&register=INVc&id=laptop
?action=pastespecial&register=CUVc&id=acme&compno=2
?action=pastespecial&register=AllCUVc&id=john

Note: pastespecial uses id parameter for search text. Returns max 50 results. Search fields: INVc (Code, Name), CUVc/VEVc/AllCUVc (Code, Name, RegNr1), UserVc (Code, Name).

Field Triggers (windowactions)

POST ?action=windowactions  (with Base64-encoded JSON body)
POST ?action=windowactions&usercode=JOHN  (for __new with user defaults)
POST ?action=activeeditfields  (get editable fields state)

List Queries (no action parameter)

?register=IVVc&sd=2024-01-01&ed=2024-12-31&perpage=50
?register=ActVc&search=pending&sortkey=TransDate&order=descending
?register=CUVc&page=1&perpage=100
?register=Kanban&usercode=JOHN

Reports

POST /WebExcellentAPI.hal?action=report
Content-Type: application/json

{"reportwindow": "INEClass", "lang": "EST", "spec": {"d1": "31.12.2025"}, "repname": "InvValRn"}

Employee Portal

?action=action&register=getemployeeinfo&empcode=EMP001
?action=action&register=getvacationbalance&empcode=EMP001
?action=action&register=getemptimeplan&empcode=EMP001&sd=2024-01-01&ed=2024-01-31

Utilities

?action=action&register=getportalusers
?action=action&register=getallusers
?action=action&register=getnotifications&usercode=JOHN
?action=action&register=getdashboardkpi
?action=action&register=copyrecord&regname=IVVc&id=12345
?action=action&register=unokrecord&regname=IVVc&id=12345&usercode=JOHN
?action=action&register=getbilinks&usercode=JOHN
?action=action&register=getactivitytypes

Global Parameters

These parameters can be used with any WebExcellentAPI action:

Parameter	Description
`compno`	Company number (for multi-company databases). If not specified, uses current/default company.
`usercode`	User code for user-specific operations
`portalcc`	Country code for country-specific features (`est` = Estonia, `lat` = Latvia)

Example with company number:

?action=pastespecial&register=INVc&id=laptop&compno=2
?action=action&register=getattachlist&regname=IVVc&id=12345&compno=3

Authentication

Actions: login, deactivate

Login and get system info

Authenticates and returns system configuration including supported features, date formats, and version info.

Example Request:

GET /WebExcellentAPI.hal?action=login
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example Response:

<res>
  <dateformat>YYYY-MM-DD</dateformat>
  <dec_separator>,</dec_separator>
  <apiversion>2.1</apiversion>
  <version>8.5</version>
  <supported>
    <activities>1</activities>
    <invoices>1</invoices>
    <attachments>1</attachments>
    <hassigning>1</hassigning>
  </supported>
</res>

Authorizations:

basicAuthsessionCookie

query Parameters

action

required

string

Value: "login"

Responses

Records

Record manipulation operations including delete, row operations, and text posting.

Actions: delete, deleterow, insertrow, posttext

Supported Registers:

Delete: IVVc, VIVc, ORVc, QTVc, ActVc, CUVc, EPOrderDocVc
Row operations: IVVc, ORVc, VIVc

Delete a record

Deletes a record from the specified register.

Example Request:

GET /WebExcellentAPI.hal?action=delete&register=IVVc&id=12345

Example Response (Success):

<data><res errstr=""/></data>

Example Response (Error):

<data><res errstr="Record is locked"/></data>

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "delete"
register required	string Enum: "IVVc" "VIVc" "ORVc" "QTVc" "ActVc" "CUVc" "EPOrderDocVc" Register to delete from
id required	string Record ID (SerNr)

Responses

Delete rows from record

Deletes specific rows from a multi-row record (invoice, order, etc.).

Important: The id parameter uses a colon-separated format: {SerNr}:{rows}

Example Request:

GET /WebExcellentAPI.hal?action=deleterow&register=IVVc&id=12345:2,3,5

12345 = Record SerNr
2,3,5 = Row numbers to delete (1-based, comma-separated)

Multiple rows can be deleted in a single request.

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "deleterow"
register required	string Enum: "IVVc" "ORVc" "VIVc" "EXCExternalSignersVc" "EXCSignSessVc" "EPOrderDocVc"
id required	string Example: id=12345:2,3 Format: {SerNr}:{rows} - Record ID and comma-separated row numbers

Responses

Insert new row into record

Inserts a new empty row into a multi-row record.

Important: The id parameter uses a colon-separated format: {SerNr}:{afterRow}:{rowType}

Example Request:

GET /WebExcellentAPI.hal?action=insertrow&register=IVVc&id=12345:1:1

12345 = Record SerNr
1 = Insert after row number (0 = at beginning)
1 = Row type (stp field value, typically 1 for normal item row)

Common row types (stp):

1 = Normal item row
2 = Text/comment row
3 = Credit row

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "insertrow"
register required	string Enum: "IVVc" "VIVc" "EXCExternalSignersVc" "EXCSignSessVc"
id required	string Example: id=12345:1:1 Format: {SerNr}:{afterRow}:{rowType} - Record ID, row position, and row type

Responses

Post text content to record

Posts text/HTML content to a record's text field (e.g., email body, document text).

Example Request:

POST /WebExcellentAPI.hal?action=posttext&register=MailVc&id=12345
Content-Type: application/x-www-form-urlencoded

set_field.Math=<p>Email body content here</p>

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "posttext"
register required	string Enum: "MailVc" "EPOrderDocVc"
id required	string

Request Body schema: application/x-www-form-urlencoded
required

set_field.Math

string

Text/HTML content

Responses

Documents

Document generation and PDF printing.

Actions: document

Supported Registers: IVVc, VIVc, ORVc, QTVc, EPOrderDocVc

Generate document PDF

Generates a PDF document for printing or download.

Example Request:

GET /WebExcellentAPI.hal?action=document&register=IVVc&id=12345&doccode=INV

Example Response:

<data>
  <file>
    <name>Invoice_12345.pdf</name>
    <base64>JVBERi0xLjQK...</base64>
  </file>
</data>

The base64 field contains the PDF file encoded in base64.

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "document"
register required	string Enum: "IVVc" "VIVc" "ORVc" "QTVc" "EPOrderDocVc"
id required	string
doccode	string Document template code
language	string Enum: "est" "lat" "eng" Document language

Responses

Attachments

File upload, download, listing, and deletion.

Sub-actions (via action=action):

doupload - Upload file attachment (POST)
getattachlist - List attachments for record
getfile - Download attachment by UUID
deleteattachment - Remove attachment
getrecordlinks - Get linked records
sendemail - Email document with PDF attachment

Supported Registers: IVVc, VIVc, QTVc, StockTakeVc, ORVc, ActVc, CUVc, EPOrderDocVc

File Size Limit: Maximum upload size is configured in Excellent Books: Technics > Registers > Program Settings > Web tab > Max Web Post Size

File Format: Files are transferred as Base64-encoded content wrapped in XML:

<root><file><filename>document.pdf</filename><base64>...</base64></file></root>

doupload - Complete Example

Endpoint:

POST /WebExcellentAPI.hal?action=action&register=doupload&regname=IVVc&id=2525040

Request Body:

<root>
  <file>
    <filename>invoice_scan.pdf</filename>
    <base64>JVBERi0xLjQK...base64_encoded_content...</base64>
  </file>
</root>

Parameters:

action=action - Required for sub-action calls
register=doupload - The sub-action to execute
regname=IVVc - Target register (IVVc, VIVc, ORVc, CUVc, etc.)
id=2525040 - SerNr of the record to attach file to

curl Example:

curl -X POST "https://server:port/WebExcellentAPI.hal?action=action&register=doupload&regname=IVVc&id=2525040" \
  -u username:password \
  -H "Content-Type: application/xml" \
  -d '<root><file><filename>document.pdf</filename><base64>JVBERi0xLjQK...</base64></file></root>'

Success Response:

<data><res errstr="" uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890"/></data>

The returned uuid identifies the uploaded file for later use with getfile or deleteattachment.

sendemail

Sends email with document PDF attachment to the customer/contact. Prerequisites:

Email address must be configured on the customer record
SMTP settings must be configured in Excellent Books
Document template must be available

?action=action&register=sendemail&regname=IVVc&id=10001&usercode=JOHN

Supported registers for sendemail: IVVc, ORVc, QTVc

getrecordlinks

Returns list of records linked to the specified record (e.g., orders linked to invoice).

?action=action&register=getrecordlinks&regname=IVVc&id=10001

Upload file attachment

Uploads a file attachment to a record.

Example Request:

POST /WebExcellentAPI.hal?action=action&register=doupload&regname=IVVc&id=12345
Content-Type: application/xml

<root>
  <file>
    <filename>receipt.pdf</filename>
    <base64>JVBERi0xLjQK...</base64>
  </file>
</root>

Example Response:

<data><res errstr="" uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890"/></data>

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "doupload"
regname required	string Enum: "IVVc" "VIVc" "QTVc" "StockTakeVc" "ORVc" "ActVc" "CUVc" "EPOrderDocVc" "EPShiftSheetVc" Target register
id required	string

Request Body schema: application/xml
required

object

Responses

List attachments for record

Returns list of all attachments for a record.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getattachlist&regname=IVVc&id=12345

Example Response:

<data>
  <attachment uuid="a1b2c3d4..." filename="receipt.pdf" size="102400" date="2024-01-15"/>
  <attachment uuid="e5f67890..." filename="photo.jpg" size="51200" date="2024-01-16"/>
</data>

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "getattachlist"
regname required	string
id required	string

Responses

Download attachment

Downloads an attachment file by UUID.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getfile&regname=IVVc&id=12345&file=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "getfile"
regname required	string
id required	string
file required	string <uuid> File UUID

Responses

Approvals

Approval workflow operations for documents and activities.

Sub-actions (via action=action):

checkapprovalstatus - Get current approval state
sendforapproval - Submit for approval
approveactivity - Approve record
rejectactivity - Reject record
cancelapproval - Cancel pending approval
signactivity - Sign approved record

Approval Status Codes:

0: Not requested
1: Not required
2: Not started
3: Pending
4: Approved
5: Rejected

Check approval status

Returns the current approval status of a record.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=checkapprovalstatus&regname=IVVc&id=12345

Example Response:

<data>
  <res errstr="" regname="IVVc"/>
  <DummyVc>
    <hasapprovals>1</hasapprovals>
    <approvalstatus>3</approvalstatus>
    <message>Waiting for approval from MANAGER</message>
    <cancancel>1</cancancel>
  </DummyVc>
</data>

Status Codes:

0: Not requested
1: Not required
2: Not started
3: Pending
4: Approved
5: Rejected

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "checkapprovalstatus"
regname required	string Enum: "ActVc" "IVVc" "VIVc" "ORVc" "QTVc" "EPOrderDocVc"
id required	string

Responses

Submit record for approval

Submits a record to the approval workflow.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=sendforapproval&regname=IVVc&id=12345

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "sendforapproval"
regname required	string
id required	string

Responses

Approve a record

Approves a record pending approval.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=approveactivity&id=12345&usercode=MANAGER

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "approveactivity"
id required	string
usercode required	string Approver's user code

Responses

Reject a record

Rejects a record pending approval.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=rejectactivity&id=12345&usercode=MANAGER

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "rejectactivity"
id required	string
usercode required	string

Responses

Signing

Digital signing operations using Dokobit integration.

Sub-actions (via action=action):

createsigningactivity - Create signing activity for document
createsigningsess - Create signing session
startsigning - Initiate signing process
cancelsigning - Cancel signing session

Supported for: ORVc, IVVc, EPOrderDocVc, EPContractVc

Create signing activity

Creates a digital signing activity for a document (Dokobit integration).

Example Request:

GET /WebExcellentAPI.hal?action=action&register=createsigningactivity&regname=ORVc&id=12345

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "createsigningactivity"
regname required	string Enum: "ORVc" "IVVc" "EPOrderDocVc" "EPContractVc" "EPTS2Vc"
id required	string

Responses

Start signing process

Initiates the digital signing process for a signer.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=startsigning&id=12345

Returns a URL to redirect the user to the Dokobit signing interface.

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "startsigning"
id required	string Signing activity or session SerNr
usercode	string User code (optional, uses session user if not specified)

Responses

Activities

Activity and task management operations.

Sub-actions (via action=action):

getactivitydata - Get activity details
getcomments - Get activity comments
addcomment - Add comment to activity
settaskdescription - Update task description
getactivitytypes - List available activity types

Lookups

Paste special, search, and field trigger operations.

Actions: pastespecial, windowactions, activeeditfields

pastespecial

Search for records to populate lookup fields.

Supported Registers: INVc, CUVc, VEVc, AllCUVc, UserVc

windowactions - Field Trigger API

Simulates field changes in the UI, executing business logic and returning computed values. This is useful for building custom form UIs that need real-time field calculations without saving the record.

Supported Registers: IVVc, ORVc, CUVc, ActVc, QTVc, VIVc

How it works:

Client sends current record state + field being changed
Server executes all business logic for that field change
Server returns updated record with all computed/derived fields

Use Cases:

Customer changed -> load payment terms, addresses, language
Item code entered -> load price, VAT code, description
Quantity changed -> recalculate line totals and sums
Currency changed -> update exchange rates

Special Fields:

__new - Initialize a new empty record with defaults
__copy - Duplicate an existing record

activeeditfields

Returns which fields are currently editable based on record state.

Supported Registers: ORVc, CUVc

Use Cases:

ORVc: Check if order rows are locked (has shipments)
CUVc: Get classification rules for conditional field display

Search records (paste special)

Searches for records to use in paste special / lookup fields.

Note: This endpoint uses the id parameter for the search text (not search). Returns a maximum of 50 results (hardcoded limit, pagination not supported).

Searchable Fields by Register:

Register	Fields Searched
INVc	Code, Name
CUVc	Code, Name, RegNr1
VEVc	Code, Name, RegNr1 (vendors only)
AllCUVc	Code, Name, RegNr1 (all contacts)
UserVc	Code, Name

Search Behavior:

Space-separated terms are ANDed (all must match)
Case-insensitive prefix matching
Example: id=laptop dell matches items containing BOTH "laptop" AND "dell"

Example Request:

GET /WebExcellentAPI.hal?action=pastespecial&register=INVc&id=laptop
GET /WebExcellentAPI.hal?action=pastespecial&register=CUVc&id=ACME&compno=2

Example Response:

<data>
  <INVc>
    <Code>LAPTOP01</Code>
    <Name>Dell Laptop 15"</Name>
    <UPrice1>899.00</UPrice1>
  </INVc>
  <INVc>
    <Code>LAPTOP02</Code>
    <Name>HP Laptop 14"</Name>
    <UPrice1>749.00</UPrice1>
  </INVc>
</data>

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "pastespecial"
register required	string Enum: "INVc" "CUVc" "VEVc" "AllCUVc" "UserVc" Register to search in
id required	string Search text. Searched fields depend on register: INVc: Code, Name CUVc/VEVc/AllCUVc: Code, Name, RegNr1 UserVc: Code, Name
compno	integer Company number (for multi-company databases)
bfilter	string Additional filter (only for INVc)

Responses

Execute field change logic (Field Triggers)

Simulates a field value change in the UI and returns the record with all computed/derived fields updated. This is the core API for building custom form UIs that need real-time field calculations.

The request body must be Base64-encoded JSON (reversed byte order, then Base64).

Supported Registers: IVVc, ORVc, CUVc, ActVc, QTVc, VIVc

Request Body Structure (JSON before encoding)

{
  "vcname": "IVVc",
  "fieldname": "CustCode",
  "value": "ACME",
  "rowindex": -1,
  "headerfields": "CustCode:1,PayDeal:1,Addr0:1,CurncyCode:1",
  "rowfields": "ArtCode:1,Quant:5,Price:5,Sum:5",
  "values": {
    "header": {
      "CustCode": "ACME",
      "InvDate": "2024-01-15"
    },
    "rows": [
      {"stp": 1, "ArtCode": "ITEM01", "Quant": "2", "Price": "100.00"}
    ]
  }
}

Field Type Codes (in headerfields/rowfields):

1 = String
2 = Date (YYYY-MM-DD)
5 = Decimal value
12 = Decimal value
15 = Decimal value (1 decimal place)

Trigger Fields by Register

IVVc (Sales Invoice)

Field	Triggers	Description
`CustCode`	Address, PayDeal, Language, Region, SalesMan	Loads customer defaults
`ArtCode`	Price, VATCode, Description, SalesAcc	Loads item defaults
`Quant`	Sum, row recalculation	Recalculates line total
`Price`	Sum, row recalculation	Recalculates line total
`CurncyCode`	FrRate, ToRateB1, ToRateB2, BaseSum4	Updates exchange rates
`PayDeal`	PayDate, PriceList	Loads payment terms
`InvDate`	Exchange rates, periods	Updates date-dependent values
`VATCode`	VAT calculation	Recalculates VAT
`Sum`	vRebate back-calculation	Calculates discount from sum
`SerialNr`	Dimensions, quantity	Loads serial number data
`UnitCode`	UnitFactor calculations	Updates unit conversions
`Location`	Stock validation	Validates stock location
`__new`	All defaults	Creates new empty invoice
`__copy`	Duplicate record	Copies existing invoice

ORVc (Sales Order)

Field	Triggers	Description
`CustCode`	Address, PayDeal, SalesMan	Loads customer defaults
`ArtCode`	Price, VATCode, Description	Loads item defaults
`Quant`	Sum, Price recalculation	Recalculates line (may update price for quantity discounts)
`Price`	Sum recalculation	Recalculates line total
`PlanShip`	Delivery date, PriceList	Updates planned shipment
`SerialNr`	Item, Location, Dimensions	Loads serial number and item
`__new`	All defaults	Creates new empty order
`__copy`	Duplicate record	Copies existing order

CUVc (Contact)

Field	Triggers	Description
`RegNr2`	VAT validation	Validates registration number
`Name`	Search/validation	Name processing
`Person`	Mobile from contact relation	Loads contact person mobile
`CountryCode`	Address format	Updates address format
`IBANCode`	IBAN validation	Validates bank account
`VATNr`	VAT law validation	Validates VAT number
`__new`	All defaults	Creates new contact
`__copy`	Duplicate record	Copies existing contact

ActVc (Activity)

Field	Triggers	Description
`CUCode`	CUName, Phone, Contact	Loads customer info
`ActType`	Default values	Loads activity type defaults
`TransDate`	EndDate, CostTime	Calculates duration
`StartTime`	CostTime calculation	Recalculates duration
`EndTime`	CostTime calculation	Recalculates duration
`ActResult`	EndTime, CostTime	Closes activity
`MainPersons`	Expands user codes	Expands group to users
`__new`	All defaults	Creates new activity
`__prepareActivity`	From source record	Creates activity from order/invoice

QTVc (Quotation)

Field	Triggers	Description
`CustCode`	Address, PayDeal, PriceList	Loads customer defaults
`ArtCode`	Price, VATCode, Description	Loads item defaults
`Quant`	Sum, Price recalculation	Recalculates line
`Price`	Sum recalculation	Recalculates line total
`PriceList`	Item prices update	Updates all row prices
`QTDate`	Validity dates	Updates related dates
`__new`	All defaults	Creates new quotation
`__copy`	Duplicate record	Copies existing quotation

VIVc (Purchase Invoice)

Field	Triggers	Description
`VECode`	VAT codes, Objects	Loads vendor defaults
`PayVal`	VATVal calculation	Recalculates VAT
`AccNumber`	Objects, defaults	Loads account defaults
`VATCode`	VAT calculation	Updates VAT amounts
`Sum`	Totals recalculation	Recalculates totals
`PayDeal`	DueDate	Loads payment terms
`CredInv`	Rate, POSerNr	Loads credit invoice source
`__new`	All defaults	Creates new purchase invoice
`__copy`	Duplicate record	Copies existing invoice

Response Format

{
  "success": true,
  "res": true,
  "messages": [
    {"description": "Customer credit limit exceeded"}
  ],
  "record": {
    "CustCode": "ACME",
    "Addr0": "ACME Corporation",
    "PayDeal": "NET30",
    "Sum4": "242.00",
    "rows": [
      {"ArtCode": "ITEM01", "Quant": "2", "Price": "100.00", "Sum": "200.00"}
    ]
  }
}

Response Fields:

success - Always true for successful response
res - Operation result
messages - Array of warning messages (if any)
record - Updated record with computed values

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "windowactions"
usercode	string User code for defaults (used with __new)

Request Body schema: application/octet-stream
required

Base64-encoded JSON (reversed byte order)

string <byte>

Responses

Response samples

Content type

application/json

{"success": true,
"res": true,
"messages": [{"description": "Customer credit limit exceeded"
}
],
"record": {"rows": [{"property1": "string",
"property2": "string"
}
],
"property1": "string",
"property2": "string"
},
"activeFields": {"headerFields": true,
"matrixFields": true,
"exceptionHeaderList": "string",
"exceptionMatrixList": "string"
},
"rules": [{"rulefield": "string",
"rulename": "string",
"rulevalue": "string"
}
]
}

Get active/editable fields

Returns information about which fields are currently editable based on record state. Useful for dynamically enabling/disabling form fields in custom UI.

Supported Registers: ORVc, CUVc

Request Body Structure (JSON before encoding)

{
  "vcname": "ORVc",
  "id": "12345"
}

Per-Register Behavior

ORVc (Sales Order)

Checks if the order has any shipments (deliveries created).

Condition	headerFields	matrixFields	exceptionHeaderList
No shipments	true	true	(empty)
Has shipments	true	false	CustCode

When an order has been partially or fully shipped, the row fields become read-only to prevent changes that would conflict with the delivery. The customer code is also locked to maintain data integrity.

CUVc (Contact)

Returns dynamic rules based on the contact customer class (CCatVc.ClassType). These rules can be used by the UI to show/hide fields or apply validation.

Example: If contact has class with ClassType=COMPANY, returns:

{
  "rules": [
    {
      "rulefield": "Classification",
      "rulename": "type",
      "rulevalue": "COMPANY"
    }
  ]
}

The UI can use these rules to conditionally display fields relevant to companies vs individuals (e.g., show RegNr1 for companies, hide for private persons).

Response Structure

Response includes:

success - Always true for successful response
res - Operation result
activeFields - Field editability flags
- headerFields - Whether header fields are editable (default: true)
- matrixFields - Whether row fields are editable (default: true)
- exceptionHeaderList - Comma-separated list of locked header fields
- exceptionMatrixList - Comma-separated list of locked row fields
rules - Array of dynamic rules (CUVc only)

Example Response (ORVc with shipments):

{
  "success": true,
  "res": true,
  "activeFields": {
    "headerFields": true,
    "matrixFields": false,
    "exceptionHeaderList": "CustCode",
    "exceptionMatrixList": ""
  }
}

Example Response (CUVc with company class):

{
  "success": true,
  "res": true,
  "activeFields": {
    "headerFields": true,
    "matrixFields": true,
    "exceptionHeaderList": "",
    "exceptionMatrixList": ""
  },
  "rules": [
    {
      "rulefield": "Classification",
      "rulename": "type",
      "rulevalue": "COMPANY"
    }
  ]
}

Authorizations:

basicAuthsessionCookie

query Parameters

action

required

string

Value: "activeeditfields"

Request Body schema: application/octet-stream
required

Base64-encoded JSON with vcname and record id

string <byte>

Responses

Response samples

Content type

application/json

{"success": true,
"res": true,
"activeFields": {"headerFields": true,
"matrixFields": true,
"exceptionHeaderList": "string",
"exceptionMatrixList": "string"
},
"rules": [{"rulefield": "string",
"rulename": "string",
"rulevalue": "string"
}
]
}

Lists

Data listing and browsing with pagination and filtering.

Usage: Omit action parameter, use register directly

Supported Registers:

INVc (Items)
CUVc (Contacts)
ActVc (Activities)
Kanban (Kanban board)
IVVc (Invoices)
VIVc (Purchase Invoices)
ORVc (Sales Orders)
QTVc (Quotations)
StockTakeVc (Stock Takes)

Common Parameters:

page - Page number (1-based)
perpage - Records per page (max 100)
search - Search text
sortkey - Sort field
order - ascending/descending
sd, ed - Date range

List records with pagination

Retrieves a paginated list of records. Note: No action parameter - use register directly.

Example Requests:

GET /WebExcellentAPI.hal?register=IVVc&sd=2024-01-01&ed=2024-12-31&perpage=50
GET /WebExcellentAPI.hal?register=ActVc&search=pending&page=2
GET /WebExcellentAPI.hal?register=CUVc&sortkey=Name&order=ascending

Example Response:

<data count="150" page="1" perpage="50" totalpages="3">
  <IVVc>
    <SerNr>10001</SerNr>
    <InvDate>2024-01-15</InvDate>
    <CustCode>ACME</CustCode>
    <Sum4>1250.00</Sum4>
  </IVVc>
  <!-- more records... -->
</data>

Authorizations:

basicAuthsessionCookie

query Parameters

register required	string Enum: "INVc" "CUVc" "ActVc" "Kanban" "IVVc" "VIVc" "StockTakeVc" "ORVc" "QTVc" "EPOrderDocVc" Register to list
page	integer >= 1
perpage	integer [ 1 .. 100 ]
search	string
sortkey	string
order	string Enum: "ascending" "descending"
sd	string <date> Start date (YYYY-MM-DD)
ed	string <date> End date (YYYY-MM-DD)
usercode	string
bfilter	string Additional filter fields

Responses

Reports

Report generation operations.

Actions: report (POST with JSON body)

JSON Body Fields:

reportwindow - Report window class name (e.g., INEClass, AT2ListRClass)
repname - Internal report name (e.g., InvValRn, AT2ListRn)
lang - Language code (e.g., EST, ENG)
spec - Object with report-specific parameters (dates, filters, etc.)

Generate report

Runs an API report and returns results. Requires a POST request with JSON body.

Example Request:

POST /WebExcellentAPI.hal?action=report
Content-Type: application/json

{
  "reportwindow": "INEClass",
  "lang": "EST",
  "spec": {
    "d1": "31.12.2025",
    "f2": "PLU"
  },
  "repname": "InvValRn"
}

Authorizations:

basicAuthsessionCookie

query Parameters

action

required

string

Value: "report"

Request Body schema: application/json
required

reportwindow required	string Report window class name
repname required	string Internal report name
lang	string Language code
	object Report-specific parameters (dates, filters, etc.)

Responses

Request samples

Payload

Content type

application/json

{"reportwindow": "INEClass",
"repname": "InvValRn",
"lang": "EST",
"spec": {"d1": "31.12.2025",
"f2": "PLU"
}
}

Portal

Employee portal specific operations.

Sub-actions (via action=action):

getemployeeinfo - Employee details
getvacationbalance - Vacation days balance
getemptimeplan - Work schedule
getemptimeplannewformat - Work schedule (new format)
getcontactpersons - Contact persons list
getapprovalpersons - Available approvers

Get employee information

Returns detailed employee information for portal users.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getemployeeinfo&empcode=EMP001

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "getemployeeinfo"
empcode required	string

Responses

Get vacation balance

Returns employee's vacation days balance.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getvacationbalance&empcode=EMP001

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "getvacationbalance"
empcode required	string

Responses

Record Creation

Document conversion operations for sales workflows (quotation → order → invoice).

Sub-actions (via action=action):

createslinvoicefromorder - Create sales invoice from sales order
createsalesorderfromquotation - Create sales order from quotation
createslinvoicefromquotation - Create sales invoice directly from quotation
copyrecord - Duplicate an existing record
unokrecord - Remove OK status (return to draft)

createslinvoicefromorder

Creates a sales invoice from an existing sales order.

?action=action&register=createslinvoicefromorder&id={ORVc_SerNr}&usercode=JOHN

Response: <data><res errstr="" newdata="10001"/></data> The newdata attribute contains the new invoice SerNr.

createsalesorderfromquotation

Creates a sales order from an existing quotation.

?action=action&register=createsalesorderfromquotation&id={QTVc_SerNr}&regname=QTVc&usercode=JOHN

createslinvoicefromquotation

Creates a sales invoice directly from a quotation (skipping order stage).

?action=action&register=createslinvoicefromquotation&id={QTVc_SerNr}&regname=QTVc&usercode=JOHN

copyrecord

Duplicates an existing record. Currently supports IVVc (invoices). New record gets current date and OKFlag=0 (draft).

?action=action&register=copyrecord&regname=IVVc&id=12345

unokrecord

Reverses record confirmation (sets OKFlag from 1 to 0). Requires appropriate access permissions (EXCPortalUnOK action). Supported registers: IVVc, ORVc, PlanAbsenceVc

?action=action&register=unokrecord&regname=IVVc&id=12345&usercode=JOHN

Create invoice from sales order

Creates a sales invoice from an existing sales order.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=createslinvoicefromorder&id=5001&usercode=JOHN

Example Response:

<data>
  <res errstr="" newdata="10001"/>
</data>

The newdata attribute contains the SerNr of the newly created invoice.

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "createslinvoicefromorder"
id required	string Sales order SerNr (from ORVc)
usercode required	string

Responses

Create sales order from quotation

Creates a sales order from an existing quotation.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=createsalesorderfromquotation&id=3001&regname=QTVc&usercode=JOHN

Example Response:

<data>
  <res errstr="" newdata="5001"/>
</data>

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "createsalesorderfromquotation"
id required	string Quotation SerNr (from QTVc)
regname required	string Value: "QTVc"
usercode required	string

Responses

Create invoice from quotation

Creates a sales invoice directly from a quotation (skipping the sales order stage).

Example Request:

GET /WebExcellentAPI.hal?action=action&register=createslinvoicefromquotation&id=3001&regname=QTVc&usercode=JOHN

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "createslinvoicefromquotation"
id required	string Quotation SerNr (from QTVc)
regname required	string Value: "QTVc"
usercode required	string

Responses

Duplicate a record

Creates a copy of an existing record.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=copyrecord&regname=IVVc&id=10001

Behavior:

Creates new record with data from source
Sets date to current date
Sets OKFlag=0 (draft)
Generates new SerNr

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "copyrecord"
regname required	string Value: "IVVc" Currently only IVVc supported
id required	string

Responses

Remove OK status from record

Reverses record confirmation, returning it to draft state (OKFlag=0).

Example Request:

GET /WebExcellentAPI.hal?action=action&register=unokrecord&regname=IVVc&id=10001&usercode=JOHN

Requirements:

User must have EXCPortalUnOK permission
Record must be in confirmed state (OKFlag=1)

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "unokrecord"
regname required	string Enum: "IVVc" "ORVc" "PlanAbsenceVc"
id required	string
usercode required	string
portalcc	string Enum: "est" "lat" Country code for country-specific rules

Responses

Utilities

Utility and meta operations.

Sub-actions (via action=action):

hasusernewapi - Check if user has new API access
getportalusers - List portal users
getadminusers - List admin users
getallusers - List all users
getnotifications - User notifications
getdashboardkpi - Dashboard KPIs
linktosourcerecord - Create activity link to source record
getrecordlinks - Get records linked to a record
getbilinks - Get Business Intelligence portal links
getactivitytypes - List available activity types with signing info
registerapi - Register callback URL for webhooks
buildrecidstr - Build standardized record ID string

hasusernewapi

Checks if the current user has access to new API features.

?action=action&register=hasusernewapi&usercode=JOHN

Response: <data><res errstr="" hasapi="1"/></data>

getrecordlinks

Returns list of records linked to the specified record.

?action=action&register=getrecordlinks&regname=IVVc&id=12345

getbilinks

Returns Business Intelligence portal links for FlexBI integration.

?action=action&register=getbilinks&usercode=JOHN&id={accessId}

Response includes salesanalysis and customeranalysis URLs. Links only returned if user has EXCPortalShowInvoices permission.

getactivitytypes

Lists all configured activity types (ActTypVc).

?action=action&register=getactivitytypes

registerapi

Registers an external callback URL for webhook notifications.

?action=action&register=registerapi&UUID={uuid}&url={url}&port={port}&path={path}

buildrecidstr

Builds a standardized record ID string for cross-system references.

?action=action&register=buildrecidstr&code={code}&vcname={vcname}&compno={compno}

Data Limits

Some operations have row limits to prevent performance issues:

Operation	Default Limit	Extended Limit
Cash flow data	2,000 rows	30,000 rows (with limitf=false)
List queries	100 per page	Use pagination
Kanban columns	maxsize parameter	Configurable

Country-Specific Features (portalcc parameter)

Some operations have country-specific implementations. Use the portalcc parameter:

portalcc=est - Estonia-specific (ESTPayroll module)
portalcc=lat - Latvia-specific (LATPayroll module)

Estonia-specific actions:

Employee time plans with Estonian calendar
Estonian payroll vacation balance
Estonian tax calculations
Estonian e-invoice formats

Latvia-specific actions:

Latvian payroll calculations
Latvian tax rules
Latvian approval workflows

Example:

?action=action&register=getvacationbalance&empcode=EMP001&portalcc=est

Get user notifications

Returns pending notifications for a user.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getnotifications&usercode=JOHN

Authorizations:

basicAuthsessionCookie

query Parameters

action required	string Value: "action"
register required	string Value: "getnotifications"
usercode required	string

Responses

Extensibility

WebExcellentAPI can be extended with custom actions, registers, and field triggers using HAL extension functions.

These extension points allow partners to add new functionality without modifying the core API code. Each extension function is a global procedure defined in a HAL file and automatically called by the API when relevant.

Extension Functions Reference

Extension Function	Purpose	Called When
`OuterExcellentAPIActions`	Add custom sub-actions	`action=action&register={YourAction}`
`OuterExcellentAPIDeleteRecord`	Add custom registers to delete	`action=delete&register={YourRegister}`
`OuterExcellentAPIDeleteRow`	Add custom registers to deleterow	`action=deleterow`
`OuterExcellentAPIInsertRow`	Add custom registers to insertrow	`action=insertrow`
`OuterExcellentAPIPostText`	Add custom registers to posttext	`action=posttext`
`OuterExcellentAPIPrint`	Add custom document types	`action=document`
`OuterExcellentAPIPasteSpecial`	Add custom registers to search	`action=pastespecial`
`OuterExcellentAPIGetList`	Add custom list types	List queries (no action)
`OuterExcellentAPIWindowActions`	Add custom field triggers	`action=windowactions`

Country-specific variants are also supported by appending _EST or _LAT suffix (e.g., OuterExcellentAPIDeleteRecord_EST).

OuterExcellentAPIActions - Custom Sub-Actions

This is the most commonly used extension point. It allows you to add completely new sub-actions to the action=action endpoint.

HAL Signature (6 parameters):

global
procedure OuterExcellentAPIActions(
  string type,         // Value of register= parameter (the sub-action name)
  string empcode,      // Employee code from query string
  string usercode,     // User code from query string
  string id,           // ID from query string
  string err,          // Error string
  var Boolean outputf  // Set to false when you handle the response
)

URL pattern:

POST /WebExcellentAPI.hal?action=action&register=MyCustomAction&id=12345&usercode=JOHN

Example implementation:

global
procedure OuterExcellentAPIActions(string type, string empcode, string usercode,
                                   string id, string err, var Boolean outputf)
begin
  switch (type) begin
    case "MyCustomAction":
      HandleMyCustomAction(id, usercode);
      outputf = false;   // false = we handled the output
  end;
  return;
end;

When outputf is set to false, the extension function is responsible for writing the HTTP response (e.g., using WebOutString, WebSetContentType, SetHTTPResponseStatus).

OuterExcellentAPIPasteSpecial - Custom Search Registers

Add new registers to the pastespecial action for lookup/search functionality.

URL pattern:

GET /WebExcellentAPI.hal?action=pastespecial&register=MyRegister&id=searchtext

OuterExcellentAPIGetList - Custom List Types

Add new list types for the list query endpoint (no action parameter).

URL pattern:

GET /WebExcellentAPI.hal?register=MyListType&page=1&perpage=50&search=text

OuterExcellentAPIWindowActions - Custom Field Triggers

Add custom field trigger logic for registers in the windowactions endpoint.

Architecture Notes for Extensions

Extension functions are global procedure (not function)
They are called automatically if defined - no registration needed
For sub-actions that modify the database, delegate to a remote updating procedure
Web handlers (global procedures) cannot modify the database directly
Use temp files to pass large payloads across the remote procedure boundary (areas cannot cross)

3-file pattern for database-modifying extensions:

Web handler file: global procedure (HTTP I/O + validation)
Remote file: remote updating procedure (database operations)
Data definition file: settings block for configuration (API keys, secrets)

WebExcellentAPI - Portal API (1.0.1)

How This API Works

Base URL Example

Authentication

Response Format

Quick Reference - Example URLs

Authentication

Record Operations

Document Generation

Attachments (action=action with sub-action in register)

Approvals

Digital Signing (Dokobit)

Activities & Tasks

Lookups & Search

Field Triggers (windowactions)

List Queries (no action parameter)

Reports

Employee Portal

Utilities

Global Parameters

Authentication

Login and get system info

Authorizations:

query Parameters

Responses

Records

Delete a record

Authorizations:

query Parameters

Responses

Delete rows from record

Authorizations:

query Parameters

Responses

Insert new row into record

Authorizations:

query Parameters

Responses

Post text content to record

Authorizations:

query Parameters

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Documents

Generate document PDF

Authorizations:

query Parameters

Responses

Attachments

doupload - Complete Example

sendemail

getrecordlinks

Upload file attachment

Authorizations:

query Parameters

Request Body schema: application/xmlrequired

Responses

List attachments for record

Authorizations:

query Parameters

Responses

Download attachment

Authorizations:

query Parameters

Responses

Approvals

Check approval status

Authorizations:

query Parameters

Responses

Submit record for approval

Authorizations:

query Parameters

Responses

Approve a record

Authorizations:

query Parameters

Responses

Reject a record

Authorizations:

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/xml
required

Request Body schema: application/octet-stream
required

Request Body schema: application/octet-stream
required

Request Body schema: application/json
required