### Manual API Testing with cURL and XML

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/testSuite/README.md

Demonstrates how to manually send legal text data to the API using cURL. Includes a full example of the XML payload structure required for the 'push' action.

```bash
curl -X POST http://www.example.com/itrk-test-api.php -dxml='<?xml version="1.0" encoding="UTF-8" standalone="yes"?><api><api_version>1.0</api_version><user_auth_token>1234567890</user_auth_token><action>push</action><user_account_id>123</user_account_id><rechtstext_type>datenschutz</rechtstext_type><rechtstext_title>Datenschutzerklaerung</rechtstext_title><rechtstext_country>DE</rechtstext_country><rechtstext_language>de</rechtstext_language><rechtstext_language_iso639_2b>ger</rechtstext_language_iso639_2b><rechtstext_pdf_filenamebase_suggestion>datenschutz</rechtstext_pdf_filenamebase_suggestion><rechtstext_pdf_localized_filenamebase_suggestion>Datenschutzerklaerung.pdf</rechtstext_pdf_localized_filenamebase_suggestion><rechtstext_pdf_filename_suggestion>datenschutz</rechtstext_pdf_filename_suggestion><rechtstext_pdf>JVBERiAxMjM0</rechtstext_pdf><rechtstext_text>Beispielrechtstext</rechtstext_text><rechtstext_html>HTML Beispieltext</rechtstext_html></api>'
```

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

### Execute IT-Recht Kanzlei TestSuite via CLI

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/testSuite/README.md

Commands to run the automated test suite against a specific API endpoint. Users can specify the API URL, authentication token, user account ID for multi-shop setups, and optionally filter by specific test names.

```bash
php runTestSuite.php --help
php runTestSuite.php --api-url=http://www.example.com/itrk-test-api.php --api-token=IhrApiToken
php runTestSuite.php --api-url=http://www.example.com/itrk-test-api.php --api-token=IhrApiToken --user-account-id=1 --test-name=action_invalid
```

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

### XML Push Request Format

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

Provides an example of the XML structure sent by the IT-Recht Kanzlei server to the SDK. This format includes metadata, authentication tokens, and the legal text content in various formats.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<api>
  <api_version>1.0</api_version>
  <action>push</action>
  <user_auth_token>ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo</user_auth_token>
  <user_account_id>shop-de</user_account_id>
  <rechtstext_type>agb</rechtstext_type>
  <rechtstext_title>Allgemeine Geschäftsbedingungen</rechtstext_title>
  <rechtstext_country>DE</rechtstext_country>
  <rechtstext_language>de</rechtstext_language>
  <rechtstext_language_iso639_2b>ger</rechtstext_language_iso639_2b>
  <rechtstext_pdf_localized_filenamebase_suggestion>allgemeine-geschaeftsbedingungen</rechtstext_pdf_localized_filenamebase_suggestion>
  <rechtstext_pdf_url>https://www.it-recht-kanzlei.de/rechtstexte/example.pdf</rechtstext_pdf_url>
  <rechtstext_pdf>JVBERi0xLjQK...base64-encoded-pdf...</rechtstext_pdf>
  <rechtstext_pdf_md5hash>c9a0574850d3a3332d35991143dd08d5</rechtstext_pdf_md5hash>
  <rechtstext_text>Plain text version of the legal document...</rechtstext_text>
  <rechtstext_html>&lt;div&gt;&lt;h1&gt;AGB&lt;/h1&gt;...&lt;/div&gt;</rechtstext_html>
</api>
```

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

### XML Response for 'getversion' Action (Success)

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

An example of a successful XML response to the 'getversion' action. It includes the standard success status and can be extended with meta elements like 'meta_shopversion' and 'meta_modulversion' to provide environment information.

```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>
</response>
```

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

### Example Success XML Response

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

This XML snippet demonstrates a successful response from the API, including status, version information, 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>
```

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

### XML Example Request for Pushing Legal Texts

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

