WebExcellentAPI - Portal API (1.0.2.3)

Returns system formats, version information, employee data, portal access and supported capabilities. Capability values emitted in supported are yes. hassigning is included only when Dokobit is enabled; nonewtimetables depends on portal settings. Country-specific capabilities depend on portalcc. The example shows a subset of the response.

Example Request:

GET /WebExcellentAPI.hal?action=login&usercode=JOHN&portalcc=est

Example Response:

<res>
  <supported>
    <sendemail>yes</sendemail>
    <usesessions>yes</usesessions>
    <hasnotifications>yes</hasnotifications>
    <createslinvoicefromorder>yes</createslinvoicefromorder>
    <approvalrules>yes</approvalrules>
    <unok>yes</unok>
    <haspagination>yes</haspagination>
  </supported>
</res>

Sets EXCPortalBlock.UseHRPortal to 0, stores the block, and invokes the close-service operation for class 92 with an empty second argument. Returns JSON {"res":"OK"}.

The deactivation branch does not require a usercode or test portal admin/accountant rights. usercode is read by the dispatcher for language/access setup.

Example Request:

GET /WebExcellentAPI.hal?action=deactivate

Example Response:

{"res":"OK"}

Deletes a record. The response is <data></data> when the handler reports no error; errors use <data><error>...</error></data>. An empty response does not establish that a record was found.

Example Request:

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

Example Response:

<data></data>

Deletes rows using zero-based matrix indexes: id={recordId}:{rows}. IVVc, IPVc, ORVc, QTVc, VIVc, OPVc, ActVc and EPOrderDocVc accept comma-separated indexes and delete them from highest to lowest. EXCExternalSignersVc and EXCSignSessVc accept one index. EXCSignSessVc uses a UUID as recordId; the other listed registers use SerNr. Errors use <data><error>...</error></data>.

Example Request:

GET /WebExcellentAPI.hal?action=deleterow&register=IVVc&id=10001:0,2

Example Response:

<data></data>

Inserts a row at the zero-based matrix position in id={recordId}:{rowIndex}:{stp}. Position 0 inserts at the beginning. The index is passed directly to the insertion routine. stp is passed to the register row initializer; its meaning depends on the register. EXCSignSessVc uses a UUID as recordId; the other listed registers use SerNr. Errors use <data><error>...</error></data>.

Example Request:

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

Example Response:

<data></data>

Writes form field set_field.Math to a record text field. For MailVc, the mail must have an activity description link; arbitrary mail bodies are not updated by this handler. EPOrderDocVc is read by SerNr. Errors, when reported, use an error element.

Example Request:

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

set_field.Math=Example%20description

Example Response:

<data></data>

Generates a PDF and returns its filename and Base64 content in data/file. The handler chooses the document form. doccode and language query parameters are not read. Errors, when reported, appear in data/error.

Example Request:

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

Example Response:

<data><file><name>DOCUMENT_10001.pdf</name><base64>BASE64_PDF</base64></file></data>

Uploads XML with root file and children filename and base64. The standard response has empty errstr and newdata; it does not return an attachment UUID or confirm storage. Use getattachlist to check the result and obtain the UUID.

Example Request:

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

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

Example Response:

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

Returns attachment rows inside data, preceded by res regname='AttachVc'. Each row contains UUID, Name and Size. Size is copied from Attach2Vc.FileSize; this handler does not convert units.

Example Request:

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

Example Response:

<data><res regname='AttachVc'></res><AttachVc><UUID>00000000-0000-0000-0000-000000000001</UUID><Name>document.pdf</Name><Size>100</Size></AttachVc></data>

Returns the matching attachment as Base64 text in data/file. If no matching attachment is found, the response is <data><res></res></data>.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getfile&regname=IVVc&id=10001&file=00000000-0000-0000-0000-000000000001

Example Response:

<data><res></res><file>BASE64_FILE</file></data>

