README

存储库已转移到不同的所有者，包所有者保持不变，但包已重命名为 itsmind/sevdesk-php-sdk。要迁移，请将 composer.json 中的依赖项更改为 itsmind/sevdesk-php-sdk。其他所有内容，如类名、接口等，保持不变。

itsmind/sevdesk-php-sdk

这个非官方包提供了一个 SDK，用于使用 PHP 访问 sevDesk API。它是通过 OpenAPI-Generator 自动生成的，基于 sevdesk-api 项目提供的调整。

获取支持的地方

如果您遇到问题、缺少参数或收到意外的响应，请在 sevdesk-api 项目中报告问题或拉取请求。

有关 API 的支持，请直接联系 sevDesk 支持。

本项目仅针对 SDK 和应用程序相关问题。

联系方式：要联系我们的支持，请点击此处

一般信息

欢迎使用我们的 API！
sevDesk 允许您通过接口（即 sevDesk API）检索数据，并做出更改，而无需使用 web UI。sevDesk 接口是一个 REST-Full API。所有在 web UI 中使用的 sevDesk 数据和功能都可以通过 API 控制。

跨源资源共享

此 API 具有跨源资源共享（CORS）功能。
它允许浏览器进行跨域通信。
所有响应都有一个通配符同源，这使得它们完全公开，可供每个人访问，包括任何网站上的任何代码。

嵌入资源

当使用此 API 获取资源时，您可能会在请求的资源中遇到嵌套资源。
例如，发票总是包含一个联系人，您可以查看其 ID 和对象名称。
此 API 允许您将您最初请求的资源中的这些资源完全嵌入。
以我们的发票为例，这意味着您不仅可以查看联系人的 ID 和对象名称，还可以查看完整的联系人资源。

要嵌入资源，您只需在 GET 请求中添加查询参数 'embed'。
作为值，您可以提供嵌套资源的名称。
也可以通过提供多个名称（以逗号分隔）来提供多个嵌套资源。

身份验证和授权

sevDesk API 使用令牌身份验证来授权调用。为此，每个 sevDesk 管理员都有一个 API 令牌，它是一个包含 32 个字符 的 十六进制字符串。以下片段显示了您可以在何处找到 API 令牌（如果您是第一次使用我们的 API）。

令牌将在您想要发送的每个请求中都需要，并需要附加到请求 URL 作为 查询参数
或提供为 授权头 的值。
出于安全考虑，我们建议将 API 令牌放在授权头中，而不是查询字符串中。
然而，在本文档中的请求示例中，我们将保持它在查询字符串中，因为这样您更容易复制它们并亲自尝试。
以下URL是一个示例，展示了您的令牌需要作为查询参数放置的位置。
在这种情况下，我们使用了一些随机的API令牌。

https://my.sevdesk.de/api/v1/Contact?token=b7794de0085f5cd00560f160f290af38

下一个示例显示了令牌在授权头中。

"Authorization" :"b7794de0085f5cd00560f160f290af38"

API令牌有无限的生命周期，换句话说，只要sevDesk用户存在，它们就存在。
因此，用户永远不应该被删除。
如果真的有必要，建议保存api令牌，因为我们将无法在之后检索它！
还可能生成一个新的API令牌，例如，如果您想防止其他获得您当前API令牌的人使用您的sevDesk帐户。
要实现这一点，您只需单击您的令牌右侧的“生成新”符号，并用您的密码确认。

API新闻

要再次不遗漏API新闻和更新，请订阅我们的免费API通讯，获取所有相关信息，以确保您的sevDesk软件运行顺畅。要订阅，只需单击此处并确认我们可以向其发送所有与您相关的更新的电子邮件地址。

API请求

在我们的例子中，REST API请求需要通过组合以下组件来构建。

注意：请通过“User-Agent”头传递一个有意义的条目。如果“User-Agent”设置有意义，我们可以在客户查询的情况下提供更好的支持。
以下是一个“User-Agent”可能看起来如何的示例：“由abc提供的集成名称”。

这是一个使用curl检索sevDesk中现有联系人的示例请求。

如你所见，请求包含上述所有组件。
它的HTTP方法是GET，它有正确的端点（https://my.sevdesk.de/api/v1/Contact），查询参数如token以及额外的header信息！

查询参数

如您在上面示例请求中所见，除了“token”之外，URL中还有其他几个参数。
这些大多是可选的，但它们对于许多请求非常有用，因为它们可以限制、扩展、排序或过滤您将作为响应得到的数据。

以下是sevDesk API中最常用的查询参数。这是一个使用嵌入参数的示例。
以下第一个请求将返回所有公司联系人条目，最多100条，没有任何附加信息，也没有偏移量。

现在看看响应中位于分类属性的位置。
自然地，它只包含对象的id和对象名称，但没有更多信息。
我们现在将使用值为“category”的参数embed。

