API Profiles

1What is this page? #

• The desktop's API Profile screen. Find (F2) , Add (F3) , Modify (F4) , Save (F5) , Esc as on every master.
• The definition and the header grid are one record: grid changes (add, edit, remove, reorder) wait for Save and are written together.
• Duplicate copies the profile with its headers. Preview request shows the exact call for a voucher without sending it.

2Step by step #

1. Set up the provider first (Settings -> API Providers) with its address and keys.
2. Press Add (F3) , name the profile and pick the provider - an empty address becomes @ and the provider's body is copied in.
3. Choose the method , the timeout and the sign-in method the provider's documentation asks for.
4. Complete the address , pick what the profile is used for , and write the body , inserting placeholders where values belong.
5. Add the headers the provider needs (Accept, a tenant id, …).
6. Optionally add a condition , then Save (F5) and try Preview request on a recent voucher.

3Sign-in methods #

• None - only the headers below; a header such as API-TOKEN: @ still works.
• Bearer - adds Authorization: Bearer + the provider's API key.
• Basic - adds Authorization: Basic with the provider's end-user name and password.
• API-key header - adds the provider's API key in the header you name (for example X-API-Key).
• The keys are read from the provider and decrypted only when the call is made; they never reach this page. Preview shows them as dots.

4Placeholders #

• @ , @ , @ , @ , @ , @ , @ , @ , @ , @ , @ - the provider's values.
• {MASTERSECTION.Col} , {ITEMSECTION.Col} , {ACCOUNTSECTION.Col} , {SUNDRYSECTION.Col} , {CUSTOMFIELDSECTION.Col} - voucher values; item, account, sundry and custom-field lines repeat inside their //[INV_..._BEGIN] ... _END] block.
• @ - a module record's field; @ / @ - a report row's values; $Name - standard variables.
• Insert places the placeholder at the cursor of the address, body, condition or header value.

5Fields #

• Profile name - required, up to 100 characters, unique. API provider - required.
• Method - GET, POST, PUT, PATCH or DELETE. Timeout - 5 to 300 seconds.
• Address - required; http:// or https://, or starting with @
• Used for - Voucher, Other or Custom Reports with the voucher type, module or report (required).
• Body - optional JSON; section markers must pair up. Condition - optional filter.
• Headers - name (letters, digits and - _ . etc.) and value, both required; names unique in the profile. (UserSession.IsErpLicensed) {
• Applicable branches (ERP edition) - none ticked means every branch. }

6Integrity rules #

• The name is unique .
• Only one active default per voucher type, module or report may cover a branch.
• A header name appears once ; Authorization is refused when a sign-in method adds it; Content-Length and Host are always set by the sender.
• A voucher condition is compiled on save without running; a condition containing ; , comments or statements (INSERT, UPDATE, DELETE, EXEC, …) is refused.
• The profile and its headers are saved in one transaction - either all of it is stored or none of it.
• Deleting a profile removes its headers; its call log is kept.
• Finding, adding, changing and deleting need Find / Create / Alter / Delete on Api Profile Settings in User Manager (Masters tab), checked by the server and again by the database.
• Every problem is listed at once, numbered.

7If something does not work #