This XML snippet demonstrates a typical request to the IT-Recht Kanzlei API for pushing legal texts. It includes all necessary metadata and content for a legal document, such as AGB (General Terms and Conditions). The structure allows for specifying the action, user authentication, and detailed information about the legal text, including its plain text and HTML representations, and PDF data.

```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+Pj4vQ29udGVudHMgNSAw
    IFI+PmVuZG9iag00IDAgb2JqPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTEvTmFtZS9GMS9CYXNlRm9udC9IZWx2ZXRpY2Fc
    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>
```

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

### Test LTI Endpoint with curl

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

Use curl commands to simulate requests from IT-Recht Kanzlei to test your LTI endpoint implementation. Examples include testing the 'getversion' action for credential validation, 'getaccountlist' to retrieve sales channels, and 'push' to send legal text. The documentation also shows how to test with an invalid token to expect an error response.

```bash
# Test getversion action (validates credentials)
curl -X POST https://myshop.com/lti-endpoint.php \
  -H "Content-Type: text/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<api>
  <api_version>1.0</api_version>
  <user_auth_token>ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo</user_auth_token>
  <action>getversion</action>
</api>'

# Expected response:
# <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
# <response>
#     <status>success</status>
#     <meta_shopversion>2.5.0</meta_shopversion>
#     <meta_modulversion>1.0.3</meta_modulversion>
# </response>

# Test getaccountlist action (retrieve sales channels)
curl -X POST https://myshop.com/lti-endpoint.php \
  -H "Content-Type: text/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<api>
  <api_version>1.0</api_version>
  <user_auth_token>ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo</user_auth_token>
  <action>getaccountlist</action>
</api>'

# Test push action (send legal text)
curl -X POST https://myshop.com/lti-endpoint.php \
  -H "Content-Type: text/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<api>
  <api_version>1.0</api_version>
  <action>push</action>
  <user_auth_token>ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo</user_auth_token>
  <user_account_id>0</user_account_id>
  <rechtstext_type>agb</rechtstext_type>
  <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_text>Plain text version...</rechtstext_text>
  <rechtstext_html>&lt;h1&gt;Terms&lt;/h1&gt;</rechtstext_html>
</api>'

# Test with invalid token (expect error code 3)
curl -X POST https://myshop.com/lti-endpoint.php \
  -H "Content-Type: text/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<api>
  <api_version>1.0</api_version>
  <user_auth_token>invalid_token</user_auth_token>
  <action>getversion</action>
</api>'

# Expected error response:
# <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
# <response>

```

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

### POST /itrk-test-api.php

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/testSuite/README.md

Endpoint to receive and process legal text updates from the IT-Recht Kanzlei service.

```APIDOC
## POST /itrk-test-api.php

### Description
This endpoint accepts an XML payload containing legal text data, including the text content, PDF versions, and metadata, to update the shop's legal pages.

### Method
POST

### Endpoint
/itrk-test-api.php

### Parameters
#### Request Body
- **xml** (string) - Required - The XML payload containing the API version, auth token, action, account ID, and legal text details (type, title, country, language, PDF data, HTML content).

### Request Example
```xml
<api>
  <api_version>1.0</api_version>
  <user_auth_token>1234567890</user_auth_token>
  <action>push</action>
  <user_account_id>123</user_account_id>
  <rechtstext_type>datenschutz</rechtstext_type>
  <rechtstext_text>Beispielrechtstext</rechtstext_text>
  <rechtstext_html>HTML Beispieltext</rechtstext_html>
</api>
```

### Response
#### Success Response (200)
- **status** (string) - Indicates successful processing of the legal text update.

#### Response Example
{
  "status": "success"
}
```

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

### XML Request for 'getversion' Action

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Provides an example XML request for the 'getversion' action. This action is primarily used to validate access credentials and ensure the interface is correctly configured. It includes the API version, authentication token, and the action type.

```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>getversion</action>
</api>
```

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

### Extract and Send Test XML

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/testSuite/README.md

Uses the XtractXml utility to prepare XML payloads from test case files and pipe them directly into a cURL request.

```bash
php src/XtractXml.php push_valid IhrApiToken MultiShopId
curl -X POST http://www.example.com/itrk-test-api.php -dxml="$(php ./src/XtractXml.php push_valid IhrApiToken MultiShopId)"
```

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

