README

数据以 POST 的形式通过 XML 格式推送到您的界面。文档以 UTF-8 编码。默认的 POST 参数是 "xml"（$_POST['xml']），其他协议也是可能的。

PHP SDK 的实现和使用

我们为 IT-Recht Kanzlei 界面的用户提供 PHP SDK。SDK 设计易于使用。首先，必须重写 LTIHandler 类的两个抽象方法之一。

创建自己的 LTI 处理器

认证方法

为确保法律文本的传输来自 IT-Recht Kanzlei 系统，您可以实施以下两种方法之一。

isTokenValid(string $token): bool

如果系统应使用令牌，则必须在此处检查传输的令牌的有效性。令牌由您手动生成或由您的系统自动生成，并在用户通过配置界面设置 IT-Recht Kanzlei 客户端门户时存储。这是首选的认证方法。要生成随机令牌，请参阅 LTI::generateToken()。

validateUserPass(string $username, string $password): bool

必须在此处检查传输的用户名和密码的正确性。用户名和密码可以由用户自己分配到您的插件中或由您的插件创建。然后，必须在设置界面时将用户名和密码存储在客户端门户中。

handleActionGetAccountList(): LTIAccountListResult

此函数应返回系统中的所有销售渠道列表。每个销售渠道必须指定一个 ID（accountid）和名称（accountname）。此外，还可以为每个销售渠道传输可用的目标语言和国家/地区列表。

即使您的系统不是多店系统，也建议实现此功能以宣布系统支持的目标语言和国家/地区。对于此用例，只需指定一个销售渠道，其中 ID 指定为 0。账户名称可以保持为空。

重要提示：请确保将这些 5 个特殊 XML 字符替换为相应的实体，存储在销售渠道（accountname）名称中

& => &amp;
< => &lt;
> => &gt;
" => &quot;
' => &apos;

handleActionPush(LTIPushData $data): LTIPushResult

一旦插件收到请求，就必须将文档集成到相应的目标页面中。文档在此进行处理。LTIPushData 对象具有获取文档所有属性的getter方法，可以查询并随后处理。

使用 LTI 类和您已实现的 LTI 处理器

LTI 类（LTI.php）负责处理传入的 XML 数据，评估要执行的操作并执行大多数错误处理。应确保 SDK 完全功能，不应更改此文件。

LTI 类的构造函数需要三个参数。

您重写的 LTIHandler 类的实例
您实现针对的系统版本
SDK 在其中使用的您的实现版本

最后一步是调用 LTI 类对象的 handleRequest() 方法。为此，可以直接使用 $_POST['xml'] 作为参数。

SDK 内部错误处理以及为 IT-Recht Kanzlei 服务器准备响应都由 SDK 自动处理。开发者可以忽略这些方面。

SDK 的一个示例实现包含在提供的 example.php 文件中。

通用

版本控制

客户端门户对版本号处理的要求

meta_modulversion：在首次创建实现以及每次后续更新时，为您的实现分配递增的版本号。
meta_shopversion：如果可能，请也传输一个可以通过比较运算符进行比较的系统版本号（例如“2.0”而不是“XY2” - 否则请请求）。请告知我们您的版本控制方案的结构（例如“major.minor”），以便我们可以正确地内部处理。

多商店系统

如果您的系统是所谓的多商店系统，即在一个管理界面下存在多个销售渠道/服务，那么在您的实现中向用户提供一个列表是必要的，这些销售渠道/服务需要在 IT-Recht Kanzlei 的客户端门户中传输法律文本。

销售渠道列表通过函数 handleActionGetAccountList() 获取。

随后的“推送”操作中，在多商店系统中，用户选择的 accountid 将通过 XML 元素 user_account_id 传输。

最佳实践

在模块首次创建以及每次后续更新时，为您的模块分配合适的递增数字版本号（例如“1.0”、“1.1”、“1.2”……）。除了经典版本号外，还可以使用数字形式的发布日期（例如“20230827”，格式为 YYYYMMDD）。始终在模块的文档/安装说明以及在主要程序文件中至少声明当前版本号。
在模块下载或下载页面上包含易于理解的安装说明。在描述中包含特殊情况（例如针对旧版商店版本）。
在您的实现（更新）的新版本中包含用户说明，说明如何更新到最新版本（这通常与经典安装说明不同），除非更新是自动进行的（例如通过在商店的模块存储中单击“更新”进行）。
在您的实现（更新）的新版本中包含 changelog.txt 或类似的文件，以告知用户新功能和错误修复。

测试

为了测试您的接口实现，请阅读 testSuite 目录下的 README.md。

