LTI XML Specification

https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md
Admin
LTI XML Specification is an API specification for IT-Recht Kanzlei's legal text integration...
Tokens:5,260
Snippets:29
Trust Score:7.4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Configure Authentication Methods

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

Examples of supported authentication mechanisms including token-based authentication and traditional username/password credentials.

```xml
<!-- Token Authentication -->
<user_auth_token>ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo</user_auth_token>

<!-- Username/Password Authentication -->
<user_username>Username</user_username>
<user_password>Password</user_password>
```

--------------------------------

### Example Success Response XML

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

This XML snippet demonstrates a successful response from the system. It includes status information, metadata about shop and module versions, and an optional target URL for accessing legal texts.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
  <status>success</status>
  <meta_shopversion>1.0</meta_shopversion>
  <meta_modulversion>1.1.0</meta_modulversion>
  <target_url>https://www.example.org/terms-and-conditions/</target_url>
</response>
```

--------------------------------

### Example XML API Request for Account List

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

This XML snippet demonstrates a typical request to the API to retrieve an account list. It includes essential elements like API version, user authentication token, and the desired action.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<api>
  <api_version>1.0</api_version>
  <user_auth_token>EXAMPLE_TOKEN</user_auth_token>
  <action>getaccountlist</action>
</api>
```

--------------------------------

### POST /getversion

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

Validates access credentials and confirms the interface is correctly configured.

```APIDOC
## POST /getversion

### Description
The `getversion` action is used to validate access data and ensure the interface is set up correctly.

### Method
POST

### Endpoint
/ (XML payload)

### Request Body
- **api_version** (string) - Required - The version of the API (e.g., "1.0")
- **action** (string) - Required - Must be "getversion"
- **user_auth_token** (string) - Optional - Authentication token
- **user_username** (string) - Optional - Username for authentication
- **user_password** (string) - Optional - Password for authentication

### Request Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<api>
  <api_version>1.0</api_version>
  <user_auth_token>EXAMPLE_TOKEN</user_auth_token>
  <action>getversion</action>
</api>

### Response
#### Success Response (200)
- **status** (string) - "success"
- **meta_shopversion** (string) - Version of the shop system
- **meta_modulversion** (string) - Version of the integration module

#### Response Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <status>success</status>
    <meta_shopversion>1.0</meta_shopversion>
    <meta_modulversion>1.1.0</meta_modulversion>
</response>
```

--------------------------------

### Execute getversion Action

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

The 'getversion' action is used to validate access data and ensure the interface is configured correctly. Returns status and environment metadata.

```xml
<!-- Request -->
<api>
  <api_version>1.0</api_version>
  <user_auth_token>EXAMPLE_TOKEN</user_auth_token>
  <action>getversion</action>
</api>

<!-- Success Response -->
<response>
    <status>success</status>
    <meta_shopversion>1.0</meta_shopversion>
    <meta_modulversion>1.1.0</meta_modulversion>
</response>
```

--------------------------------

### POST /getaccountlist

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

Retrieves a list of available sales channels, languages, and countries from the client system.

```APIDOC
## POST /getaccountlist

### Description
Retrieves a list of all sales channels available in the client system, including supported languages and countries, to allow users to map legal texts correctly.

### Method
POST

### Endpoint
/ (XML payload)

### Request Body
- **api_version** (string) - Required - The version of the API
- **action** (string) - Required - Must be "getaccountlist"
- **user_auth_token** (string) - Required - Authentication token

### Request Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<api>
  <api_version>1.0</api_version>
  <user_auth_token>EXAMPLE_TOKEN</user_auth_token>
  <action>getaccountlist</action>
</api>

### Response
#### Success Response (200)
- **status** (string) - "success"

#### Response Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <status>success</status>
</response>
```

--------------------------------

### XML API Response for Systems with Multiple Sales Channels

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

This XML response illustrates the format for systems that support multiple sales channels. It lists different accounts, each with a unique account ID and a descriptive account name, allowing for targeted legal text transfers.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
  <status>success</status>
  <meta_shopversion>1.0</meta_shopversion>
  <meta_modulversion>1.1.0</meta_modulversion>
  <account>
    <accountid>sc-id-01</accountid>
    <accountname>Apparel</accountname>
  </account>
  <account>
    <accountid>sc-id-02</accountid>
    <accountname>Electronics</accountname>
  </account>