Returns approval data in DummyVc; the response marker is res/@regname=DummyVc, regardless of the requested register. Fields are hasapprovals, cancancel, approvalstatus, message and approvaldate. approvalstatus is the ERP integer status. The example illustrates the response fields without assigning a meaning to the status number.

Example Request:

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

Example Response:

<data><res errstr='' regname='DummyVc'></res><DummyVc><hasapprovals>1</hasapprovals><cancancel>0</cancancel><approvalstatus>3</approvalstatus><message></message><approvaldate></approvaldate></DummyVc></data>

Submits a record to the approval workflow.

Supported registers: IVVc, VIVc, ORVc, QTVc, ActVc, EPOrderDocVc, OPVc

Example Request:

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

Approves an unconfirmed approval activity only when usercode is included in its MainPersons. The supplied id is an ActVc SerNr. The standard empty result is also returned when these conditions are not met; it does not confirm that the activity changed.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=approveactivity&id=10001&usercode=JOHN

Example Response:

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

Rejects an unconfirmed approval activity only when usercode is included in its MainPersons. The supplied id is an ActVc SerNr. The standard empty result is also returned when these conditions are not met; it does not confirm that the activity changed.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=rejectactivity&id=10001&usercode=JOHN

Example Response:

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

Returns XML with res/@regname=PersonVc. Each resolved user has Name, numeric Status, UserCode, canreject, canapprove, cansign and activity SerNr elements.

For the core register cases, the handler reads the record and its acceptance rules and collects linked activities with the approval flag and Invalid=0. After collection it keeps the greatest activity number per user code, and emits only entries whose user lookup succeeds. Status is the integer returned by the approval-state helper.

canapprove and canreject start at 0 and become 1 when a linked activity has MainPersons exactly equal to usercode and OKFlag=0. These variables are not reset between linked activities, so subsequent rows can retain 1. cansign remains 0 in these collection branches. The flags describe the values emitted by this handler.

Core register cases are IVVc, VIVc, ORVc, QTVc, EPOrderDocVc, OPVc and ActVc. Additional cases are PlanAbsenceVc and EPShiftSheetVc through the EST implementation, or EPOffWorkPlanVc and EPShiftSheetVc through the LAT implementation, selected by the installed payroll implementation. portalcc does not select this extension.

Example Request:

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

The example response shows an empty list.

Example Response:

<data><res regname="PersonVc"></res></data>

The creation block is disabled in production, including register-specific and payroll delegation. This operation does not create a signing activity. The response emits the serial number of an unpopulated activity record; it is not a newly created activity ID.

Example Request:

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

Example Response:

<data><res newdata='0'></res></data>

Starts signing for an unconfirmed activity whose type permits signatures, excluding approval activities. The response contains errstr and an empty newdata; this handler never assigns a signing URL to newdata.

Example Request:

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

Example Response:

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

Loads the signing session contact list only when the activity exists, OKFlag=0, TodoFlag is not the approval flag, and its activity type has AllowSignature=1. The signing session is looked up by current company and activity number.

Returns XML with res/@regname=PersonVc and empty errstr and newdata attributes. Each PersonVc contains Name, Status (the contact email address) and JobTitle (the contact job description). If the prerequisites or session lookup fail, the res element is still returned with no person rows. The helper does not check usercode against the activity persons.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getcontactpersons&id=10001

Example Response:

<data><res errstr="" newdata="" regname="PersonVc"></res>
  <PersonVc><Name>Example signer</Name><Status>signer@example.invalid</Status><JobTitle>Manager</JobTitle></PersonVc>
</data>

Requests a Dokobit signing link only when the activity exists, OKFlag=0, usercode belongs to MainPersons, TodoFlag is not the approval flag, and the activity type exists with AllowSignature=1.

Returns XML <data><res errstr="..." newdata="..."></res></data>. newdata contains the link returned by the signing helper; errstr contains its error text with double quotes removed. If the eligibility checks fail, both attributes remain empty.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=signactivity&usercode=JOHN&id=10001

