sevDesk.NET 1.0.1

sevDesk.NET

A strongly-typed .NET client library for the sevDesk API. Manage invoices, contacts, vouchers, orders, credit notes, and more — with full async support and dependency injection.

Feature highlights:

• 20 typed clients covering the entire sevDesk REST API
• Strongly typed models and enums for all resources
• Transaction operations: save invoice/order/voucher with positions atomically
• PDF generation, email sending, status management, and document upload
• Pagination with SevDeskListResponse<T> and filtering
• Proper exception hierarchy (SevDeskAuthenticationException, SevDeskNotFoundException, SevDeskValidationException)
• IHttpClientFactory integration with automatic auth header injection
• Dependency injection via IServiceCollection.AddSevDesk()

Prerequisites

• A sevDesk account and API token
• .NET 10.0

Installation

dotnet add package sevDesk.NET

Getting Started

1. Register services

In Program.cs, register sevDesk.NET with your API token:

builder.Services.AddSevDesk(options =>
{
    options.ApiToken = "your-api-token";
});

For custom base URLs (e.g. self-hosted or proxy):

builder.Services.AddSevDesk(options =>
{
    options.ApiToken = "your-api-token";
    options.CustomBaseUrl = "https://my-proxy.example.com/api/v1";
});

2. Inject and use the client

public class InvoiceService
{
    private readonly ISevDeskClient _client;

    public InvoiceService(ISevDeskClient client)
    {
        _client = client;
    }

    public async Task ListRecentInvoicesAsync()
    {
        var result = await _client.Invoices.ListAsync();
        foreach (var invoice in result.Items)
        {
            Console.WriteLine($"{invoice.InvoiceNumber}: {invoice.SumGross} {invoice.Currency}");
        }
    }
}

3. Configuration via appsettings.json

{
  "SevDesk": {
    "ApiToken": "your-api-token"
  }
}

builder.Services.AddSevDesk(
    builder.Configuration.GetSection("SevDesk"));

Available Clients

Financial Documents

Contacts

Banking

Products

Organization

Reference Data

Key Operations

Create an invoice with positions

var invoice = await client.Invoices.SaveInvoiceAsync(
    new Invoice
    {
        Contact = new SevDeskObjectReference { Id = 123, ObjectName = "Contact" },
        InvoiceDate = DateTime.Today,
        Header = "Invoice 2024-001",
        TimeToPay = 14
    },
    new[]
    {
        new InvoicePos
        {
            Name = "Consulting",
            Quantity = 10,
            Price = 150.00m,
            Unity = new SevDeskObjectReference { Id = 1, ObjectName = "Unity" },
            TaxRate = 19
        }
    });

Get invoice PDF

byte[] pdf = await client.Invoices.GetPdfAsync(invoiceId);
File.WriteAllBytes("invoice.pdf", pdf);

Send invoice via email

await client.Invoices.SendViaEmailAsync(
    invoiceId,
    email: "customer@example.com",
    subject: "Your Invoice",
    text: "Please find your invoice attached.");

Pagination

var page = await client.Contacts.ListAsync(new PaginationParameters
{
    Limit = 50,
    Offset = 100
});

Console.WriteLine($"Showing {page.Items.Count} of {page.Total} contacts");

Upload a voucher with file

await using var stream = File.OpenRead("receipt.pdf");
var document = await client.Vouchers.UploadFileAsync(stream, "receipt.pdf");

Check account balance

decimal balance = await client.CheckAccounts.GetBalanceAsync(
    accountId,
    date: DateTime.Today);

Error Handling

sevDesk.NET uses a typed exception hierarchy:

try
{
    var invoice = await client.Invoices.GetAsync(id);
}
catch (SevDeskNotFoundException)
{
    // 404 — invoice not found
}
catch (SevDeskAuthenticationException)
{
    // 401 — invalid API token
}
catch (SevDeskValidationException ex)
{
    // 422 — validation error
    Console.WriteLine(ex.RawResponse);
}
catch (SevDeskApiException ex)
{
    // Other API errors
    Console.WriteLine($"{ex.StatusCode}: {ex.Message}");
}

Configuration

SevDeskOptions

Validation

AddSevDesk() validates options on registration:

• ApiToken must not be empty
• CustomBaseUrl (if set) must use HTTPS or be localhost

License

MIT