</response>
```

--------------------------------

### Implement API Response Handling

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

Standardized success and error response formats for API actions. Includes optional meta elements for environment tracking and error reporting.

```xml
<!-- Success Response -->
<response>
    <status>success</status>
</response>

<!-- Error Response -->
<response>
    <status>error</status>
    <error>1</error>
    <error_message>Something failed.</error_message>
</response>
```

--------------------------------

### Minimal XML API Response for No Sales Channels

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

This XML response represents a minimal success case for systems without sales channels, languages, or country specifications. It informs the client portal that the system is not a multishop system and has no restrictions.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
  <status>success</status>
  <meta_shopversion>1.0</meta_shopversion>
  <meta_modulversion>1.1.0</meta_modulversion>
  <account>
    <accountid>0</accountid>
    <accountname/>
  </account>
</response>
```

--------------------------------

### Define Basic XML Request Structure

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

The root structure for all API requests, containing the version, action, and authentication parameters. It serves as the base template for all communication with the IT-Recht Kanzlei server.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<api>
  <api_version>1.0</api_version>
  <action>action</action>
  ...
</api>
```

--------------------------------

### XML API Request Structure for Legal Text Push

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

This XML structure represents a request to push legal text updates to the IT-Recht Kanzlei API. It includes authentication tokens, account identifiers, metadata about the legal text, a base64-encoded PDF, and the content in both plain text and HTML formats.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<api>
  <api_version>1.0</api_version>
  <action>push</action>
  <user_auth_token>EXAMPLE_TOKEN</user_auth_token>
  <user_account_id>sc-id-01</user_account_id>
  <rechtstext_type>agb</rechtstext_type>
  <rechtstext_type_ucase>AGB</rechtstext_type_ucase>
  <rechtstext_title>General Terms and Conditions</rechtstext_title>
  <rechtstext_country>DE</rechtstext_country>
  <rechtstext_language>en</rechtstext_language>
  <rechtstext_language_iso639_2b>eng</rechtstext_language_iso639_2b>
  <rechtstext_pdf_filenamebase_suggestion>agb</rechtstext_pdf_filenamebase_suggestion>
  <rechtstext_pdf_filename_suggestion>agb.pdf</rechtstext_pdf_filename_suggestion>
  <rechtstext_pdf_localized_filenamebase_suggestion>general-terms-and-conditions</rechtstext_pdf_localized_filenamebase_suggestion>
  <rechtstext_pdf_url>https://www.it-recht-kanzlei.de/rechtstexte/m1/181/1/1234567890abcdef1234567890abcdef.pdf</rechtstext_pdf_url>
  <rechtstext_pdf>
    JVBERi0xLjQKJeKCrOKAmsaSCjEgMCBvYmo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PmVuZG9iagoyIDAgb2JqPD
    wvVHlwZS9QYWdlcy9LaWRzWzMgMCBSXS9Db3VudCAxPj5lbmRvYmoKMyAwIG9iajw8L1R5cGUvUGFnZS9QYXJlbnQgMiAw
    IFIvTWVkaWFCb3hbMCAwIDU5NSA3OTJdL1Jlc291cmNlczw8L0ZvbnQ8PC9GMSA0IDAgUj4+Pj4vQ29udGVudHMgNSAwIF
    I+PmVuZG9iago0IDAgb2JqPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTEvTmFtZS9GMS9CYXNlRm9udC9IZWx2ZXRpY2Ev
    RW5jb2RpbmcvTWFjUm9tYW5FbmNvZGluZz4+ZW5kb2JqCjUgMCBvYmo8PC9MZW5ndGggNDQ+PgpzdHJlYW0KQlQgL0YxID
    IwIFRmIDIyMCA3MDAgVGQgKEhlbGxvIFdvcmxkISkgVGogRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNiAKMDAwMDAw
    MDAwMCA2NTUzNSBmIAowMDAwMDAwMDE1IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDEwNyAwMDAwMC
    BuIAowMDAwMDAwMjE3IDAwMDAwIG4gCjAwMDAwMDAzMTIgMDAwMDAgbiAKdHJhaWxlcgo8PC9Sb290IDEgMCBSL1NpemUg
    Nj4+CnN0YXJ0eHJlZgo0MDMKJSVFT0Y=
  </rechtstext_pdf>
  <rechtstext_pdf_md5hash>c9a0574850d3a3332d35991143dd08d5</rechtstext_pdf_md5hash>
  <rechtstext_text>----------------------------&#13;
General Terms and Conditions&#13;
----------------------------&#13;
&#13;
&#13;
Table of Contents&#13;
-----------------&#13;
1. Scope of Application&#13;
2. Conclusion of the Contract&#13;
&#13;
&#13;
1) Scope of Application&#13;</rechtstext_text>
  <rechtstext_html>&lt;div&gt;&lt;h1&gt;General Terms and Conditions&lt;/h1&gt;

&lt;h2&gt;Table of Contents&lt;/h2&gt;
&lt;ol&gt;
  &lt;li&gt;Scope of Application&lt;/li&gt;
  &lt;li&gt;Conclusion of the Contract&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;1) Scope of Application&lt;/h2&gt;&lt;/div&gt;</rechtstext_html>
</api>
```

