External Forms — Developer Integration Guide

---

External Forms allow external web applications to be embedded directly into KORONA Studio as part of the system’s navigation. This enables partners and solution providers to build custom UI modules that interact with the customer’s KORONA account data using the KORONA APIv3.

When the user opens the External Form inside KORONA Studio, the configured URL is loaded inside an iframe. KORONA automatically appends authentication and context parameters so the embedded application can authenticate and communicate with the KORONA API securely.

---

1. Configuration in KORONA Studio

Path: Settings → External Forms

Each External Form has the following configuration fields:

Field	Description
Number	Internal identifier of the form.
Name	Display name shown in the navigation and browser tab.
Display URL	Base URL of the external application (KORONA will append parameters).
Navigation Category	Where the menu item appears (e.g., Inventory, Reports, Sales).
User Roles	Which user roles may access the form (Master users always see it).

Once saved, KORONA automatically creates a dedicated APIv3 user for this form if one does not already exist.
This API user is used solely by the external form to authenticate API requests.

---

2. How the Form is Displayed

When the user clicks the menu entry, KORONA:

1. Opens a new tab in Studio.
2. Loads the configured Display URL inside an iframe.
3. Appends authentication & context as base64-encoded query parameters.
   

Example request:

https://your-app.example.com/your-ui-page?
  accountId=ZjM1ZTdlM2YtMDg0ZC00NDBkLTlkZmMtMWFkNzU3NTM3MzE1&
  apiUserLogin=ZXh0ZXJuYWxfZm9ybQ%3D%3D&
  apiUserPassword=dbno6jb9da38en47kz3vftd4p&
  url=aHR0cHM6Ly90cnVuay50ZXN0LmNvbWJhc2UuZGUvd2ViLw%3D%3D&
  locale=en

---

3. Passed Query Parameters

Parameter	Encoded	Meaning	Notes
accountId	Base64	UUID of the KORONA Account	Use in API requests.
apiUserLogin	Base64	Login of the dedicated API user	Use for HTTP Basic auth.
apiUserPassword	Base64	Password of the dedicated API user	Use for HTTP Basic auth.
url	Base64	Base URL of the current KORONA Studio instance	Useful for redirects and links.
locale	Plaintext	User’s language selection (de, en, es, etc.)	Use for UI localization.

All values except locale must be base64-decoded before use.

---

4. Authentication Against the API

The KORONA APIv3 uses HTTP Basic Authentication:

Authorization: Basic base64(apiUserLogin:apiUserPassword)

Example (pseudo-code):

const login = atob(apiUserLogin);        // base64 decode
const password = atob(apiUserPassword);

const authHeader = "Basic " + btoa(`${login}:${password}`);

---

5. Calling the API

Example: Fetch cashiers of the account

GET {studioBaseUrl}/api/v3/accounts/{accountId}/cashiers
Accept: application/json
Authorization: Basic <base64(login:password)>

Example response will contain JSON data representing cashiers in the account.

---

6. UI / IFrame Considerations

Your external app:

• Must support being embedded in an iframe.
• Should automatically adapt to fullscreen content.
• Should respect the locale parameter for UI language.
• Should handle session refresh/reload gracefully.

---

7. Security Notes

• Each External Form uses a dedicated API user, isolated per form.
  This avoids exposing admin credentials.
• If the External Form entry is removed, the navigation updates immediately and the API user is removed.
• Your app should never store the API credentials permanently.
  They are passed on every access and can change.

---

8. Example: Minimal JavaScript Client

const params = new URLSearchParams(window.location.search);

const accountId = atob(params.get("accountId"));
const login = atob(params.get("apiUserLogin"));
const password = atob(params.get("apiUserPassword"));
const studioUrl = atob(params.get("url"));
const locale = params.get("locale");

async function fetchAccountData() {
  const res = await fetch(`${studioUrl}api/v3/accounts/${accountId}`, {
    headers: {
      "Accept": "application/json",
      "Authorization": "Basic " + btoa(`${login}:${password}`)
    }
  });
  return res.json();
}

fetchAccountData().then(console.log);

---

9. Best Practices

Topic	Recommendation
Authentication	Always generate Authorization header dynamically.
UI Language	Use locale to load translations.
Error Handling	Display meaningful API errors to the user.
Logging	Log to your server, not to browser console.

---

10. Support

If you need help building or testing your external form integration, contact us.

---