### XML Response for 'getversion' Action (Error)

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

An example of an erroneous XML response to the 'getversion' action. It indicates an error status and provides details such as an error code and a descriptive error message, like an invalid authentication token.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <status>error</status>
    <meta_shopversion>1.0</meta_shopversion>
    <meta_modulversion>1.1.0</meta_modulversion>
    <error>3</error>
    <error_message>The authentication token is invalid.</error_message>
</response>
```

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

### Initialize LTI Class and Handle Requests

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

Demonstrates how to instantiate the LTI class with a custom handler and process incoming XML requests. It includes configuration for error handling and debugging, and shows how to return the processed XML response.

```php
require_once 'sdk/require_all.php';
require_once 'MyLTIHandler.php';

$ltiHandler = new MyLTIHandler();
$lti = new \ITRechtKanzlei\LegalText\Sdk\LTI($ltiHandler, '2.5.0', '1.0.3');

$lti->setIncludeErrorStackTrace(false);
$lti->setErrorCallback(function(\Throwable $e) {
    error_log('LTI Error: ' . $e->getMessage());
});

$xml = file_get_contents('php://input');
if (strpos($_SERVER['CONTENT_TYPE'] ?? '', 'x-www-form-urlencoded') !== false && isset($_POST['xml'])) {
    $xml = $_POST['xml'];
}

$response = $lti->handleRequest($xml);
header('Content-Type: application/xml; charset=utf-8');
header('Content-Length: ' . strlen($response));
echo $response;
```

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

### Implement Multi-Shop Account List

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

Shows how to override handleActionGetAccountList to define available sales channels and handleActionPush to route legal text updates to specific shop directories.

```php
public function handleActionGetAccountList(): \ITRechtKanzlei\LegalText\Sdk\LTIAccountListResult {
    $accountList = new \ITRechtKanzlei\LegalText\Sdk\LTIAccountListResult();
    $accountList->addAccount('shop-de', 'German Store', ['de_DE', 'en_GB'], ['DE', 'AT']);
    $accountList->addAccount('shop-ch', 'Swiss Store', ['de', 'fr', 'it'], ['CH']);
    $accountList->addAccount('shop-int', 'International Store', ['en'], ['GB', 'US', 'AU']);
    return $accountList;
}

public function handleActionPush(\ITRechtKanzlei\LegalText\Sdk\LTIPushData $data): \ITRechtKanzlei\LegalText\Sdk\LTIPushResult {
    $shopId = $data->getMultiShopId();
    $basePath = "/var/www/shops/{$shopId}/legal/";
    return new \ITRechtKanzlei\LegalText\Sdk\LTIPushResult("https://{$shopId}.myshop.com/legal/");
}
```

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

### Override handleActionGetVersion for System Diagnostics

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

Demonstrates how to extend the version request handler to include Apache modules and active plugin metadata. This is useful for troubleshooting environment-specific issues during API communication.

```php
public function handleActionGetVersion(): \ITRechtKanzlei\LegalText\Sdk\LTIVersionResult {
    $result = new \ITRechtKanzlei\LegalText\Sdk\LTIVersionResult();

    // Include Apache modules list for troubleshooting
    $result->includeApacheModules(true);

    // Add installed plugins that may affect the interface
    $result->addPluginInfo('woocommerce', '8.2.1');
    $result->addPluginInfo('multilingual-plugin', '2.4.0');
    $result->addPluginInfo('caching-plugin', '3.1.5');

    return $result;
}
```

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

### Action "getaccountlist"

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Retrieves a list of available sales channels, languages, and countries for a user's system.

```APIDOC
## Action "getaccountlist"

This action is used for systems that offer multiple sales channels. It retrieves a list of all available sales channels for the user, along with the languages and countries supported for each channel. This allows the user to select a specific sales channel in the client portal for legal text transfers. It is recommended to implement this action even for systems with a single sales channel.
```

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

### POST /lti-endpoint.php

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

The primary endpoint for handling LTI actions including version checks, account listing, and legal text pushes.

```APIDOC
## POST /lti-endpoint.php