您可以使用的一个额外测试工具是 LTI 测试工具。在那里，您可以输入测试系统的 API URL 和认证数据，并使用 IT-Recht Kanzlei 的法律文本接口执行请求。

SDK 内部实现的详细信息

如果您无法或不想使用 SDK，下面提供的一些细节可能对您的实现有所帮助。

XML 元素，[数据类型] 和（可能的值）

api_version [字符串]

接口版本号（例如“1.0”）
user_auth_token [字符串]

由您的系统生成，也可以在那里找到。用于认证。
action [字符串] （push | getaccountlist | version）

“version”仅返回商店版本、模块版本和系统上安装的 PHP 版本。

“getaccountlist”列出所有销售渠道及其支持的语言。

“push”是传输法律文本的命令。
user_account_id [字符串]

仅在通过使用 getaccountlist 动作检索销售渠道列表并客户端已做出选择的情况下，才为多店系统设置。

rechtstext_type [字符串] (impressum | agb | datenschutz | widerruf )

传输的法定文本类型
- impressum = 版权信息
- agb = 一般条款和条件
- datenschutz = 隐私政策
- widerruf = 取消政策
rechtstext_title [字符串]

原始语言中翻译的法定文本标题
rechtstext_text [文本]

法定文本的文本变体
rechtstext_pdf [文本]

法定文本的PDF版本
rechtstext_html [文本]

法定文本的HTML版本
rechtstext_country [字符串]

ISO 3166-1-alpha-2，国家，例如“DE”代表德国，以大写形式传输
rechtstext_language [字符串]

ISO 639-1，法定文本的语言，例如“de”代表德语，以小写形式传输
rechtstext_language_iso639_2b [字符串]

ISO 639-2文献代码（B代码），法定文本的语言，例如“ger”代表德语，以小写形式传输

状态代码

成功：一切顺利。您确认，
- 查询版本时没有发生错误
- 查询账户列表时没有发生错误
- 当推送法定文本时，它已在用户的账户/商店中成功发布
错误：无论错误代码如何，错误响应的状态始终为“错误”。

错误代码

错误代码在 LTIError.php 文件中有记录。如果可能，请只使用文件中定义的错误代码。尽可能避免使用错误代码 99。您可以定义自己的错误代码，范围大于等于 100。请通知 IT-Recht Kanzlei 错误代码及其含义。其他通用错误的错误代码也可以通过协议添加到小于 100 的范围。

示例XML响应输出

如果成功，则输出“version”

<?xml version="1.0" ?>
<response>
    <status>success</status>
    <meta_shopversion>1.0</meta_shopversion>
    <meta_modulversion>1.1.0</meta_modulversion>
    <meta_phpversion>7.4</meta_phpversion>
</response>

如果成功，则输出“getaccountlist”

<?xml version="1.0" ?>
<response>
    <status>success</status>
    <meta_shopversion>1.0</meta_shopversion>
    <meta_modulversion>1.1.0</meta_modulversion>
    <meta_phpversion>7.4</meta_phpversion>
    <account>
        <accountid>12345</accountid>
        <accountname>Shop 1</accountname>
        <locales>
            <locale>de</locale>
            <locale>en</locale>
            <locale>fr</locale>
        </locales>
        <countries>
          <country>DE</country>
          <country>AT</country>
          <country>GB</country>
          <country>FR</country>
        </countries>
    </account>
    <account>
        <accountid>23456</accountid>
        <accountname>Shop 2</accountname>
        <locales>
            <locale>de</locale>
        </locales>
        <countries>
          <country>DE</country>
        </countries>
    </account>
</response>

如果成功，则输出“push”

<?xml version="1.0" ?>
<response>
    <status>success</status>
    <meta_shopversion>1.0</meta_shopversion>
    <meta_modulversion>1.1.0</meta_modulversion>
    <meta_phpversion>7.4</meta_phpversion>
    <target_url>https://example.org/imprint</target_url>
</response>

发生错误时

<?xml version="1.0" ?>
<response>
    <status>error</status>
    <meta_shopversion>1.0</meta_shopversion>
    <meta_modulversion>1.1.0</meta_modulversion>
    <meta_phpversion>7.4</meta_phpversion>
    <error>12</error>
    <error_message>Something was not found!</error_message>
</response>

联系

Max-Lion Keller，LL.M.
IT-Recht Kanzlei，Alter Messeplatz 2，80339 慕尼黑
电话：+49 89 1301433-0
传真：+49 89 1301433-60
电子邮件：m.keller@it-recht-kanzlei.de

it-recht-kanzlei / itrk-plugin-sdk

维护者

详细信息