如你所见，分类对象现在扩展了，并显示了所有属性及其对应的值。

还有很多其他查询参数可以用来过滤返回的数据，以便对象匹配某种模式，但这些将不会在此提及，而是可以在最常用的API端点的详细文档中找到，如联系人、发票或收据。

分页
示例

https://my.sevdesk.de/api/v1/Invoice?offset=20&limit=10

请求头

HTTP请求（响应）头允许客户端以及服务器在请求中传递额外的信息。
它们传输重要的参数和论点，这些参数和论点对于通过HTTP传输数据非常重要。
当使用sevDesk API时，以下三个头部非常有用/必要：“Authorization”、“Accept”和“Content-type”。
以下是对为何以及如何使用它们的简要说明。

授权

如果您想在头部而不是URL中提供API令牌，则可以使用此功能。

授权：yourApiToken

Accept

指定响应的格式。
对于有响应体的操作是必需的。

Accept:application/format

在我们的情况下，format可以用json或xml替换。

Content-type

指定请求中使用的格式。
对于有请求体的操作是必需的。

Content-type:application/format

在我们的情况下，format可以用json或x-www-form-urlencoded替换。

API响应

HTTP状态码
调用sevDesk API时，您很可能在响应中获得HTTP状态码。
某些API调用还会返回包含有关资源信息的JSON响应体。
返回的每个状态码要么是成功码，要么是错误码。

成功码
错误码

资源版本化

我们使用资源版本化来处理端点的大幅度更改，这些更改很少使用，并且在我们删除旧版本之前会进行通知。
要调用不同的版本，我们使用特定的头部X-Version，应该填写所需的版本。

如果您未指定任何版本，我们假设为default。
如果您指定了一个不存在或已删除的版本，您将收到一个错误，其中包含有关哪些版本可用的信息。

您的第一个请求

阅读我们的API简介后，您现在应该能够进行第一个调用。
为了测试我们的API，我们始终建议为sevDesk创建一个试用账户，以防止对您的主账户造成意外更改。
试用账户将处于最高费率（物料管理），因此可以测试sevDesk的所有功能！

为了开始测试，我们建议以下工具之一

Postman
cURL

此示例将演示您的第一个请求，即在sevDesk中创建新的联系人。

下载适用于您所需系统的Postman并启动应用程序
将https://my.sevdesk.de/api/v1/Contact作为URL输入
使用连接符?将token=附加到URL末尾，或创建一个授权头。将您的API令牌作为值插入
对于此测试，选择HTTP方法为POST
转到Headers并输入键值对Content-type + application/x-www-form-urlencoded
作为替代方案，您可以直接转到Body并选择x-www-form-urlencoded
现在转到Body（如果您还没有在那里），并输入以下图片中显示的键值对
单击Send。您的响应现在应该看起来像这样

如您所见，成功响应在此情况下返回一个包含您刚刚创建的联系人信息的JSON格式响应体。
为了简单起见，这只是一个创建联系人的最小示例。
但是，您可以为联系人提供许多参数组合，这些参数组合可以添加信息。

安装与使用

要求

PHP 7.4及以后版本。也应与PHP 8.0兼容。

Composer

要通过Composer安装绑定，请将以下内容添加到composer.json

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/j-mastr/sevdesk-php-sdk.git"
    }
  ],
  "require": {
    "j-mastr/sevdesk-php-sdk": "*@dev"
  }
}

然后运行composer install

手动安装

下载文件并包含autoload.php

<?php
require_once('/path/to/itsmind/sevdesk-php-sdk/vendor/autoload.php');

入门指南

请按照安装程序进行操作，然后运行以下

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure API key authorization: api_key
$config = Itsmind\Sevdesk\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Itsmind\Sevdesk\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');


$apiInstance = new Itsmind\Sevdesk\Api\AccountingContactApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$model_accounting_contact = new \Itsmind\Sevdesk\Model\ModelAccountingContact(); // \Itsmind\Sevdesk\Model\ModelAccountingContact | Creation data

try {
    $result = $apiInstance->createAccountingContact($model_accounting_contact);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AccountingContactApi->createAccountingContact: ', $e->getMessage(), PHP_EOL;
}

API端点

所有URI都是相对于https://my.sevdesk.de/api/v1

模型

授权

API中定义的认证方案

api_key

类型: API密钥
API密钥参数名称: 认证
位置: HTTP头

测试

要运行测试，使用

composer install
vendor/bin/phpunit

作者

关于此包

此PHP包由OpenAPI Generator项目自动生成

API版本: 2.0.0
- 生成器版本: 7.5.0
构建包: org.openapitools.codegen.languages.PhpClientCodegen

itsmind / sevdesk-php-client

维护者

详细信息