### Description
This endpoint processes XML requests from the IT-Recht Kanzlei service. It supports actions like 'getversion', 'getaccountlist', and 'push' for updating legal texts.

### Method
POST

### Endpoint
/lti-endpoint.php

### Parameters
#### Request Body (XML)
- **api_version** (string) - Required - The API version (e.g., '1.0')
- **user_auth_token** (string) - Required - The security token generated via LTI::generateToken()
- **action** (string) - Required - The action to perform: 'getversion', 'getaccountlist', or 'push'
- **rechtstext_type** (string) - Optional - Required for 'push' action (e.g., 'agb', 'impressum', 'datenschutz', 'widerruf')

### Request Example
```xml
<api>
  <api_version>1.0</api_version>
  <user_auth_token>ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo</user_auth_token>
  <action>getversion</action>
</api>
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure
- **meta_shopversion** (string) - Current shop version
- **meta_modulversion** (string) - Current SDK module version

#### Response Example
```xml
<response>
    <status>success</status>
    <meta_shopversion>2.5.0</meta_shopversion>
    <meta_modulversion>1.0.3</meta_modulversion>
</response>
```
```

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

### Handle Legal Document Types with PHP

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

The SDK supports four types of legal documents, defined as constants in LTIPushData. Use these constants to handle different document types appropriately within your PHP application. The code demonstrates how to process different document types, including checking for PDF attachments and updating relevant pages.

```php
<?php
use ITRechtKanzlei\LegalText\Sdk\LTIPushData;

public function handleActionPush(LTIPushData $data): \ITRechtKanzlei\LegalText\Sdk\LTIPushResult {

    switch ($data->getType()) {
        case LTIPushData::DOCTYPE_IMPRINT:  // 'impressum' - Legal Notice
            // No PDF available for this type
            $this->updateImprintPage($data->getTextHtml());
            break;

        case LTIPushData::DOCTYPE_TERMS_AND_CONDITIONS:  // 'agb'
            $this->updateTermsPage($data->getTextHtml());
            // Should be attached to order confirmation emails
            if ($data->hasPdf()) {
                $this->storeEmailAttachment('agb', $data->getPdf());
            }
            break;

        case LTIPushData::DOCTYPE_PRIVACY_POLICY:  // 'datenschutz'
            $this->updatePrivacyPage($data->getTextHtml());
            break;

        case LTIPushData::DOCTYPE_CANCELLATION_POLICY:  // 'widerruf'
            $this->updateCancellationPage($data->getTextHtml());
            // Should be attached to order confirmation emails
            if ($data->hasPdf()) {
                $this->storeEmailAttachment('widerruf', $data->getPdf());
            }
            break;
    }

    // Documents that should be sent with order confirmations:
    // LTIPushData::DOCTYPES_TO_MAIL = ['agb', 'widerruf']
    if (in_array($data->getType(), LTIPushData::DOCTYPES_TO_MAIL)) {
        $this->updateOrderEmailAttachments($data);
    }

    return new \ITRechtKanzlei\LegalText\Sdk\LTIPushResult($this->getDocumentUrl($data->getType()));
}
?>
```

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

### Generate Authentication Tokens with PHP

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

Use the static LTI::generateToken() method in PHP to create secure random tokens for authentication. These tokens can be configured in the IT-Recht Kanzlei client portal. The method supports generating tokens of default length, custom lengths, and with custom character sets.

```php
<?php
use ITRechtKanzlei\LegalText\Sdk\LTI;

// Generate a 32-character alphanumeric token (default)
$token = LTI::generateToken();
// Example: 'ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo'

// Generate longer token
$longToken = LTI::generateToken(64);

// Generate token with custom alphabet
$numericToken = LTI::generateToken(16, '0123456789');
// Example: '4829103756284019'

// Store token in database and display to user
$db->saveInterfaceToken($token);
echo "Your API Token: " . $token;
echo "Enter this token in the IT-Recht Kanzlei client portal.";

// Validate token in handler
class MyLTIHandler extends \ITRechtKanzlei\LegalText\Sdk\LTIHandler {
    public function isTokenValid(string $token): bool {
        $storedToken = $this->db->getInterfaceToken();
        return hash_equals($storedToken, $token);
    }
}
?>
```

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