Example Response:

<data><res errstr="" newdata="https://SIGNING-SERVER/signing/SESSION-ID"></res></data>

When the activity exists and both source parameters are nonblank, creates record links in both directions between the activity and the supported source record, in the current company. The source record must also exist.

CUVc and EmplVc use Code; EPEmpVc uses EmpCode. Other supported sources use numeric SerNr. For EPOrderDocVc, AbsenceVc, EPOffWorkVc, PlanAbsenceVc, EPOffWorkPlanVc, EPShiftSheetVc, WorkedHoursVc and EPTS2Vc, the converted source number must also be positive.

Flushes the database and returns <data><res></res></data>, including when no links were created because an input, record or supported register case was missing. The response does not confirm that a link was created.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=linktosourcerecord&id=10001&sourceRegName=IVVc&sourceRecordId=10002

Example Response:

<data><res></res></data>

Looks up records using URL-decoded id as search text and requests at most 50 record IDs. INVc, CUVc, VEVc, AllCUVc, UserVc, APVc and ARVc are handled by production. Record element names retain their register names; their field element names are lowercase. For INVc, bfilter is the stock location used to calculate instock.

Example Request:

GET /WebExcellentAPI.hal?action=pastespecial&register=INVc&id=ITEM

Example Response:

<data><INVc><code>ITEM01</code><name>Example item</name><uprice1>100.00</uprice1><instock>5</instock><group>GROUP01</group><eucodex></eucodex></INVc></data>

Applies a field trigger to the supplied record values and returns JSON. Plain JSON is the default. For legacy encrypted=true, Base64-encode the JSON bytes, then reverse the Base64 text. The server reverses that text before Base64 decoding.

Use rowindex=-1 for a header field and a zero-based row index for a matrix field. headerfields and rowfields select fields and type codes as FieldName:TypeCode: 2 parses ISO dates; 5, 12 and 15 parse decimal values; other codes use strings. Type 15 is returned with one decimal place. Supply current values in values.header and values.rows. Trigger names and their effects depend on vcname. For IVVc, __new initializes defaults and __copy reads the source record from JSON id; these are field-trigger operations, not the copyrecord endpoint.

Example Request:

POST /WebExcellentAPI.hal?action=windowactions&usercode=JOHN
Content-Type: application/json

{
  "vcname": "IVVc",
  "fieldname": "__new",
  "rowindex": -1,
  "headerfields": "SerNr:1",
  "rowfields": "",
  "values": {
    "header": {},
    "rows": []
  }
}

Example Response:

{"success": true, "res": true, "record": {"SerNr": "-1", "rows": []}}

Plain JSON is the default. For legacy encrypted=true, Base64-encode the JSON bytes, then reverse the Base64 text. The server reverses that text before Base64 decoding.

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 (plain JSON)

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

Per-Register Behavior

ORVc (Sales Order)

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

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:

{
  "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"
    }
  ]
}

Example Request:

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

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

Returns XML with res/@regname=ContactPersonVc. Traverses ContactRelVc rows whose CustCode equals id and reads each linked contact by ContactCode.

Each contact found is emitted as ContactPersonVc with Code, Name, Mobile, Phone, eMail and JobDesc. If no linked contacts are found, the res element remains and there are no contact rows.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getcustomercontactpersons&id=CUSTOMER01

Example Response:

<data><res regname="ContactPersonVc"></res>
  <ContactPersonVc><Code>CONTACT01</Code><Name>Example contact</Name><Mobile>EXAMPLE-MOBILE</Mobile><Phone>EXAMPLE-PHONE</Phone><eMail>contact@example.invalid</eMail><JobDesc>Manager</JobDesc></ContactPersonVc>
</data>

Returns XML for the item identified by id. A missing item returns <data></data>.

For an existing item, res/@regname is INVcStockList. Each location with a nonzero calculated balance has an INVcStockList row with Type=row, Code, Name, Stock, Unit, Balance, UnitCost and Value.

