PHPackages                             ameax/sevdesk-api-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. ameax/sevdesk-api-client

ActiveLibrary[API Development](/categories/api)

ameax/sevdesk-api-client
========================

PHP client for SevDesk API integration using Saloon v3

10PHP

Since Mar 26Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/ameax/sevdesk-api-client)[ Packagist](https://packagist.org/packages/ameax/sevdesk-api-client)[ RSS](/packages/ameax-sevdesk-api-client/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (2)Used By (0)

SevDesk API Client
==================

[](#sevdesk-api-client)

A flexible PHP client for integrating with the SevDesk API using Saloon v3. This package can be used standalone or with Laravel.

Disclaimer
----------

[](#disclaimer)

This package is an unofficial API client for SevDesk. It is not affiliated with, officially maintained, or endorsed by SevDesk GmbH. SevDesk is a trademark of SevDesk GmbH.

This package is provided as-is for integration purposes. Users must comply with SevDesk's API terms of service.

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Saloon v3

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require ameax/sevdesk-api-client
```

Configuration
-------------

[](#configuration)

### Getting Your API Token

[](#getting-your-api-token)

1. Log in to your SevDesk account
2. Go to Settings → Users & Rights → Users
3. Click on your user
4. In the "API Token" section, you'll find your 32-character hexadecimal token
5. Click "Generate new" if you need a new token

### Standalone Usage (Without Laravel)

[](#standalone-usage-without-laravel)

```
use Ameax\SevDeskApi\SevDesk;

// Option 1: Simple initialization with API token
$sevdesk = new SevDesk('your_32_character_hexadecimal_token');

// Option 2: Initialize with array configuration
$sevdesk = new SevDesk([
    'api_token' => 'your_32_character_hexadecimal_token',
    'base_url' => 'https://my.sevdesk.de/api/v1', // optional, this is the default
    'user_agent' => 'My App/1.0', // optional
    'timeout' => 30, // optional, in seconds
]);

// Option 3: Initialize and configure separately
$sevdesk = new SevDesk();
$sevdesk->setApiToken('your_32_character_hexadecimal_token')
    ->setConfig('timeout', 60)
    ->setConfig('user_agent', 'My App/1.0');
```

### Laravel Usage

[](#laravel-usage)

#### 1. Publish Configuration (Optional)

[](#1-publish-configuration-optional)

If you want to use Laravel's configuration system:

```
php artisan vendor:publish --tag=sevdesk-config
```

#### 2. Add Environment Variables

[](#2-add-environment-variables)

Add your SevDesk API token to your `.env` file:

```
SEVDESK_API_TOKEN=your_32_character_hexadecimal_token
SEVDESK_BASE_URL=https://my.sevdesk.de/api/v1
SEVDESK_TIMEOUT=30

```

#### 3. Usage in Laravel

[](#3-usage-in-laravel)

```
use Ameax\SevDeskApi\SevDesk;

// Get the SevDesk instance from the container
$sevdesk = app(SevDesk::class);

// Or use dependency injection
public function __construct(private SevDesk $sevdesk) {}

// Or create a custom service
namespace App\Services;

use Ameax\SevDeskApi\SevDesk;

class SevDeskService
{
    protected SevDesk $connector;

    public function __construct(string $apiToken)
    {
        $this->connector = new SevDesk($apiToken);
    }

    public function connector(): SevDesk
    {
        return $this->connector;
    }
}
```

Usage Examples
--------------

[](#usage-examples)

### Working with Contacts

[](#working-with-contacts)

```
// Get all contacts (organizations and persons)
$response = $sevdesk->contact()->getContacts('1', null);
$contacts = $response->json('objects') ?? [];

// Get only organizations
$response = $sevdesk->contact()->getContacts('0', null);

// Get contact by customer number
$response = $sevdesk->contact()->getContacts(null, 'CUST-12345');

// Get a specific contact by ID
$response = $sevdesk->contact()->getContactById(123456);
$contact = $response->json('objects.0');

// Create a new contact (organization)
$request = new \Ameax\SevDeskApi\Requests\Contact\CreateContact();
$request->body()->set([
    'name' => 'ACME Corporation',
    'status' => 100, // 100 = Active
    'customerNumber' => 'CUST-' . time(),
    'category' => [
        'id' => 3, // 3 = Organization, 1 = Person
        'objectName' => 'Category'
    ],
    'description' => 'Important customer',
    'vatNumber' => 'DE123456789',
    'taxNumber' => '12/345/67890',
    'bankAccount' => 'DE89370400440532013000',
    'bankNumber' => 'COBADEFFXXX',
    'defaultTimeToPay' => 14,
]);
$response = $sevdesk->send($request);

// Delete a contact
$response = $sevdesk->contact()->deleteContact(123456);
```

### Working with Invoices

[](#working-with-invoices)

```
// Get all invoices
$response = $sevdesk->invoice()->getInvoices(
    status: null,        // null for all, 50 = draft, 100 = open, 200 = paid
    invoiceNumber: null,
    startDate: null,
    endDate: null,
    contactId: null,
    contactObjectName: null
);
$invoices = $response->json('objects') ?? [];

// Get a specific invoice
$response = $sevdesk->invoice()->getInvoiceById($invoiceId);

// Create an invoice using the factory pattern
$request = new \Ameax\SevDeskApi\Requests\Invoice\CreateInvoiceByFactory();
$request->body()->set([
    'invoice' => [
        'invoiceNumber' => 'RE-10001',
        'contact' => [
            'id' => 123456,
            'objectName' => 'Contact'
        ],
        'invoiceDate' => date('Y-m-d'),
        'header' => 'Invoice for Services',
        'status' => 100, // 100 = Draft
        'taxType' => 'default',
        'invoiceType' => 'RE', // RE = Invoice
    ],
    'invoicePosSave' => [
        [
            'quantity' => 1,
            'price' => 100.00,
            'name' => 'Consulting Service',
            'unity' => [
                'id' => 1,
                'objectName' => 'Unity'
            ],
            'taxRate' => 19,
        ]
    ]
]);
$response = $sevdesk->send($request);

// Send invoice via email
$request = new \Ameax\SevDeskApi\Requests\Invoice\SendInvoiceViaEmail($invoiceId);
$request->body()->set([
    'toEmail' => 'customer@example.com',
    'subject' => 'Your Invoice',
    'text' => 'Please find your invoice attached.',
]);
$response = $sevdesk->send($request);

// Get invoice PDF
$response = $sevdesk->invoice()->invoiceGetPdf($invoiceId, download: true, preventSendBy: false);
```

### Working with Check Accounts (Bank Accounts)

[](#working-with-check-accounts-bank-accounts)

```
// Get all check accounts
$response = $sevdesk->checkAccount()->getCheckAccounts();
$accounts = $response->json('objects') ?? [];

// Get account balance at specific date
$response = $sevdesk->checkAccount()->getBalanceAtDate(
    checkAccountId: 123456,
    date: '2024-12-31'
);
```

### Working with Parts (Products/Services)

[](#working-with-parts-productsservices)

```
// Get all parts
$response = $sevdesk->part()->getParts();
$parts = $response->json('objects') ?? [];

// Create a new part
$request = new \Ameax\SevDeskApi\Requests\Part\CreatePart();
$request->body()->set([
    'name' => 'Consulting Hour',
    'partNumber' => 'SERV-001',
    'stock' => 0,
    'unity' => [
        'id' => 1, // 1 = Piece
        'objectName' => 'Unity'
    ],
    'price' => 150.00,
    'priceNet' => 150.00,
    'priceGross' => 178.50,
    'pricePurchase' => null,
    'taxRate' => 19,
    'status' => 100, // 100 = Active
]);
$response = $sevdesk->send($request);
```

### Error Handling

[](#error-handling)

```
try {
    $response = $sevdesk->contact()->getContacts('1', null);

    if ($response->successful()) {
        $contacts = $response->json('objects') ?? [];
        // Process contacts
    } else {
        // Handle API error
        $error = $response->json();
        $statusCode = $response->status();

        switch ($statusCode) {
            case 401:
                throw new Exception('Invalid API token');
            case 404:
                throw new Exception('Resource not found');
            case 422:
                throw new Exception('Validation error: ' . json_encode($error));
            default:
                throw new Exception('API error: ' . $response->body());
        }
    }
} catch (\Exception $e) {
    // Handle exception
    logger()->error('SevDesk API error: ' . $e->getMessage());
}
```

Available Resources
-------------------

[](#available-resources)

Each resource provides methods for interacting with specific SevDesk entities:

### Core Resources

[](#core-resources)

- `$sevdesk->contact()` - Customer and supplier management
- `$sevdesk->invoice()` - Invoice creation and management
- `$sevdesk->order()` - Order processing
- `$sevdesk->creditNote()` - Credit note handling
- `$sevdesk->voucher()` - Expense tracking
- `$sevdesk->part()` - Product and service catalog

### Financial Resources

[](#financial-resources)

- `$sevdesk->checkAccount()` - Bank account management
- `$sevdesk->checkAccountTransaction()` - Bank transactions
- `$sevdesk->accountingContact()` - Accounting-specific contacts

### Supporting Resources

[](#supporting-resources)

- `$sevdesk->tag()` - Organization and categorization
- `$sevdesk->communicationWay()` - Contact communication methods
- `$sevdesk->contactAddress()` - Contact addresses
- `$sevdesk->layout()` - Document layouts
- `$sevdesk->export()` - Data export functionality
- `$sevdesk->report()` - Financial reporting

Common Patterns
---------------

[](#common-patterns)

### Pagination

[](#pagination)

Most list endpoints support pagination:

```
$limit = 50;
$offset = 0;

do {
    $response = $sevdesk->contact()->getContacts('1', null);
    // Note: The SDK's getContacts method doesn't support limit/offset parameters directly
    // You would need to modify the request or use the raw API

    $contacts = $response->json('objects') ?? [];

    // Process contacts
    foreach ($contacts as $contact) {
        // Process each contact
    }

    $offset += $limit;
} while (count($contacts) >= $limit);
```

### Filtering and Searching

[](#filtering-and-searching)

Many endpoints support filtering through query parameters:

```
// Search contacts by various criteria
// Note: These would require custom requests as the SDK methods have limited parameters
$request = new \Saloon\Http\Request();
$request->setMethod('GET');
$request->setEndpoint('/Contact');
$request->query()->add([
    'depth' => 1,
    'name' => 'ACME',     // Search by name
    'email' => '@acme.com', // Search by email
    'limit' => 100,
]);
$response = $sevdesk->send($request);
```

### Working with Enums

[](#working-with-enums)

The package includes various enum classes for type-safe values:

```
use Ameax\SevDeskApi\Enums\Status\InvoiceStatus;
use Ameax\SevDeskApi\Enums\Type\InvoiceType;
use Ameax\SevDeskApi\Enums\ObjectName;

// Use enum values
$status = InvoiceStatus::DRAFT; // 100
$type = InvoiceType::INVOICE; // 'RE'
$objectName = ObjectName::CONTACT; // 'Contact'
```

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues

[](#common-issues)

1. **Authentication Error (401)**

    - Verify your API token is correct
    - Check if the token has been regenerated in SevDesk
    - Ensure the token is exactly 32 characters
2. **Not Found Error (404)**

    - Check if the resource ID exists
    - Verify you're using the correct endpoint
    - Some resources may have been deleted
3. **Validation Error (422)**

    - Check required fields are provided
    - Verify data types match API expectations
    - Review the error response for specific field errors
4. **Timeout Errors**

    - Increase the timeout in configuration
    - Check your network connection
    - SevDesk API might be experiencing high load

### Debug Mode

[](#debug-mode)

Enable debug mode to see detailed request/response information:

```
// For Saloon v3, you can add middleware or use Laravel's HTTP client debugging
$sevdesk->getConfig('debug', true);
```

Limitations
-----------

[](#limitations)

- The current version of the SDK has limited support for request body parameters in some update methods
- Some endpoints may require custom requests for advanced filtering
- Bulk operations are not directly supported by all resources

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

Support
-------

[](#support)

For API-specific questions, refer to the [SevDesk API documentation](https://api.sevdesk.de/).

For package-specific issues, please create an issue on GitHub.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

16

—

LowBetter than 5% of packages

Maintenance41

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 76.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/f67be86f330b5a3e644c8594bbf322be6ab1a08da5434d9cef417097d5567287?d=identicon)[aranes](/maintainers/aranes)

---

Top Contributors

[![ms-aranes](https://avatars.githubusercontent.com/u/69188126?v=4)](https://github.com/ms-aranes "ms-aranes (10 commits)")[![raymadrona](https://avatars.githubusercontent.com/u/4514908?v=4)](https://github.com/raymadrona "raymadrona (2 commits)")[![Inoqulath](https://avatars.githubusercontent.com/u/104569371?v=4)](https://github.com/Inoqulath "Inoqulath (1 commits)")

### Embed Badge

![Health badge](/badges/ameax-sevdesk-api-client/health.svg)

```
[![Health](https://phpackages.com/badges/ameax-sevdesk-api-client/health.svg)](https://phpackages.com/packages/ameax-sevdesk-api-client)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[knplabs/github-api

GitHub API v3 client

2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk

PHP SDK for Facebook Business

90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

73813.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

263103.1M454](/packages/google-gax)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)