### Handle account list response for multi-shop systems

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

This snippet demonstrates the XML response format for systems supporting multiple sales channels. Each account entry contains a unique accountid and a descriptive accountname for identification in the client portal.

```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>
```

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

### Request account list from IT-Recht Kanzlei API

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

This XML snippet demonstrates the required structure for the 'getaccountlist' action. It includes the API version, user authentication token, and the specific action to be performed.

```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>
```

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

### Action "getversion"

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

This action is used to validate access data and ensure the interface is correctly configured.

```APIDOC
## Action "getversion"

This action is generally used to validate the access data and ensure the interface is set up correctly.

### Example request

```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>getversion</action>
</api>
```

### Example response (in case of 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>
</response>
```

Additional meta fields can be included in the response upon discussion with IT-Recht Kanzlei technical support.

### Example response (in case of error)

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <status>error</status>
    <meta_shopversion>1.0</meta_shopversion>
    <meta_modulversion>1.1.0</meta_modulversion>
    <error>3</error>
    <error_message>The authentication token is invalid.</error_message>
</response>
```
```

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

### Handle account list response for single-shop systems

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

This snippet shows the XML response for systems without multiple sales channels. It includes optional configuration for supported locales and countries to restrict 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>0</accountid>
    <accountname/>
    <locales>
      <locale>de</locale>
      <locale>en</locale>
    </locales>
    <countries>
      <country>DE</country>
    </countries>
  </account>
</response>
```

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

### Implement Custom LTI Handler in PHP

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

This snippet demonstrates how to extend the LTIHandler abstract class to process incoming legal text updates. It includes mandatory authentication validation and the implementation of handleActionPush to store HTML, plain text, and PDF versions of legal documents.

```php
<?php
require_once 'sdk/require_all.php';

class MyLTIHandler extends \ITRechtKanzlei\LegalText\Sdk\LTIHandler {

    private $validToken = 'ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo';

    /**
     * Validate authentication token
     */
    public function isTokenValid(string $token): bool {
        return hash_equals($this->validToken, $token);
    }

    /**
     * Optional: Initialize resources before handling request
     */
    public function preHandleRequest(): void {
        // Check database connection, validate configuration, etc.
        if (!$this->isDatabaseConnected()) {
            throw new \ITRechtKanzlei\LegalText\Sdk\LTIError(
                'Database connection failed',
                \ITRechtKanzlei\LegalText\Sdk\LTIError::CONFIGURATION_INCOMPLETE
            );
        }
    }

    /**
     * Required: Handle incoming legal text push requests
     */
    public function handleActionPush(
        \ITRechtKanzlei\LegalText\Sdk\LTIPushData $data
    ): \ITRechtKanzlei\LegalText\Sdk\LTIPushResult {

        $type = $data->getType();        // 'agb', 'datenschutz', 'widerruf', 'impressum'
        $language = $data->getLanguageIso639_1();  // 'de', 'en', etc.
        $country = $data->getCountry();   // 'DE', 'AT', etc.
        $title = $data->getTitle();       // 'Allgemeine Geschäftsbedingungen'

        // Store HTML version
        $htmlContent = $data->getTextHtml();
        file_put_contents("/var/www/legal/{$type}_{$language}.html", $htmlContent);

        // Store plain text version
        $textContent = $data->getText();
        file_put_contents("/var/www/legal/{$type}_{$language}.txt", $textContent);

        // Store PDF if available (not available for 'impressum' type)
        if ($data->hasPdf()) {
            $pdfBinary = $data->getPdf();
            $filename = $data->getLocalizedFileName(); // e.g., 'allgemeine-geschaeftsbedingungen'
            file_put_contents("/var/www/legal/{$filename}.pdf", $pdfBinary);
        }

        // Return success with URL where document is published
        return new \ITRechtKanzlei\LegalText\Sdk\LTIPushResult(
            'https://www.myshop.com/legal/' . $type
        );
    }
}
```

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

### Implement Error Handling with LTIError

Source: https://context7.com/it-recht-kanzlei/itrk-plugin-sdk/llms.txt

Shows how to throw LTIError exceptions to communicate specific failure states to the SDK. The SDK automatically maps these exceptions to standardized XML error responses based on the provided error codes.

```php
use ITRechtKanzlei\LegalText\Sdk\LTIError;
use ITRechtKanzlei\LegalText\Sdk\LTIPushData;
use ITRechtKanzlei\LegalText\Sdk\LTIPushResult;

