README

This unofficial package provides an SDK to access the sevDesk API using PHP. It is auto-generated using the OpenAPI-Generator, with slight adjustments to the official OpenAPI specification.

For support regarding the API, please contact the sevDesk support directly.

Contact: To contact our support click here

General information

Welcome to our API!
sevDesk offers you the possibility of retrieving data using an interface, namely the sevDesk API, and making changes without having to use the web UI. The sevDesk interface is a REST-Full API. All sevDesk data and functions that are used in the web UI can also be controlled through the API.

Cross-Origin Resource Sharing

This API features Cross-Origin Resource Sharing (CORS).
It enables cross-domain communication from the browser.
All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.

Embedding resources

When retrieving resources by using this API, you might encounter nested resources in the resources you requested.
For example, an invoice always contains a contact, of which you can see the ID and the object name.
This API gives you the possibility to embed these resources completely into the resources you originally requested.
Taking our invoice example, this would mean, that you would not only see the ID and object name of a contact, but rather the complete contact resource.

To embed resources, all you need to do is to add the query parameter 'embed' to your GET request.
As values, you can provide the name of the nested resource.
Multiple nested resources are also possible by providing multiple names, separated by a comma.

Authentication and Authorization

The sevDesk API uses a token authentication to authorize calls. For this purpose every sevDesk administrator has one API token, which is a hexadecimal string containing 32 characters. The following clip shows where you can find the API token if this is your first time with our API.

The token will be needed in every request that you want to send and needs to be attached to the request url as a Query Parameter
or provided as a value of an Authorization Header.
For security reasons, we suggest putting the API Token in the Authorization Header and not in the query string.
However, in the request examples in this documentation, we will keep it in the query string, as it is easier for you to copy them and try them yourself.
The following url is an example that shows where your token needs to be placed as a query parameter.
In this case, we used some random API token.

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

The next example shows the token in the Authorization Header.

"Authorization" :"b7794de0085f5cd00560f160f290af38"

The api tokens have an infinite lifetime and, in other words, exist as long as the sevDesk user exists.
For this reason, the user should NEVER be deleted.
If really necessary, it is advisable to save the api token as we will NOT be able to retrieve it afterwards!
It is also possible to generate a new API token, for example, if you want to prevent the usage of your sevDesk account by other people who got your current API token.
To achieve this, you just need to click on the "generate new" symbol to the right of your token and confirm it with your password.

API News

To never miss API news and updates again, subscribe to our free API newsletter and get all relevant information to keep your sevDesk software running smoothly. To subscribe, simply click here and confirm the email address to which we may send all updates relevant to you.

API Requests

In our case, REST API requests need to be build by combining the following components.

Component	Description
HTTP-Methods	GET (retrieve a resource) POST (create a resource) PUT (update a resource) DELETE (delete a resource)
URL of the API	https://my.sevdesk.de/api/v1
URI of the resource	The resource to query. For example contacts in sevDesk: /Contact Which will result in the following complete URL: https://my.sevdesk.de/api/v1/Contact
Query parameters	Are attached by using the connectives ? and & in the URL.
Request headers	Typical request headers are for example: Content-type Authorization Accept-Encoding User-Agent ...
Request body	Mostly required in POST and PUT requests. Often the request body contains json, in our case, it also accepts url-encoded data.

Note: please pass a meaningful entry at the header "User-Agent". If the "User-Agent" is set meaningfully, we can offer better support in case of queries from customers.
An example how such a "User-Agent" can look like: "Integration-name by abc".

This is a sample request for retrieving existing contacts in sevDesk using curl:

As you can see, the request contains all the components mentioned above.
It's HTTP method is GET, it has a correct endpoint (https://my.sevdesk.de/api/v1/Contact), query parameters like token and additional header information!

Query Parameters

As you might have seen in the sample request above, there are several other parameters besides "token", located in the url.
Those are mostly optional but prove to be very useful for a lot of requests as they can limit, extend, sort or filter the data you will get as a response.

