PHPackages prepaid-host/sevdesk-php-client - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. prepaid-host/sevdesk-php-client ActiveLibrary[API Development](/categories/api) prepaid-host/sevdesk-php-client =============================== 01PHP Since Mar 26Pushed 3y agoCompare [ Source](https://github.com/prepaid-host/sevdesk-php-client)[ Packagist](https://packagist.org/packages/prepaid-host/sevdesk-php-client)[ RSS](/packages/prepaid-host-sevdesk-php-client/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (1)Used By (0) SwaggerClient-php ================= [](#swaggerclient-php) **Contact:** To contact our support click [here](https://landing.sevdesk.de/service-support-center-technik) # 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**](https://landing.sevdesk.de/api-newsletter) 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: [![Get Request](OpenAPI/img/GETRequest.PNG)](OpenAPI/img/GETRequest.PNG) 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. [![](OpenAPI/img/ContactQueryWithoutEmbed.PNG)](OpenAPI/img/ContactQueryWithoutEmbed.PNG) 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". [![](OpenAPI/img/ContactQueryWithEmbed.PNG)](OpenAPI/img/ContactQueryWithEmbed.PNG) 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,`format`could 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](https://www.getpostman.com/) - [cURL](https://curl.haxx.se/download.html) This example will illustrate your first request, which is creating a new Contact in sevDesk. 1. Download [**Postman**](https://www.getpostman.com/) for your desired system and start the application 2. Enter **ht****tps://my.sevdesk.de/api/v1/Contact** as the url 3. Use the connective **?** to append **token=** to the end of the url, or create an authorization header. Insert your API token as the value 4. For this test, select **POST** as the HTTP method 5. 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** 6. Now go to **Body** (if you are not there yet) and enter the key-value pairs as shown in the following picture [![](OpenAPI/img/FirstRequestPostman.PNG)](OpenAPI/img/FirstRequestPostman.PNG) 7. Click on **Send**. Your response should now look like this: [![](OpenAPI/img/FirstRequestResponse.PNG)](OpenAPI/img/FirstRequestResponse.PNG) 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.This PHP package is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project: - API version: 2.0.0 - Build package: io.swagger.codegen.v3.generators.php.PhpClientCodegen Requirements ------------ [](#requirements) PHP 5.5 and later Installation & Usage ------------------------ [](#installation--usage) ### Composer [](#composer) To install the bindings via [Composer](http://getcomposer.org/), add the following to `composer.json`: ``` { "repositories": [ { "type": "git", "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git" } ], "require": { "GIT_USER_ID/GIT_REPO_ID": "*@dev" } } ``` Then run `composer install` ### Manual Installation [](#manual-installation) Download the files and include `autoload.php`: ``` require_once('/path/to/SwaggerClient-php/vendor/autoload.php'); ``` Tests ----- [](#tests) To run the unit tests: ``` composer install ./vendor/bin/phpunit ``` Getting Started --------------- [](#getting-started) Please follow the [installation procedure](#installation--usage) and then run the following: ```