public function handleActionPush(LTIPushData $data): LTIPushResult {

    // Check if language is supported
    $supportedLanguages = ['de', 'en'];
    if (!in_array($data->getLanguageIso639_1(), $supportedLanguages)) {
        throw new LTIError(
            'Language not supported. Supported: de, en',
            LTIError::CONFIGURATION_LANGUAGE_NOT_SUPPORTED  // Error code 82
        );
    }

    // Check if target page exists
    $targetPage = $this->findCmsPage($data->getType());
    if (!$targetPage) {
        throw new LTIError(
            'CMS page for ' . $data->getType() . ' not found. Please create page first.',
            LTIError::CONFIGURATION_DOCUMENT_NOT_FOUND  // Error code 81
        );
    }

    // Handle save errors
    try {
        $this->saveLegalText($data);
    } catch (\Exception $e) {
        throw new LTIError(
            'Failed to save legal text: ' . $e->getMessage(),
            LTIError::SAVE_DOCUMENT_ERROR  // Error code 50
        );
    }

    // Handle PDF save errors separately
    if ($data->hasPdf()) {
        try {
            $this->savePdf($data->getPdf(), $data->getLocalizedFileName());
        } catch (\Exception $e) {
            throw new LTIError(
                'Failed to save PDF: ' . $e->getMessage(),
                LTIError::SAVE_PDF_ERROR  // Error code 51
            );
        }
    }

    return new LTIPushResult('https://myshop.com/legal/' . $data->getType());
}
```

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

### POST /getaccountlist

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Retrieves a list of accounts or sales channels associated with the shop system to facilitate legal text synchronization.

```APIDOC
## POST /getaccountlist

### Description
Retrieves the available accounts or sales channels from the shop system. This is used to identify where legal texts should be assigned.

### Method
POST

### Endpoint
/ (XML-based API)

### Request Body
- **api_version** (string) - Required - The version of the API (e.g., "1.0")
- **user_auth_token** (string) - Required - Authentication token for the client portal
- **action** (string) - Required - Must be set to "getaccountlist"

### Request Example
```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>
```

### Response
#### Success Response (200)
- **status** (string) - The status of the request (e.g., "success")
- **meta_shopversion** (string) - The version of the shop system
- **meta_modulversion** (string) - The version of the plugin module
- **account** (array) - List of account objects containing accountid and accountname

#### Response Example
```xml
<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>
</response>
```
```

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

### Basic API Structure and Authentication

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Describes the fundamental XML structure for requests and responses, including authentication mechanisms.

```APIDOC
## Basic API Structure and Authentication

### Request (basic)

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

Requests sent to the system must include the API version, action parameter, and values within the root `api` node.

Possible values for the `action` parameter are:
* `version`
* `getaccountlist`
* `push`

### Response (basic)

#### In case of success

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

#### In case of error

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <status>error</status>
    <error>1</error>
    <error_message>Something failed.</error_message>
</response>
```

Responses can include optional `meta` elements for environment information.

### Authentication

#### Authentication via a token (preferred)

Your system generates a token, which the user stores in the IT-Recht Kanzlei client portal. The token is sent in the `user_auth_token` element.

Example:
```xml
<user_auth_token>ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo</user_auth_token>
```

#### Authentication with user name and password

Users can define credentials in your system, which are then stored in the IT-Recht Kanzlei client portal. Password transmission can be unencrypted or hashed upon agreement.

Example:
```xml
<user_username>Username</user_username>
<user_password>Password</user_password>
```
```

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