These are the three most used query parameter for the sevDesk API.

Parameter	Description
limit	Limits the number of entries that are returned. Most useful in GET requests which will most likely deliver big sets of data like country or currency lists. In this case, you can bypass the default limitation on returned entries by providing a high number.
offset	Specifies a certain offset for the data that will be returned. As an example, you can specify "offset=2" if you want all entries except for the first two.
embed	Will extend some of the returned data. A brief example can be found below.

This is an example for the usage of the embed parameter.
The following first request will return all company contact entries in sevDesk up to a limit of 100 without any additional information and no offset.

Now have a look at the category attribute located in the response.
Naturally, it just contains the id and the object name of the object but no further information.
We will now use the parameter embed with the value "category".

As you can see, the category object is now extended and shows all the attributes and their corresponding values.

There are lot of other query parameters that can be used to filter the returned data for objects that match a certain pattern, however, those will not be mentioned here and instead can be found at the detail documentation of the most used API endpoints like contact, invoice or voucher.

Request Headers

The HTTP request (response) headers allow the client as well as the server to pass additional information with the request.
They transfer the parameters and arguments which are important for transmitting data over HTTP.
Three headers which are useful / necessary when using the sevDesk API are "Authorization, "Accept" and "Content-type".
Underneath is a brief description of why and how they should be used.

Authorization

Can be used if you want to provide your API token in the header instead of having it in the url.

Authorization:yourApiToken

Accept

Specifies the format of the response.
Required for operations with a response body.

Accept:application/format

In our case, format could be replaced with json or xml

Content-type

Specifies which format is used in the request.
Is required for operations with a request body.

Content-type:application/format

In our case,formatcould be replaced with json or x-www-form-urlencoded

API Responses

HTTP status codes
When calling the sevDesk API it is very likely that you will get a HTTP status code in the response.
Some API calls will also return JSON response bodies which will contain information about the resource.
Each status code which is returned will either be a success code or an error code.

Success codes

Status code	Description
`200 OK`	The request was successful
`201 Created`	Most likely to be found in the response of a POST request. This code indicates that the desired resource was successfully created.

Error codes

Status code	Description
`400 Bad request`	The request you sent is most likely syntactically incorrect. You should check if the parameters in the request body or the url are correct.
`401 Unauthorized`	The authentication failed. Most likely caused by a missing or wrong API token.
`403 Forbidden`	You do not have the permission the access the resource which is requested.
`404 Not found`	The resource you specified does not exist.
`500 Internal server error`	An internal server error has occurred. Normally this means that something went wrong on our side. However, sometimes this error will appear if we missed to catch an error which is normally a 400 status code!

Your First Request

After reading the introduction to our API, you should now be able to make your first call.
For testing our API, we would always recommend to create a trial account for sevDesk to prevent unwanted changes to your main account.
A trial account will be in the highest tariff (materials management), so every sevDesk function can be tested!

To start testing we would recommend one of the following tools:

Postman
cURL

This example will illustrate your first request, which is creating a new Contact in sevDesk.

Download Postman for your desired system and start the application
Enter https://my.sevdesk.de/api/v1/Contact as the url
Use the connective ? to append token= to the end of the url, or create an authorization header. Insert your API token as the value
For this test, select POST as the HTTP method
Go to Headers and enter the key-value pair Content-type + application/x-www-form-urlencoded
As an alternative, you can just go to Body and select x-www-form-urlencoded
Now go to Body (if you are not there yet) and enter the key-value pairs as shown in the following picture
Click on Send. Your response should now look like this:

As you can see, a successful response in this case returns a JSON-formatted response body containing the contact you just created.
For keeping it simple, this was only a minimal example of creating a contact.
There are however numerous combinations of parameters that you can provide which add information to your contact.

Installation & Usage

Requirements

PHP 7.4 and later. Should also work with PHP 8.0.

