itsmind / sevdesk-php-sdk

官方sevDesk API的非官方SDK。始终保持最新状态，由j-mastr/sevdesk-api和OpenAPI Generator提供支持。

维护者

详细信息

github.com/j-mastr/sevdesk-php-sdk

主页

源代码

问题

安装: 280

依赖项: 0

建议者: 0

安全性: 0

星级: 4

关注者: 1

分支: 3

开放问题: 0

v1.3.0 2024-07-26 13:16 UTC

Requires

Requires (Dev)

Replaces

MIT b77f8da387d2cde92fa3b665039fded2d248eabe

phprestapisdkAccountingSEVDESK

This package is auto-updated.

Last update: 2024-09-16 12:26:44 UTC

README

此非官方包提供了一个使用PHP访问 sevDesk API 的SDK。它使用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
下一个示例显示了令牌在授权头中的位置。
  • “授权”：“b7794de0085f5cd00560f160f290af38”
API令牌具有无限的生命周期，换句话说，只要sevdesk用户存在，它们就存在。
因此，用户绝对不要被删除。
如果真的有必要，建议保存API令牌，因为我们无法在之后检索它！
也可以生成新的API令牌，例如，如果您想防止其他人使用您当前的API令牌访问您的sevdesk账户。
要实现这一点，只需点击令牌右侧的“生成新令牌”符号，并使用您的密码进行确认。

API新闻

为了不再错过API新闻和更新，请订阅我们的免费API新闻通讯，获取所有相关信息，确保您的sevdesk软件顺畅运行。要订阅，只需点击此处并确认我们发送所有相关更新的电子邮箱地址。

API请求

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


注意：请通过“User-Agent”头传递一个有意义的条目。如果“User-Agent”设置得当，我们可以在客户查询时提供更好的支持。
以下是一个这样的“User-Agent”示例：“Integration-name by abc”。

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

Get Request



如您所见，请求包含上述所有组件。
它的HTTP方法是GET，它有一个正确的端点（https://my.sevdesk.de/api/v1/Contact），查询参数如令牌和额外的头信息！

查询参数

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

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



现在看看响应中的分类属性。
自然地，它只包含对象的ID和对象名称，没有其他信息。
现在我们将使用具有“category”值的参数。



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

还有许多其他查询参数可以用于过滤匹配特定模式的对象返回的数据，但这里将不提及其内容，而是在最常用的API端点（如联系人、发票或收据）的详细文档中查找。

分页
示例
  • https://my.sevdesk.de/api/v1/Invoice?offset=20&limit=10
请求头

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

授权

如果您想在头部而不是URL中提供API令牌，则可以使用。
  • 授权：yourApiToken
接受

指定响应的格式。
对于有响应体的操作是必需的。
  • 接受：application/format
在我们的例子中，format可以用json或xml代替。

内容类型

指定请求中使用的格式。
对于带有请求体的操作是必需的。
  • Content-type:application/format
在我们的案例中，format可以替换为json或x-www-form-urlencoded

API 响应

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

成功代码
错误代码

资源版本化

我们使用资源版本化来处理端点的破坏性更改，这些更改很少使用，我们将在移除旧版本之前进行沟通。
要调用不同的版本，我们使用一个特定的头X-Version，应该填充所需的版本。
  • 如果您未指定任何版本，我们假定default
  • 如果您指定了一个不存在或已删除的版本，您将收到一个错误，其中包含有关哪些版本可用的信息。

您的第一个请求

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

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

此示例将说明您的第一个请求，即在 sevdesk 中创建一个新的联系。
  1. 下载适用于您所需系统的 Postman 并启动应用程序
  2. 将 https://my.sevdesk.de/api/v1/Contact 作为 URL
  3. 使用连接符 ? 在 URL 末尾附加 token=，或创建一个授权头。将您的 API 令牌作为值插入
  4. 对于此测试，选择 POST 作为 HTTP 方法
  5. 转到 Headers 并输入键值对 Content-type + application/x-www-form-urlencoded
    作为替代，您也可以直接转到 Body 并选择 x-www-form-urlencoded
  6. 现在转到 Body（如果您还没有在那里），并输入以下图片中显示的键值对



  7. 点击 Send。您的响应现在应该看起来像这样

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

sevdesk-Update 2.0

从 2024 年开始，我们在 sevdesk 中引入了新纪元的账务管理。您可以通过点击 sevdesk WebApp 右上角的个人资料或使用工具/账务系统版本端点来检查您是否已经收到更新。
旧版本将适用于一些客户，直到 2024 年底。在这个简短的列表中，我们概述了已更改的端点，并附有跳转到描述的链接。如果您已经收到api 通讯，您已经知道发生了什么变化。否则，您可以在此处检查 API 变更。

检查您的账务系统版本