### POST / (Legal Text Update)

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Endpoint for receiving legal text XML documents from the IT-Recht Kanzlei system.

```APIDOC
## POST / 

### Description
Receives XML documents containing legal text updates from the IT-Recht Kanzlei system. The system must process the XML and return a response with the same content type.

### Method
POST

### Endpoint
/ (Configured in client portal)

### Parameters
#### Request Body
- **XML Document** (text/xml) - Required - The legal text data payload formatted as XML.

### Request Example
<legal_text_update>
	<id>12345</id>
	<content>...</content>
</legal_text_update>

### Response
#### Success Response (200)
- **Status** (text/xml) - Confirmation that the XML was processed successfully.

#### Response Example
<response>
	<status>success</status>
</response>
```

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

### POST /push-legal-text

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Endpoint for receiving pushed legal text updates from the IT-Recht Kanzlei service.

```APIDOC
## POST /push-legal-text

### Description
Endpoint used to receive legal text updates. The system responds with a status and an optional target URL.

### Method
POST

### Response
#### Success Response (200)
- **status** (string) - Success status indicator.
- **meta_shopversion** (string) - Version of the shop system.
- **target_url** (string) - Optional URL where the text is published.

### 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>
  <target_url>https://www.example.org/terms-and-conditions/</target_url>
</response>
```

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

### Basic XML Request Structure

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Defines the fundamental XML structure for requests sent to the IT-Recht Kanzlei system. It includes essential elements like api_version, action, and a root 'api' node for validation. This structure is common across all actions.

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

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

### XML Authentication via Token

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Demonstrates the XML structure for token-based authentication, which is the preferred method. The 'user_auth_token' element contains the alphanumeric token generated by the system and stored by the user.

```xml
<user_auth_token>ME2ssmzzWxOa2HoNgpfeLM14KvJAIKKo</user_auth_token>
```

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

### XML Authentication via Username and Password

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Shows the XML elements used for username and password authentication. The 'user_username' and 'user_password' elements transmit the user's credentials. Password transmission can be unencrypted or hashed upon agreement with IT-Recht Kanzlei.

```xml
<user_username>Username</user_username>
<user_password>Password</user_password>
```

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

### Basic XML Response Structures (Success and Error)

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Illustrates the minimal XML response formats for successful operations and errors. A success response includes a 'status' element set to 'success'. Error responses include 'status' set to 'error', along with 'error' code and 'error_message'.

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

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <status>error</status>
    <error>1</error>
    <error_message>Something failed.</error_message>
</response>
```

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

### Legal Text Data Structure

Source: https://github.com/it-recht-kanzlei/itrk-plugin-sdk/blob/main/docs/LTI_XML_Specification.md

Defines the schema for legal text objects returned by the SDK, including support for PDF, HTML, and plain text formats.

```APIDOC
## Legal Text Object Structure

### Description
Represents the data structure for a legal text transferred from the IT-Recht Kanzlei service.

### Parameters
- **user_account_id** (string) - Optional - ID for multi-channel systems.
- **rechtstext_type** (string) - Required - Type: impressum, agb, datenschutz, or widerruf.
- **rechtstext_type_ucase** (string) - Required - Uppercase variant of the type.
- **rechtstext_title** (string) - Required - Original title of the text.
- **rechtstext_country** (string) - Required - ISO 3166-1-alpha-2 country code.
- **rechtstext_language** (string) - Required - ISO 639-1 language code.
- **rechtstext_pdf_url** (url) - Optional - Download URL for PDF version.
- **rechtstext_pdf** (text) - Optional - Base64-encoded PDF content.
- **rechtstext_html** (text) - Optional - URL-encoded HTML content.

### Response Example
{
  "rechtstext_type": "agb",
  "rechtstext_title": "Allgemeine Geschäftsbedingungen",
  "rechtstext_country": "DE",
  "rechtstext_language": "de",
  "rechtstext_html": "%3Ch1%3EAGB%3C%2Fh1%3E..."
}
```