diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b18767..a263544 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ All notable changes to `laravel-sevdesk-api` will be documented in this file -## 1.0.0 - 201X-XX-XX +## 1.0.0 - 2021-12-05 - initial release +- implemented basic api handler +- implemented sevdesk contact api diff --git a/README.md b/README.md index f3458d6..f682782 100644 --- a/README.md +++ b/README.md @@ -39,20 +39,77 @@ return [ ]; ``` -## Instantiation +## Usage +First Instantiate a sevdesk instance. ```php $sevdeskApi = SevdeskApi::make(); ``` +### Create Contact -### Testing +Create sevdesk contacts. +There are 4 different default contact types in sevdesk. +- supplier +- customer +- partner +- prospect customer -``` bash -composer test +The optional `$parameter` is for additional information like description, vatNumber or bankNumber. + +```php +$sevdeskApi->contact()->createSupplier('Supplier Organisation', $parameter); +$sevdeskApi->contact()->createCustomer('Customer Organisation', $parameter); +$sevdeskApi->contact()->createPartner('Partner Organisation', $parameter); +$sevdeskApi->contact()->createProspectCustomer('Prospect Customer Organisation', $parameter); +``` +For custom contact types. + +```php +$sevdeskApi->contact()->createCustom('Custom Organisation', $categoryId, $parameter); +``` + +Check [Create Contact](https://my.sevdesk.de/api/ContactAPI/doc.html#operation/createContact) for more information. + +### Retrieve Contact + +To get all contacts. + +```php +$sevdeskApi->contact()->all(); +$sevdeskApi->contact()->allSupplier(); +$sevdeskApi->contact()->allCustomer(); +$sevdeskApi->contact()->allPartner(); +$sevdeskApi->contact()->allProspectCustomer(); +``` +To get all contacts from a custom type. + +```php +$sevdeskApi->contact()->allCustom($categoryId); +``` +To get a single contact. + +```php +$sevdeskApi->contact()->get($contactId); +``` + +### Update Contact + +To update a single contact. `$contactId` is required. + +```php +$sevdeskApi->contact()->update($contactId, $parameter); +``` + +### Delete Contact + +To delete a single contact. `$contactId` is required. + +```php +$sevdeskApi->contact()->delete($contactId); ``` -### Changelog +## Changelog Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently. @@ -62,7 +119,9 @@ Please see [CONTRIBUTING](CONTRIBUTING.md) for details. ### Security -If you discover any security related issues, please email exlo89@gmail.com instead of using the issue tracker. +If you discover any security related issues, please email +[hello@martin-appelmann.de](mailto:hello@martin-appelmann.de?subject=Laravel%20Sevdesk%20Issue) +instead of using the issue tracker. ## Credits diff --git a/src/Api/Contact.php b/src/Api/Contact.php index e7a36ec..9af24e1 100644 --- a/src/Api/Contact.php +++ b/src/Api/Contact.php @@ -11,15 +11,253 @@ use Exlo89\LaravelSevdeskApi\Api\Utils\ApiClient; use Exlo89\LaravelSevdeskApi\Api\Utils\Routes; +/** + * Sevdesk Contact Api + * + * @see https://5677.extern.sevdesk.dev/apiOverview/index.html#/doc-contacts + */ class Contact extends ApiClient { - public function all() + /** + * Contact categories + */ + const SUPPLIER = 2; + const CUSTOMER = 3; + const PARTNER = 4; + const PROSPECT_CUSTOMER = 28; + + // =========================== all ==================================== + + /** + * Return all organisation contacts by default. If you want organisations and persons use $depth = 1. + * + * @param int $depth + * @return mixed + */ + public function all(int $depth = 0) { - return $this->_get(Routes::CONTACT); + return $this->_get(Routes::CONTACT, ['depth' => $depth]); } + /** + * Return contacts filtered by city. + * + * @param string $city + * @param int $depth + * @return mixed + */ + public function allByCity(string $city, int $depth = 0) + { + return $this->_get(Routes::CONTACT, ['city' => $city, 'depth' => $depth]); + } + + /** + * Return supplier contacts. + * + * @param int $depth + * @return mixed + */ + public function allSuppliers(int $depth = 0) + { + return $this->_get(Routes::CONTACT, [ + 'category' => [ + "id" => self::SUPPLIER, + "objectName" => "Category" + ], + 'depth' => $depth, + ]); + } + + /** + * Return customer contacts. + * + * @param int $depth + * @return mixed + */ + public function allCustomers(int $depth = 0) + { + return $this->_get(Routes::CONTACT, [ + 'category' => [ + "id" => self::CUSTOMER, + "objectName" => "Category" + ], + 'depth' => $depth, + ]); + } + + /** + * Return partner contacts. + * + * @param int $depth + * @return mixed + */ + public function allPartners(int $depth = 0) + { + return $this->_get(Routes::CONTACT, [ + 'category' => [ + "id" => self::PARTNER, + "objectName" => "Category" + ], + 'depth' => $depth, + ]); + } + + /** + * Return prospect customer contacts. + * + * @param int $depth + * @return mixed + */ + public function allProspectCustomers(int $depth = 0) + { + return $this->_get(Routes::CONTACT, [ + 'category' => [ + "id" => self::PROSPECT_CUSTOMER, + "objectName" => "Category" + ], + 'depth' => $depth, + ]); + } + + /** + * Return contacts with custom category. + * + * @param int $contactCategory + * @param int $depth + * @return mixed + */ + public function allCustom(int $contactCategory, int $depth = 0) + { + return $this->_get(Routes::CONTACT, [ + 'category' => [ + "id" => $contactCategory, + "objectName" => "Category" + ], + 'depth' => $depth, + ]); + } + + // =========================== get ==================================== + + /** + * Return a single contact. + * + * @param $contactId + * @return mixed + */ public function get($contactId) { - return $this->_get(Routes::CONTACT . '/' . $contactId); + return $this->_get(Routes::CONTACT . '/' . $contactId)[0]; + } + + // ========================== create ================================== + + /** + * Create contact. + * + * @param int $contactType + * @param array $parameters + * @return mixed + */ + private function create(int $contactType, array $parameters = []) + { + $parameters['category'] = [ + "id" => $contactType, + "objectName" => "Category" + ]; + return $this->_post(Routes::CONTACT, $parameters); + } + + /** + * Create supplier contact. + * + * @param string $organisationName + * @param array $parameters + * @return mixed + */ + public function createSupplier(string $organisationName, array $parameters = []) + { + $parameters['name'] = $organisationName; + return $this->create(self::SUPPLIER, $parameters); + } + + /** + * Create customer contact. + * + * @param string $organisationName + * @param array $parameters + * @return mixed + */ + public function createCustomer(string $organisationName, array $parameters = []) + { + $parameters['name'] = $organisationName; + return $this->create(self::CUSTOMER, $parameters); + } + + /** + * Create partner contact. + * + * @param string $organisationName + * @param array $parameters + * @return mixed + */ + public function createPartner(string $organisationName, array $parameters = []) + { + $parameters['name'] = $organisationName; + return $this->create(self::PARTNER, $parameters); + } + + /** + * Create prospect customer contact. + * + * @param string $organisationName + * @param array $parameters + * @return mixed + */ + public function createProspectCustomer(string $organisationName, array $parameters = []) + { + $parameters['name'] = $organisationName; + return $this->create(self::PROSPECT_CUSTOMER, $parameters); + } + + /** + * Create contact with custom contact category. + * + * @param string $organisationName + * @param int $contactCategory + * @param array $parameters + * @return mixed + */ + public function createCustom(string $organisationName, int $contactCategory, array $parameters = []) + { + $parameters['name'] = $organisationName; + return $this->create($contactCategory, $parameters); + } + + // ========================== update ================================== + + /** + * Update an existing contact. + * + * @param $contactId + * @param array $parameters + * @return mixed + */ + public function update($contactId, array $parameters = []) + { + return $this->_put(Routes::CONTACT . '/' . $contactId, $parameters); + } + + // ========================== delete ================================== + + /** + * Delete an existing contact. + * + * @param $contactId + * @return mixed + */ + public function delete($contactId) + { + return $this->_delete(Routes::CONTACT . '/' . $contactId); } } diff --git a/src/Api/Utils/ApiClient.php b/src/Api/Utils/ApiClient.php index 0544980..c3d14b4 100644 --- a/src/Api/Utils/ApiClient.php +++ b/src/Api/Utils/ApiClient.php @@ -39,10 +39,13 @@ public function execute($httpMethod, $url, array $parameters = []) try { $parameters['token'] = $this->getToken(); $response = $this->getClient()->{$httpMethod}('api/v1/' . $url, ['query' => $parameters]); + $responseBody = json_decode((string)$response->getBody(), true); + return $responseBody['objects']; } catch (BadResponseException $exception) { $response = $exception->getResponse(); + return json_decode((string)$response->getBody(), true); } - return json_decode((string)$response->getBody(), true); + } // ========================= base methods ====================================== diff --git a/tests/TestCase.php b/tests/TestCase.php deleted file mode 100644 index 8c91abc..0000000 --- a/tests/TestCase.php +++ /dev/null @@ -1,28 +0,0 @@ -assertFalse(File::exists(config_path('sevdesk-api.php'))); - - Artisan::call('sevdesk-api:install'); - - $this->assertTrue(File::exists(config_path('sevdesk-api.php'))); - } -}