使用此端点，您可以检查您/您的客户端使用的是哪个版本。基于此，您必须使用端点的新旧版本。 工具/账务系统版本端点

税务规则

(影响税种和税套属性)
在sevdesk-Update 2.0中，我们更改了可用的税务规则。由于使用率较低，我们将不再支持以下税种： taxType = noteu 由于存在不合规会计的高可能性，我们将不再支持以下税种： taxType = custom (包括 'taxSet': ... ) 如果您只使用 taxType = default、taxType = eu 和/或 taxType = ss，这些税种将在过渡期间自动映射到新税务规则，但您必须确保在位置中使用的税率在允许的范围内（您可以使用收据指南端点进行此操作），否则API将返回验证错误（HTTP状态码422）。对于在sevdesk-Update 2.0中创建的订单、发票、凭证和贷项通知，所有返回这些对象的端点的响应将发生变化。
因此，在sevdesk系统版本1.0中创建的订单、发票、凭证和贷项通知仍然在响应中包含税种。当它们在sevdesk-Update 2.0中创建时，将包含税则。
您可以先继续使用税种，但我们建议切换到税则，因为现在有新的选项可供选择，这些选项之前不受支持。
对于在sevdesk-Update 2.0中创建的订单、发票、凭证和贷项通知，所有返回这些对象的端点的响应将发生变化。本文档包含端点的最新版本。
以下是当前可用的税务规则的列表，按使用情况排序，结构化为收入/支出和'Regelbesteuerer'/'Kleinunternehmer'。

sevdesk-Update 2.0中'规则征税'的增值税规则（收入）

sevdesk-Update 2.0中'规则征税'的增值税规则（支出）

sevdesk-Update 2.0中小型业主（'Kleinunternehmer'）的增值税规则（收入）

sevdesk-Update 2.0中小型业主（'Kleinunternehmer'）的增值税规则（支出）

记账科目

(影响属性会计类型)
在sevdesk-Update 2.0中，我们更改了可用的记账科目及其组合。如果您使用会计类型与SKR编号，这些编号在我们的收据指南中仍然可用，您不需要在请求中更改任何内容。这些记账科目将自动映射到新的表示形式（Account Datev）。但是，您必须确保在位置中使用的税率以及在凭证中使用的税则都在允许的范围内（检查收据指南），否则API将返回验证错误（HTTP状态码422）。对于在sevdesk-Update 2.0中创建的订单、发票、凭证和贷项通知，所有返回这些对象的端点的响应将发生变化。

收据指南

为了帮助您决定哪些账户可以与哪些税务规则、税率和文件一起使用，我们为您创建了几个指南端点。您可以在以下凭证变更部分的描述中找到描述，或通过使用此链接直接跳转到端点描述：收据指南。
收据指南旨在为您提供指导，告诉您可以根据哪些账户进行选择（取决于您的筛选条件和客户设置（例如“小型企业”）以及哪些税率以及税则与它们兼容。

凭证

保存新的凭证（Voucher/Factory/saveVoucher）

以下用例不再工作或已更改

  1. 自定义增值税规定（taxType = custom和提供的taxSet）
  2. 只有特定的税率和记账账户可用。请检查收据指南
  3. 自定义会计类型不再工作
  4. 使用不创建资产的资产记账账户不再可能
  5. 凭证不能再直接设置为已付款，因此创建新凭证时只能使用状态DRAFT (50)或UNPAID / DUE (100)。使用/api/v1/Voucher/{voucherId}/bookAmount端点将凭证设置为已付款
  6. 设置或更改规定的属性。使用我们新的端点/api/v1/Voucher/{voucherId}/enshrine来规定凭证

获取或更新现有凭证（《Voucher/{voucherId}》）

以下用例不再工作或已更改

  1. 自定义增值税规定（taxType = custom和提供的taxSet）
  2. 查看收据指南以检查哪些税率与哪些税则结合使用

预订凭证（《Voucher/{voucherId}》）

以下用例不再工作或已更改

  1. 带有负凭证位置的凭证不能再使用“现金折扣”作为付款差额
  2. 凭证只有在事先注册后才能预订（见上文）
  3. 基于凭证位置的组合，某些付款差额原因不再可能
  4. 货币波动（CF）类型不再作为付款差额原因支持

银行

以下用例不再工作或已更改

  1. 设置或更改规定的属性现在只能通过使用适当的规定端点来访问

开票

增值税规则的变化也适用于此处。检查上述凭证的文档，因为变化是相同的。

在PUT和POST端点进行更严格的验证