A final INVcStockList row has Type=total, Balance, UnitCost and Value. Unit cost is value divided by balance; the total uses total value divided by total quantity.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getitemstocklist&id=ITEM01

Example Response:

<data><res regname="INVcStockList"></res>
  <INVcStockList><Type>row</Type><Code>ITEM01</Code><Name>Example item</Name><Stock>MAIN</Stock><Unit>pcs</Unit><Balance>10</Balance><UnitCost>5</UnitCost><Value>50</Value></INVcStockList>
  <INVcStockList><Type>total</Type><Balance>10</Balance><UnitCost>5</UnitCost><Value>50</Value></INVcStockList>
</data>

Lists records without an action parameter. Pages are zero-based (offset = page * perpage); omitted page is 0. Supply a positive perpage to receive records: there is no server page-size default or 100-record cap, and omitted perpage produces no rows in paginated lists. Only order=ascending selects ascending order; the default is descending. The paginated envelope is <data page='...' total='...'>, where total is the number of matched records before pagination. It has no count, perpage or totalpages attributes.

ActVc, Kanban, IVVc, VIVc, IPVc, OPVc, StockTakeVc, ORVc and QTVc populate records only when usercode is nonblank; otherwise they return empty lists.

Kanban is an exception: page, perpage, sortkey and order do not control its result. It sorts by TransDate, ActType and SerNr and returns ToDo, InProgress and Done containers with ActVc rows. ToDo and InProgress are unlimited; Done returns at most the last 10 entries after sorting. Each column total counts the rows actually returned. The outer total is always 0 in this implementation and is not a board count.

Record wrappers retain register names; field elements are lowercase. Date filtering applies only to handlers that use sd/ed. EPOrderDocVc uses empcode for employee scope. Lists check the authenticated caller's register access and, when usercode is supplied, that user's portal list access.

Example Request:

GET /WebExcellentAPI.hal?register=IVVc&usercode=JOHN&page=0&perpage=50&order=descending

Example Response:

<data page='0' total='1'><IVVc><sernr>10001</sernr><custcode>CUSTOMER01</custcode><addr0>Example customer</addr0><sum4>100.00</sum4><invdate>2026-01-15</invdate></IVVc></data>

Returns a paginated list of accounts receivable entries with RVal > 0. Uses the list query pattern — no action parameter.

Fields returned per record:

• invoicenr - Invoice number
• officialsernr - Official serial number
• refstr - Reference string
• rval - Remaining open value (M4 formatted)
• arcurncycode - Currency code
• custcode - Customer code
• custname - Customer name
• duedate - Due date (YYYY-MM-DD format)

Search matches against: InvoiceNr, CustCode, CustName, RefStr, OfficialSerNr, and amount.

Example Request:

GET /WebExcellentAPI.hal?register=ARVc&page=0&perpage=50&search=ACME&sortkey=DueDate

Example Response:

<data page='0' total='12'>
  <ARVc>
    <invoicenr>10001</invoicenr>
    <custcode>ACME</custcode>
    <custname>ACME Corporation</custname>
    <rval>1250.00</rval>
    <arcurncycode>EUR</arcurncycode>
    <duedate>2026-03-31</duedate>
  </ARVc>
</data>

Pages are zero-based (offset = page * perpage); omitted page is 0. Supply a positive perpage to receive records: there is no server page-size default or 100-record cap, and omitted perpage produces no rows in paginated lists. Only order=ascending selects ascending order; the default is descending. The paginated envelope is <data page='...' total='...'>, where total is the number of matched records before pagination. It has no count, perpage or totalpages attributes. Field element names are lowercase.

Returns a paginated list of accounts payable entries with RVal > 0. Uses the list query pattern — no action parameter.

Fields returned per record:

• sernr - Record serial number
• invoicenr - Invoice number
• refstr - Reference string
• rval - Remaining open value (M4 formatted)
• curncycode - Currency code
• vecode - Vendor code
• vename - Vendor name
• duedate - Due date (YYYY-MM-DD format)