Composer

To install the bindings via Composer, add the following to composer.json:

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

Then run composer install

Manual Installation

Download the files and include autoload.php:

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

Getting Started

Please follow the installation procedure and then run the following:

<?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 Endpoints

All URIs are relative to https://my.sevdesk.de/api/v1

Class	Method	HTTP request	Description
AccountingContactApi	createAccountingContact	POST /AccountingContact	Create a new accounting contact
AccountingContactApi	deleteAccountingContact	DELETE /AccountingContact/{accountingContactId}	Deletes an accounting contact
AccountingContactApi	getAccountingContact	GET /AccountingContact	Retrieve accounting contact
AccountingContactApi	getAccountingContactById	GET /AccountingContact/{accountingContactId}	Find accounting contact by ID
AccountingContactApi	updateAccountingContact	PUT /AccountingContact/{accountingContactId}	Update an existing accounting contact
CheckAccountApi	createCheckAccount	POST /CheckAccount	Create a new check account
CheckAccountApi	deleteCheckAccount	DELETE /CheckAccount/{checkAccountId}	Deletes a check account
CheckAccountApi	getBalanceAtDate	GET /CheckAccount/{checkAccountId}/getBalanceAtDate	Get the balance at a given date
CheckAccountApi	getCheckAccountById	GET /CheckAccount/{checkAccountId}	Find check account by ID
CheckAccountApi	getCheckAccounts	GET /CheckAccount	Retrieve check accounts
CheckAccountApi	updateCheckAccount	PUT /CheckAccount/{checkAccountId}	Update an existing check account
CheckAccountTransactionApi	createTransaction	POST /CheckAccountTransaction	Create a new transaction
CheckAccountTransactionApi	deleteCheckAccountTransaction	DELETE /CheckAccountTransaction/{checkAccountTransactionId}	Deletes a check account transaction
CheckAccountTransactionApi	getCheckAccountTransactionById	GET /CheckAccountTransaction/{checkAccountTransactionId}	Find check account transaction by ID
CheckAccountTransactionApi	getTransactions	GET /CheckAccountTransaction	Retrieve transactions
CheckAccountTransactionApi	updateCheckAccountTransaction	PUT /CheckAccountTransaction/{checkAccountTransactionId}	Update an existing check account transaction
CommunicationWayApi	createCommunicationWay	POST /CommunicationWay	Create a new contact communication way
CommunicationWayApi	deleteCommunicationWay	DELETE /CommunicationWay/{communicationWayId}	Deletes a communication way
CommunicationWayApi	getCommunicationWayById	GET /CommunicationWay/{communicationWayId}	Find communication way by ID
CommunicationWayApi	getCommunicationWayKeys	GET /CommunicationWayKey	Retrieve communication way keys
CommunicationWayApi	getCommunicationWays	GET /CommunicationWay	Retrieve communication ways
CommunicationWayApi	updateCommunicationWay	PUT /CommunicationWay/{communicationWayId}	Update a existing communication way
ContactApi	contactCustomerNumberAvailabilityCheck	GET /Contact/Mapper/checkCustomerNumberAvailability	Check if a customer number is available
ContactApi	createContact	POST /Contact	Create a new contact
ContactApi	deleteContact	DELETE /Contact/{contactId}	Deletes a contact
ContactApi	findContactsByCustomFieldValue	GET /Contact/Factory/findContactsByCustomFieldValue	Find contacts by custom field value
ContactApi	getContactById	GET /Contact/{contactId}	Find contact by ID
ContactApi	getContactTabsItemCountById	GET /Contact/{contactId}/getTabsItemCount	Get number of all items
ContactApi	getContacts	GET /Contact	Retrieve contacts
ContactApi	getNextCustomerNumber	GET /Contact/Factory/getNextCustomerNumber	Get next free customer number
ContactApi	updateContact	PUT /Contact/{contactId}	Update a existing contact
ContactAddressApi	contactAddressId	GET /ContactAddress/{contactAddressId}	Find contact address by ID
ContactAddressApi	createContactAddress	POST /ContactAddress	Create a new contact address
ContactAddressApi	deleteContactAddress	DELETE /ContactAddress/{contactAddressId}	Deletes a contact address
ContactAddressApi	getContactAddresses	GET /ContactAddress	Retrieve contact addresses
ContactAddressApi	updateContactAddress	PUT /ContactAddress/{contactAddressId}	update a existing contact address
ContactFieldApi	createContactField	POST /ContactCustomField	Create contact field
ContactFieldApi	createContactFieldSetting	POST /ContactCustomFieldSetting	Create contact field setting
ContactFieldApi	deleteContactCustomFieldId	DELETE /ContactCustomField/{contactCustomFieldId}	delete a contact field
ContactFieldApi	deleteContactFieldSetting	DELETE /ContactCustomFieldSetting/{contactCustomFieldSettingId}	Deletes a contact field setting
ContactFieldApi	getContactFieldSettingById	GET /ContactCustomFieldSetting/{contactCustomFieldSettingId}	Find contact field setting by ID
ContactFieldApi	getContactFieldSettings	GET /ContactCustomFieldSetting	Retrieve contact field settings
ContactFieldApi	getContactFields	GET /ContactCustomField	Retrieve contact fields
ContactFieldApi	getContactFieldsById	GET /ContactCustomField/{contactCustomFieldId}	Retrieve contact fields
ContactFieldApi	getPlaceholder	GET /Textparser/fetchDictionaryEntriesByType	Retrieve Placeholders
ContactFieldApi	getReferenceCount	GET /ContactCustomFieldSetting/{contactCustomFieldSettingId}/getReferenceCount	Receive count reference
ContactFieldApi	updateContactFieldSetting	PUT /ContactCustomFieldSetting/{contactCustomFieldSettingId}	Update contact field setting
ContactFieldApi	updateContactfield	PUT /ContactCustomField/{contactCustomFieldId}	Update a contact field
CreditNoteApi	bookCreditNote	PUT /CreditNote/{creditNoteId}/bookAmount	Book a credit note
CreditNoteApi	createCreditNoteFromInvoice	POST /CreditNote/Factory/createFromInvoice	Creates a new creditNote from an invoice
CreditNoteApi	createCreditNoteFromVoucher	POST /CreditNote/Factory/createFromVoucher	Creates a new creditNote from a voucher
CreditNoteApi	createcreditNote	POST /CreditNote/Factory/saveCreditNote	Create a new creditNote
CreditNoteApi	creditNoteGetPdf	GET /CreditNote/{creditNoteId}/getPdf	Retrieve pdf document of a credit note
CreditNoteApi	creditNoteSendBy	PUT /CreditNote/{creditNoteId}/sendBy	Mark credit note as sent
CreditNoteApi	deletecreditNote	DELETE /CreditNote/{creditNoteId}	Deletes an creditNote
CreditNoteApi	getCreditNotes	GET /CreditNote	Retrieve CreditNote
CreditNoteApi	getcreditNoteById	GET /CreditNote/{creditNoteId}	Find creditNote by ID
CreditNoteApi	sendCreditNoteByPrinting	GET /CreditNote/{creditNoteId}/sendByWithRender	Send credit note by printing
CreditNoteApi	sendCreditNoteViaEMail	POST /CreditNote/{creditNoteId}/sendViaEmail	Send credit note via email
CreditNoteApi	updatecreditNote	PUT /CreditNote/{creditNoteId}	Update an existing creditNote
CreditNotePosApi	getcreditNotePositions	GET /CreditNotePos	Retrieve creditNote positions
DocumentApi	getDocuments	GET /Document	Retrieve documents
ExportApi	exportContact	GET /Export/contactListCsv	Export contact
ExportApi	exportCreditNote	GET /Export/creditNoteCsv	Export creditNote
ExportApi	exportDatev	GET /Export/datevCSV	Export datev
ExportApi	exportInvoice	GET /Export/invoiceCsv	Export invoice
ExportApi	exportInvoiceZip	GET /Export/invoiceZip	Export Invoice as zip
ExportApi	exportTransactions	GET /Export/transactionsCsv	Export transaction
ExportApi	exportVoucher	GET /Export/voucherListCsv	Export voucher as zip
ExportApi	exportVoucherZip	GET /Export/voucherZip	Export voucher zip
ExportApi	updateExportConfig	PUT /SevClient/{SevClientId}/updateExportConfig	Update export config
InvoiceApi	bookInvoice	PUT /Invoice/{invoiceId}/bookAmount	Book an invoice
InvoiceApi	cancelInvoice	POST /Invoice/{invoiceId}/cancelInvoice	Cancel an invoice / Create cancellation invoice
InvoiceApi	createInvoiceByFactory	POST /Invoice/Factory/saveInvoice	Create a new invoice
InvoiceApi	createInvoiceFromOrder	POST /Invoice/Factory/createInvoiceFromOrder	Create invoice from order
InvoiceApi	createInvoiceReminder	POST /Invoice/Factory/createInvoiceReminder	Create invoice reminder
InvoiceApi	deleteInvoiceById	DELETE /Invoice/{invoiceId}	Delete invoice by ID
InvoiceApi	getInvoiceById	GET /Invoice/{invoiceId}	Find invoice by ID
InvoiceApi	getInvoicePositionsById	GET /Invoice/{invoiceId}/getPositions	Find invoice positions
InvoiceApi	getInvoices	GET /Invoice	Retrieve invoices
InvoiceApi	getIsInvoicePartiallyPaid	GET /Invoice/{invoiceId}/getIsPartiallyPaid	Check if an invoice is already partially paid
InvoiceApi	getLastDunning	GET /Invoice/{invoiceId}/getLastDunning	Get the last dunning of an invoice
InvoiceApi	getOpenInvoiceReminderDebit	GET /Invoice/Factory/getOpenInvoiceReminderDebit	Get the oben reminder debit for an invoice
InvoiceApi	invoiceGetPdf	GET /Invoice/{invoiceId}/getPdf	Retrieve pdf document of an invoice
InvoiceApi	invoiceRender	POST /Invoice/{invoiceId}/render	Render the pdf document of an invoice
InvoiceApi	invoiceSendBy	PUT /Invoice/{invoiceId}/sendBy	Mark invoice as sent
InvoiceApi	sendInvoiceViaEMail	POST /Invoice/{invoiceId}/sendViaEmail	Send invoice via email
InvoiceApi	updateInvoiceById	PUT /Invoice/{invoiceId}	Update invoice by ID
InvoiceApi	updateStatus	PUT /Invoice/{invoiceId}/changeStatus	Update the status of an invoice
InvoicePosApi	getInvoicePos	GET /InvoicePos	Retrieve InvoicePos
LayoutApi	getLetterpapersWithThumb	GET /DocServer/getLetterpapersWithThumb	Retrieve letterpapers
LayoutApi	getTemplates	GET /DocServer/getTemplatesWithThumb	Retrieve templates
LayoutApi	updateCreditNoteTemplate	PUT /CreditNote/{creditNoteId}/changeParameter	Update an of credit note template
LayoutApi	updateInvoiceTemplate	PUT /Invoice/{invoiceId}/changeParameter	Update an invoice template
LayoutApi	updateOrderTemplate	PUT /Order/{orderId}/changeParameter	Update an order template
OrderApi	createContractNoteFromOrder	POST /Order/Factory/createContractNoteFromOrder	Create contract note from order
OrderApi	createOrder	POST /Order/Factory/saveOrder	Create a new order
OrderApi	createPackingListFromOrder	POST /Order/Factory/createPackingListFromOrder	Create packing list from order
OrderApi	deleteOrder	DELETE /Order/{orderId}	Deletes an order
OrderApi	getDiscounts	GET /Order/{orderId}/getDiscounts	Find order discounts
OrderApi	getOrderById	GET /Order/{orderId}	Find order by ID
OrderApi	getOrderPositionsById	GET /Order/{orderId}/getPositions	Find order positions
OrderApi	getOrders	GET /Order	Retrieve orders
OrderApi	getRelatedObjects	GET /Order/{orderId}/getRelatedObjects	Find related objects
OrderApi	orderGetPdf	GET /Order/{orderId}/getPdf	Retrieve pdf document of an order
OrderApi	orderSendBy	PUT /Order/{orderId}/sendBy	Mark order as sent
OrderApi	sendorderViaEMail	POST /Order/{orderId}/sendViaEmail	Send order via email
OrderApi	updateOrder	PUT /Order/{orderId}	Update an existing order
OrderPosApi	deleteOrderPos	DELETE /OrderPos/{orderPosId}	Deletes an order Position
OrderPosApi	getOrderPositionById	GET /OrderPos/{orderPosId}	Find order position by ID
OrderPosApi	getOrderPositions	GET /OrderPos	Retrieve order positions
OrderPosApi	updateOrderPosition	PUT /OrderPos/{orderPosId}	Update an existing order position
PartApi	createPart	POST /Part	Create a new part
PartApi	getPartById	GET /Part/{partId}	Find part by ID
PartApi	getParts	GET /Part	Retrieve parts
PartApi	partGetStock	GET /Part/{partId}/getStock	Get stock of a part
PartApi	updatePart	PUT /Part/{partId}	Update an existing part
ReportApi	reportContact	GET /Report/contactlist	Export contact list
ReportApi	reportInvoice	GET /Report/invoicelist	Export invoice list
ReportApi	reportOrder	GET /Report/orderlist	Export order list
ReportApi	reportVoucher	GET /Report/voucherlist	Export voucher list
TagApi	createTag	POST /Tag/Factory/create	Create a new tag
TagApi	deleteTag	DELETE /Tag/{tagId}	Deletes a tag
TagApi	getTagById	GET /Tag/{tagId}	Find tag by ID
TagApi	getTagRelations	GET /TagRelation	Retrieve tag relations
TagApi	getTags	GET /Tag	Retrieve tags
TagApi	updateTag	PUT /Tag/{tagId}	Update tag
TextTemplateApi	addTextTemplate	POST /TextTemplate	Create a new text template
TextTemplateApi	deleteTextTemplate	DELETE /TextTemplate/{id}	Delete an existing text template
TextTemplateApi	getTextTemplate	GET /TextTemplate	Get an overview of all text template
TextTemplateApi	updateTextTemplate	PUT /TextTemplate/{id}	Update an existing text template
VoucherApi	bookVoucher	PUT /Voucher/{voucherId}/bookAmount	Book a voucher
VoucherApi	createVoucherByFactory	POST /Voucher/Factory/saveVoucher	Create a new voucher
VoucherApi	getVoucherById	GET /Voucher/{voucherId}	Find voucher by ID
VoucherApi	getVouchers	GET /Voucher	Retrieve vouchers
VoucherApi	updateVoucher	PUT /Voucher/{voucherId}	Update an existing voucher
VoucherApi	voucherUploadFile	POST /Voucher/Factory/uploadTempFile	Upload voucher file
VoucherPosApi	getVoucherPositions	GET /VoucherPos	Retrieve voucher positions

Models

Authorization

Authentication schemes defined for the API:

api_key

Type: API key
API key parameter name: Authorization
Location: HTTP header

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

API version: 2.0.0
Build package: org.openapitools.codegen.languages.PhpClientCodegen

itsmind / sevdesk-php-client

Maintainers

Details