我们添加了更严格的验证以确保只创建正确的发票，然后在sevdesk中进一步处理。以下用例不再工作或已更改

  1. 创建具有taxType noteu的发票不再工作
  2. 创建具有taxType custom的发票不再工作
  3. 在没有联系人的情况下，处理状态超过DRAFT (100)的发票不再工作
  4. 高级发票（invoiceType: 'AR'）和部分发票（invoiceType: 'TR'）只能使用税则“Umsatzsteuerpflichtige Umsätze (taxRule: 1)”（对于Regelbesteuerer）或“Steuer nicht erhoben nach §19 UStG (taxRule: 11)”（对于Kleinunternehmer）创建
  5. 创建具有属性reminderCharge值大于0的催款函（invoiceType: 'MA'）不再工作
  6. 创建与客户defaultCurrency不同的货币的高级发票（invoiceType: 'AR'）、部分发票（invoiceType: 'TR'）或最终发票（invoiceType: 'ER'）不再可能
  7. 手动更改状态不再工作（见下文“删除端点/Invoice/{invoiceId}/changeStatus”）
  8. 现在必须使用规定端点（见下文）来进行规定

保存发票（Invoice/Factory/saveInvoice）

以下用例不再工作或已更改

  1. 发票只能以状态DRAFT (100)创建，不能手动更改。使用相应的端点（例如sendViaEmail）来自动相应地更改状态
  2. 现在仅通过使用enshrine端点来设置或更改属性enshrined

使用订单创建发票（Invoice/Factory/createInvoiceFromOrder）

以下用例不再工作或已更改

  1. 如果存在预先发票（partialType: 'AR'）或部分发票（partialType: 'TR'），则无法创建最终发票（partialType: 'ER'）。此功能将在以后的更新中添加

已删除端点/Invoice/{invoiceId}/changeStatus

此端点将被完全删除（包括sevdesk系统版本1.0！）！使用这些端点将自动相应地更改状态

新端点Invoice/{invoiceId}/resetToDraft

此新端点可用于将发票状态重置为DRAFT (100)。

新端点Invoice/{invoiceId}/resetToOpen

此新端点可用于将发票状态重置为OPEN (200)。

新端点Invoice/{invoiceId}/enshrine

enshrine端点现在用于设置属性enshrined。 由于法律原因，此操作不能撤销！

贷项通知

增值税规则的变化也适用于此处。检查上述凭证的文档，因为变化是相同的。

在PUT和POST端点进行更严格的验证

我们添加了更严格的验证以确保仅创建正确的贷项通知，然后可以在sevdesk中进一步处理。由于从taxTypes/taxSets迁移到taxRules，您需要检查taxRules与税率组合的兼容性。以下用例不再工作或已更改

  1. 对于具有交货日期（deliveryDateUntil）的发票创建没有交货日期（deliveryDateUntil）的贷项通知不再可能
  2. 对于没有交货日期（deliveryDateUntil）的发票创建具有交货日期（deliveryDateUntil）的贷项通知不再可能
  3. 创建一个在发票交货日期（deliveryDateUntil）之前的贷项通知（deliveryDateUntil）不再可能
  4. 对于预先发票（invoiceType: 'AR'）或部分发票（invoiceType: 'TR'）创建贷项通知不再可能
  5. 为收据创建贷项通知不再可能
  6. 创建具有除UNDERACHIEVEMENT之外的其他bookingCategory的贷项通知不再可能
  7. 不再支持货币波动（CF）作为付款差异

保存贷项通知（CreditNote/Factory/saveCreditNote）

以下用例不再工作或已更改

  1. 贷项通知只能以状态DRAFT (100)创建，不能手动更改。使用相应的端点（例如sendViaEmail）来自动相应地更改状态
  2. 现在必须通过使用enshrine端点（见下文）来完成enshrine

已删除端点/CreditNote/Factory/createFromVoucher

此端点将被删除。在sevdesk-Update 2.0中，不再可以在sevdesk中为收据创建贷项通知。此端点继续为现有sevdesk系统版本1.0客户提供。

已删除端点/CreditNote/{creditNoteId}/changeStatus

此端点将被完全删除（包括sevdesk系统版本1.0！）！使用这些端点将自动相应地更改状态

新端点CreditNote/{creditNoteId}/resetToDraft

这个新端点可以用来将信用凭证的状态重置为草稿（100）。您可以在这里找到文档。

新端点 CreditNote/{creditNoteId}/resetToOpen

这个新端点可以用来将信用凭证的状态重置为开放（200）。您可以在这里找到文档。

新端点 CreditNote/{creditNoteId}/enshrine

收藏端点现在用来设置属性收藏。 由于法律原因，此操作不能撤销！

部件

在PUT和POST端点进行更严格的验证

以下用例不再工作或已更改

  1. 创建税率不为0.0、7.0和19.0的产品不再可能

安装与使用

需求

PHP 7.4及更高版本。也应在PHP 8.0中工作。

Composer

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

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/j-mastr/sevdesk-php-sdk.git"
    }
  ],
  "require": {
    "itsmind/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.8.0
  • 构建包: org.openapitools.codegen.languages.PhpClientCodegen