Search matches against: SerNr, VECode, VEName, RefStr, InvoiceNr, and amount.

Example Request:

GET /WebExcellentAPI.hal?register=APVc&page=0&perpage=50&search=SUPPLIER

Example Response:

<data page='0' total='8'>
  <APVc>
    <sernr>5001</sernr>
    <invoicenr>SUP-2026-001</invoicenr>
    <vecode>SUPPLIER</vecode>
    <vename>Supplier Ltd</vename>
    <rval>3200.00</rval>
    <curncycode>EUR</curncycode>
    <duedate>2026-04-15</duedate>
  </APVc>
</data>

Pages are zero-based (offset = page * perpage); omitted page is 0. Supply a positive perpage to receive records: there is no server page-size default or 100-record cap, and omitted perpage produces no rows in paginated lists. Only order=ascending selects ascending order; the default is descending. The paginated envelope is <data page='...' total='...'>, where total is the number of matched records before pagination. It has no count, perpage or totalpages attributes. Field element names are lowercase.

Runs a report from a plain JSON body. Match reportwindow to getstartupitems.reports[].window_class and repname to that entry's report_function. getreportfilters describes its filters. Indexed filter names such as flags[0] must be submitted as spec keys such as flags0. Keys ending in Date are parsed as YYYY-MM-DD.

The report must be allowed by both portal-user access and the authenticated caller's report/module access. Language comes from resolved user settings; JSON lang is not read. Successful output starts with <report><lang>...</lang> and contains the report output; validation/access errors use <data><res errstr="..." newdata=''></res></data>.

Example Request:

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

{
  "reportwindow": "QTHistoryRClass",
  "repname": "QTHstRn",
  "spec": {
    "sStartDate": "2026-01-01",
    "sEndDate": "2026-01-31"
  }
}

Example Response:

<data><res errstr="Access denied" newdata=''></res></data>

Returns the bundled ReportFilters.json metadata, with reports appended by an extension when supplied. The JSON root contains source_files, statistics and reports. Each report has title, window_class, module and filters; some also have note. Filters use label, interfacetype, datatype, field and required, with options arrays of value/label pairs where supplied. No default values are supplied by the base asset or generated by the loader. A report with note="Window class definition not found" has unresolved window metadata and an empty filters array.

This response has no repname/report_function property. Match window_class to getstartupitems.reports[].window_class to obtain report_function. The example is an excerpt; statistics describe the bundled catalog.

Example Request:

GET /WebExcellentAPI.hal?action=action&register=getreportfilters

Example Response:

{
  "source_files": [
    "product-bks/english/productwindows.hal",
    "product-bks/estonian/productwindows.hal",
    "product-bks/latvian/productwindows.hal"
  ],
  "statistics": {
    "total_reports": 989,
    "reports_with_filters": 758,
    "reports_without_filters": 231,
    "reports_with_mandatory_fields": 501
  },
  "reports": [
    {
      "title": "Access Control",
      "window_class": "UserAccessRClass",
      "module": "modSY",
      "filters": [
        {
          "label": "Person",
          "interfacetype": "EditFieldTL",
          "datatype": "string",
          "required": false,
          "field": "f1"
        },
        {
          "label": "Function",
          "interfacetype": "RadioButton",
          "datatype": "integer",
          "field": "flags[0]",
          "required": false,
          "options": [
            {
              "value": 0,
              "label": "All Access Information"
            },
            {
              "value": 1,
              "label": "User Access Per Company"
            },
            {
              "value": 2,
              "label": "User Mail Access Groups"
            },
            {
              "value": 3,
              "label": "Access Groups per Company"
            }
          ]
        }
      ]
    },
    {
      "title": "Access Group Report",
      "window_class": "AccGrpCheckRClass",
      "module": "modTC",
      "note": "Window class definition not found",
      "filters": []
    }
  ]
}