--------------------------------

### Legal Text Elements

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

This section describes the available elements for representing and transferring legal text information.

```APIDOC
## Legal Text Elements

### Description
This section describes the available elements for representing and transferring legal text information.

### Parameters
#### Request Body / Response Body Fields

- **user_account_id** (string) - Optional - The element is only set for systems with multiple sales channels if a list of sales channels has previously been retrieved using the `getaccountlist` action and the user has made a selection.
- **rechtstext_type** (string) - Required - Type of legal text transferred. Possible values: `impressum`, `agb`, `datenschutz`, `widerruf`.
- **rechtstext_type_ucase** (string) - Required - Type of legal text transferred in the upper case variant. Possible values: `IMPRESSUM`, `AGB`, `DATENSCHUTZ`, `WIDERRUF`.
- **rechtstext_title** (string) - Optional - Title of the transferred legal text in the original language.
- **rechtstext_country** (string) - Optional - ISO 3166-1-alpha-2, Country, e.g. “DE” for Germany. Is transmitted uppercase. Corresponds to the jurisdiction of the legal text.
- **rechtstext_language** (string) - Optional - ISO 639-1, Language of the legal text, e.g. “de” for German, is transmitted lowercase.
- **rechtstext_language_iso639_2b** (string) - Optional - ISO 639-2 bibliographic code (B code), Language of the legal text, e.g. “ger” for German, lowercase.
- **rechtstext_pdf_filenamebase_suggestion** (string) - Deprecated - Suggestion for the file name of the PDF document. It is no longer recommended to use this element as a suggestion. It is only transmitted for older systems that use this value. Alternatively, use `rechtstext_pdf_localized_filenamebase_suggestion`.
- **rechtstext_pdf_filename_suggestion** (string) - Deprecated - Identical to `rechtstext_pdf_filenamebase_suggestion` with file extension.
- **rechtstext_pdf_localized_filenamebase_suggestion** (string) - Optional - Suggestion for the file name of the PDF document.
- **rechtstext_pdf_url** (url) - Optional - URL where the PDF version of the legal text can be downloaded.
- **rechtstext_pdf** (text) - Optional - PDF version of the legal text as a base64-encoded string.
- **rechtstext_pdf_md5hash** (string) - Optional - MD5 checksum of the PDF document. Can be used to validate the downloaded file.
- **rechtstext_text** (text) - Optional - Plain text variant of the legal text.
- **rechtstext_html** (text) - Optional - HTML variant of the legal text. Please note that all special characters and HTML tags are URL-encoded.

**Note**: You do not have to use all elements if your system cannot use this information. There is currently no PDF version of the legal text with the type “impressum”. Accordingly, the `rechtstext_pdf_*` elements do not exist when pushing a legal text of this type.

### Response Example (Success)
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
  <status>success</status>
  <meta_shopversion>1.0</meta_shopversion>
  <meta_modulversion>1.1.0</meta_modulversion>
  <target_url>https://www.example.org/terms-and-conditions/</target_url>
</response>
```

**Note**: The URL at which the legal text can be accessed can be specified in the `target_url` element. This field is optional.
```

--------------------------------

### XML API Response with Language and Country Restrictions

Source: https://raw.githubusercontent.com/it-recht-kanzlei/itrk-plugin-sdk/refs/heads/main/docs/LTI_XML_Specification.md

This XML snippet shows an API response for a system with language and country restrictions. It specifies allowed locales (languages) and countries for the default account (ID 0).

```xml
<account>
  <accountid>0</accountid>
  <accountname/>
  <locales>
    <locale>de</locale>
    <locale>en</locale>
  </locales>
  <countries>
    <country>DE</country>
  </countries>
</account>
```
Tokens:
Raw