### Install lexoffice-client-js with npm or yarn

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

This snippet shows how to install the lexoffice-client-js library using either npm or yarn package managers. These are standard commands for adding JavaScript dependencies to a project.

```bash
npm install @elbstack/lexoffice-client-js
```

```bash
yarn add @elbstack/lexoffice-client-js
```

--------------------------------

### Retrieve an invoice using lexoffice-client-js

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

This TypeScript example shows how to retrieve a specific invoice using the lexoffice-client-js. It uses an async function and handles the promise result, checking if the operation was successful ('ok') or if an error occurred.

```typescript
const invoiceResult = await client.retrieveInvoice('caf4e0c3-c3e8-4a06-bcfe-346bc7190b2');

if (invoiceResult.ok) {
  const invoice = invoiceResult.val;
} else {
  console.error('An error occured');
}
```

--------------------------------

### Render lexoffice Invoice Document as PDF

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Obtains the document file ID for rendering an invoice as a PDF. After getting the file ID, it proceeds to download the actual PDF file content. This operation requires the invoice to be finalized first. It returns the PDF content as an ArrayBuffer or an error.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';
import * as fs from 'fs';

const client = new Client('your-api-key');

// Get document file ID for invoice
const documentResult = await client.renderInvoiceDocumentFileId('invoice-uuid-here');

if (documentResult.ok) {
  const documentFileId = documentResult.val.documentFileId;
  console.log('Document file ID:', documentFileId);

  // Now download the actual file
  const fileResult = await client.downloadFile(documentFileId);

  if (fileResult.ok) {
    const pdfBuffer = fileResult.val; // ArrayBuffer
    // Save or send the PDF
    fs.writeFileSync('invoice.pdf', Buffer.from(pdfBuffer));
    console.log('Invoice PDF downloaded successfully.');
  } else {
    console.error('Failed to download invoice file:', fileResult.val.message);
  }
} else {
  console.error('Failed to get document file ID:', documentResult.val.message);
  console.error('Invoice must be finalized before rendering document');
}

```

--------------------------------

### GET /quotations/{id}

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Retrieve a specific quotation by its unique identifier. This endpoint allows you to fetch all details of an existing quotation.

```APIDOC
## GET /quotations/{id}

### Description
Retrieves an existing quotation by its unique ID.

### Method
GET

### Endpoint
/quotations/{id}

### Path Parameters
- **id** (string) - Required - The unique identifier of the quotation to retrieve.

### Response
#### Success Response (200)
- **voucherNumber** (string) - The sequential number of the quotation.
- **address** (object) - The customer's address details.
- **totalPrice** (object) - The total price details of the quotation.
  - **totalGrossAmount** (number) - The total amount including tax.
- **lineItems** (array) - An array of line items included in the quotation.

#### Response Example
```json
{
  "id": "quotation-uuid",
  "voucherNumber": "Q-2023-001",
  "address": {
    "name": "Customer Company GmbH",
    "street": "Kundenstraße 99",
    "city": "München",
    "zip": "80331",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Consulting Service",
      "quantity": 10,
      "unitName": "hours",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 100.00,
        "taxRatePercentage": 19
      }
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 1000.00,
    "totalTaxAmount": 190.00,
    "totalGrossAmount": 1190.00
  },
  "taxConditions": {
    "taxType": "net"
  },
  "title": "Quotation for Consulting Services"
}
```
```

--------------------------------

### Initialize lexoffice-client-js Client

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

This TypeScript snippet demonstrates how to initialize the lexoffice-client-js. It requires an API key obtained from the lexoffice user account. The client is then ready to make API requests.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client(YOUR_LEXOFFICE_API_KEY);
```

--------------------------------

### Initialize lexoffice Client with API Key

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Initializes the lexoffice client using an API key. This client instance is then used to interact with all available lexoffice API methods. All methods return a Result object for safe error handling.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

// Initialize client with API key
const client = new Client('your-lexoffice-api-key-here');

// The client is now ready to use with all available methods
// All methods return Result<T, RequestError> for safe error handling

```

--------------------------------

### GET /creditnotes/{id}

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Retrieve a specific credit note by its unique identifier. This endpoint allows fetching all details of an existing credit note.

```APIDOC
## GET /creditnotes/{id}

### Description
Retrieves an existing credit note by its unique ID.

### Method
GET

### Endpoint
/creditnotes/{id}

### Path Parameters
- **id** (string) - Required - The unique identifier of the credit note to retrieve.

### Response
#### Success Response (200)
- **voucherNumber** (string) - The sequential number of the credit note.
- **address** (object) - The customer's address details.
- **totalPrice** (object) - The total price details of the credit note.
  - **totalGrossAmount** (number) - The total amount including tax.
- **voucherStatus** (string) - The status of the credit note (e.g., 'open', 'paid').

#### Response Example
```json
{
  "id": "credit-note-uuid",
  "voucherNumber": "CN-2023-001",
  "address": {
    "name": "Customer Name",
    "street": "Straße 123",
    "city": "Berlin",
    "zip": "10115",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Refund for returned product",
      "quantity": 1,
      "unitName": "piece",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 50.00,
        "taxRatePercentage": 19
      }
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 50.00,
    "totalTaxAmount": 9.50,
    "totalGrossAmount": 59.50
  },
  "taxConditions": {
    "taxType": "net"
  },
  "title": "Credit Note",
  "voucherStatus": "open"
}
```
```

--------------------------------

### Create Event Subscription with lexoffice Client JS

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Sets up a webhook subscription to receive real-time event notifications from lexoffice. Requires specifying the event type to subscribe to and the callback URL for receiving events. Handles subscription creation failures.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Create event subscription
const subscription = {
  eventType: 'invoice.created',
  callbackUrl: 'https://your-server.com/webhook/lexoffice',
};

const subscriptionResult = await client.createEventSubscription(subscription);

if (subscriptionResult.ok) {
  const created = subscriptionResult.val;
  console.log('Subscription created:', created.subscriptionId);
  console.log('Event type:', created.eventType);
  console.log('Callback URL:', created.callbackUrl);
} else {
  console.error('Subscription failed:', subscriptionResult.val.message);
}
```

--------------------------------

### Create Voucher in lexoffice

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Creates a new voucher in lexoffice with specified line items. Requires the `@elbstack/lexoffice-client-js` library. It takes a voucher object as input and returns the created voucher's ID and version upon success.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Create voucher
const voucher = {
  version: 0,
  voucherDate: '2023-05-15T00:00:00.000+02:00',
  type: 'salesinvoice',
  voucherNumber: 'V-2023-001',
  voucherItems: [{
    amount: 100.00,
    taxAmount: 19.00,
    taxRatePercent: 19,
    categoryId: 'category-uuid-here',
  }],
};

const voucherResult = await client.createVoucher(voucher);

if (voucherResult.ok) {
  const createdVoucher = voucherResult.val;
  console.log('Voucher created:', createdVoucher.id);
  console.log('Version:', createdVoucher.version);
} else {
  console.error('Voucher creation failed:', voucherResult.val.message);
}
```

--------------------------------

### Retrieve Profile Information with TypeScript

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Fetches the lexoffice account's profile information, including organization ID, creation date, connection ID, and available features. An API key is necessary for this request.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Retrieve profile
const profileResult = await client.retrieveProfile();

if (profileResult.ok) {
  const profile = profileResult.val;
  console.log('Company name:', profile.organizationId);
  console.log('Created date:', profile.createdDate);
  console.log('Connection ID:', profile.connectionId);
  console.log('Features:', profile.features);
} else {
  console.error('Profile retrieval failed:', profileResult.val.message);
}
```

--------------------------------

### POST /webhooks/event-subscriptions

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Create a webhook subscription to receive real-time notifications for specific lexoffice events. Requires specifying the event type and the callback URL.

```APIDOC
## POST /webhooks/event-subscriptions

### Description
Creates a webhook subscription to receive real-time notifications for specific lexoffice events.

### Method
POST

### Endpoint
/webhooks/event-subscriptions

### Request Body
- **eventType** (string) - Required - The type of event to subscribe to (e.g., 'invoice.created', 'payment.received').
- **callbackUrl** (string) - Required - The URL where lexoffice will send event notifications.

### Request Example
```json
{
  "eventType": "invoice.created",
  "callbackUrl": "https://your-server.com/webhook/lexoffice"
}
```

### Response
#### Success Response (200)
- **subscriptionId** (string) - The unique identifier of the created subscription.
- **eventType** (string) - The type of event subscribed to.
- **callbackUrl** (string) - The configured callback URL.

#### Response Example
```json
{
  "subscriptionId": "sub-uuid-12345",
  "eventType": "invoice.created",
  "callbackUrl": "https://your-server.com/webhook/lexoffice"
}
```
```

--------------------------------

### Download File from lexoffice

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Downloads a file from lexoffice using its document file ID. Requires the `@elbstack/lexoffice-client-js` library and `fs`. It accepts the document file ID and an optional render type, returning the file content as an ArrayBuffer.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';
import fs from 'fs';

const client = new Client('your-api-key');

// Download file with optional render type
const downloadResult = await client.downloadFile('document-file-id-here', {
  renderType: 'pdf', // or 'original'
});

if (downloadResult.ok) {
  const fileBuffer = downloadResult.val; // ArrayBuffer

  // Save to disk
  fs.writeFileSync('downloaded-file.pdf', Buffer.from(fileBuffer));
  console.log('File downloaded successfully');
} else {
  const error = downloadResult.val;
  console.error('Download failed:', error.message);
}
```

--------------------------------

### Create Voucher API

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Creates a new voucher in lexoffice, which can include line items and be associated with file attachments.

```APIDOC
## POST /vouchers

### Description
Creates a new voucher with line items and file attachments.

### Method
POST

### Endpoint
/vouchers

### Parameters
#### Request Body
- **version** (integer) - Required - The version of the voucher, usually 0 for creation.
- **voucherDate** (string) - Required - The date of the voucher in ISO 8601 format.
- **type** (string) - Required - The type of voucher (e.g., 'salesinvoice').
- **voucherNumber** (string) - Required - The unique number for the voucher.
- **voucherItems** (array) - Required - An array of voucher item objects.
  - **amount** (number) - Required - The amount of the item.
  - **taxAmount** (number) - Required - The tax amount for the item.
  - **taxRatePercent** (number) - Required - The tax rate percentage.
  - **categoryId** (string) - Required - The ID of the category for the item.

### Request Example
```json
{
  "version": 0,
  "voucherDate": "2023-05-15T00:00:00.000+02:00",
  "type": "salesinvoice",
  "voucherNumber": "V-2023-001",
  "voucherItems": [
    {
      "amount": 100.00,
      "taxAmount": 19.00,
      "taxRatePercent": 19,
      "categoryId": "category-uuid-here"
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created voucher.
- **version** (integer) - The current version of the created voucher.

#### Response Example
```json
{
  "id": "voucher-uuid-here",
  "version": 0
}
```
```

--------------------------------

### Order Confirmation API

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Manages order confirmations, including creation, retrieval, and rendering document files.

```APIDOC
## Order Confirmation API

### Description
Manages order confirmations, including creation, retrieval, and rendering document files.

### Methods

- **createOrderConfirmation**
  - **Method**: POST (assumed)
  - **Endpoint**: /order-confirmations
  - **Description**: Creates a new order confirmation.
  - **Request Body**: `OrderConfirmation`

- **retrieveOrderConfirmation**
  - **Method**: GET (assumed)
  - **Endpoint**: /order-confirmations/{id}
  - **Description**: Retrieves a specific order confirmation by its ID.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the order confirmation.

- **renderOrderConfirmationDocumentFileId**
  - **Method**: GET (assumed)
  - **Endpoint**: /order-confirmations/{id}/document
  - **Description**: Renders the document file for a specific order confirmation.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the order confirmation.
```

--------------------------------

### Voucher API

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Handles the creation, retrieval, updating, filtering, and file uploads for vouchers.

```APIDOC
## Voucher API

### Description
Handles the creation, retrieval, updating, filtering, and file uploads for vouchers.

### Methods

- **createVoucher**
  - **Method**: POST (assumed)
  - **Endpoint**: /vouchers
  - **Description**: Creates a new voucher.
  - **Request Body**: `CreateVoucher`

- **retrieveVoucher**
  - **Method**: GET (assumed)
  - **Endpoint**: /vouchers/{id}
  - **Description**: Retrieves a specific voucher by its ID.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the voucher.

- **updateVoucher**
  - **Method**: PUT (assumed)
  - **Endpoint**: /vouchers/{id}
  - **Description**: Updates an existing voucher.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the voucher.
  - **Request Body**: `CreateVoucher`
  - **Side Note**: The 'version' property is required for updates. Retrieve the voucher first to get the current version.

- **filterVoucher**
  - **Method**: GET (assumed)
  - **Endpoint**: /vouchers/filter
  - **Description**: Filters vouchers based on the voucher number.
  - **Request Body**: `VoucherNumber`

- **uploadFileToVoucher**
  - **Method**: POST (assumed)
  - **Endpoint**: /vouchers/{id}/file
  - **Description**: Uploads a file to a specific voucher.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the voucher.
  - **Request Body**: `FormData`
```

--------------------------------

### Manage Order Confirmations

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

API endpoints for creating, retrieving, and rendering order confirmations. Rendering document files is only possible for order confirmations not in 'draft' status.

```typescript
createOrderConfirmation(orderConfirmation: OrderConfirmation): Promise<Result<OrderConfirmationResponse, RequestError>>
retrieveOrderConfirmation(id: string): Promise<Result<OrderConfirmationRetrieveResponse, RequestError>>
renderOrderConfirmationDocumentFileId(id: string): Promise<Result<DocumentFileId, RequestError>>
```

--------------------------------

### Profile API

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Provides a method to retrieve the user's profile information.

```APIDOC
## Profile API

### Description
Provides a method to retrieve the user's profile information.

### Method

- **retrieveProfile**
  - **Method**: GET (assumed)
  - **Endpoint**: /profile
  - **Description**: Retrieves the current user's profile information.
```

--------------------------------

### POST /creditnotes

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Create a new credit note, typically used to refund or credit a customer. Similar to quotations, it requires address, line items, and pricing details.

```APIDOC
## POST /creditnotes

### Description
Creates a new credit note to issue a refund or credit to a customer.

### Method
POST

### Endpoint
/creditnotes

### Query Parameters
- **finalize** (boolean) - Optional - If true, the credit note will be finalized upon creation.

### Request Body
- **voucherDate** (string) - Required - The date of the voucher (credit note).
- **address** (object) - Required - The customer's address details.
  - **name** (string) - Required - The name of the customer.
  - **street** (string) - Required - The street address.
  - **city** (string) - Required - The city.
  - **zip** (string) - Required - The zip code.
  - **countryCode** (string) - Required - The country code (e.g., 'DE').
- **lineItems** (array) - Required - An array of items for the credit note.
  - **type** (string) - Required - The type of line item (e.g., 'custom').
  - **name** (string) - Required - The name of the item.
  - **quantity** (number) - Required - The quantity.
  - **unitName** (string) - Required - The unit of measurement.
  - **unitPrice** (object) - Required - The price details for the unit.
    - **currency** (string) - Required - The currency code (e.g., 'EUR').
    - **netAmount** (number) - Required - The net amount per unit.
    - **taxRatePercentage** (number) - Required - The tax rate percentage.
- **totalPrice** (object) - Required - The total price object.
  - **currency** (string) - Required - The currency code.
- **taxConditions** (object) - Required - Tax conditions.
  - **taxType** (string) - Required - The tax type (e.g., 'net').
- **title** (string) - Required - The title of the credit note.
- **introduction** (string) - Optional - An introductory text.

### Request Example
```json
{
  "voucherDate": "2023-06-15T00:00:00.000+02:00",
  "address": {
    "name": "Customer Name",
    "street": "Straße 123",
    "city": "Berlin",
    "zip": "10115",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Refund for returned product",
      "quantity": 1,
      "unitName": "piece",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 50.00,
        "taxRatePercentage": 19
      }
    }
  ],
  "totalPrice": {
    "currency": "EUR"
  },
  "taxConditions": {
    "taxType": "net"
  },
  "title": "Credit Note",
  "introduction": "Credit for returned items"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created credit note.
- **resourceUri** (string) - The URI to access the created credit note.

#### Response Example
```json
{
  "id": "credit-note-uuid",
  "resourceUri": "/creditnotes/credit-note-uuid"
}
```
```

--------------------------------

### File API

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Handles file uploads and downloads.

```APIDOC
## File API

### Description
Handles file uploads and downloads.

### Methods

- **uploadFile**
  - **Method**: POST (assumed)
  - **Endpoint**: /files
  - **Description**: Uploads a file.
  - **Request Body**: `FormData`

- **downloadFile**
  - **Method**: GET (assumed)
  - **Endpoint**: /files/{documentFileId}
  - **Description**: Downloads a file.
  - **Path Parameters**:
    - **documentFileId** (string) - Required - The ID of the document file to download.
  - **Query Parameters**:
    - **optionalParameter** (RenderType) - Optional - Specifies the render type for the download.
```

--------------------------------

### Create Company Contact with Lexoffice Client JS

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Creates a new company contact in lexoffice. Requires an API key for client initialization. The input is a structured object detailing the company's name, tax information, roles, contact persons, email, and addresses. The output confirms the created contact's ID or provides an error message.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Create company contact
const companyContact = {
  version: 0,
  roles: {
    customer: {},
    vendor: {},
  },
  company: {
    name: 'Musterfirma GmbH',
    taxNumber: 'DE123456789',
    vatRegistrationId: 'DE123456789',
    allowTaxFreeInvoices: true,
    contactPersons: [{
      salutation: 'Frau',
      firstName: 'Anna',
      lastName: 'Schmidt',
      emailAddress: 'anna.schmidt@musterfirma.de',
      phoneNumber: '+49 30 98765432',
    }],
  },
  emailAddresses: {
    business: ['info@musterfirma.de'],
  },
  addresses: {
    billing: [{
      street: 'Hauptstraße 1',
      zip: '10115',
      city: 'Berlin',
      countryCode: 'DE',
    }],
  },
};

const contactResult = await client.createContact(companyContact);

if (contactResult.ok) {
  const contact = contactResult.val;
  console.log('Company contact created:', contact.id);
} else {
  console.error('Error:', contactResult.val.message);
}
```

--------------------------------

### Create Person Contact with Lexoffice Client JS

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Creates a new person contact in lexoffice. Requires an API key for client initialization. The input is a structured object representing the person's details, roles, contact information, and addresses. The output is a confirmation of the created contact's ID and version, or an error message.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Create person contact
const personContact = {
  version: 0,
  roles: {
    customer: {},
  },
  person: {
    salutation: 'Herr',
    firstName: 'Max',
    lastName: 'Mustermann',
  },
  emailAddresses: {
    business: ['max.mustermann@example.com'],
  },
  phoneNumbers: {
    business: ['+49 30 12345678'],
  },
  addresses: {
    billing: [{
      street: 'Musterstraße 123',
      zip: '10115',
      city: 'Berlin',
      countryCode: 'DE',
    }],
  },
};

const contactResult = await client.createContact(personContact);

if (contactResult.ok) {
  const contact = contactResult.val;
  console.log('Contact created:', contact.id);
  console.log('Contact version:', contact.version);
} else {
  const error = contactResult.val;
  console.error('Failed to create contact:', error.message);
}
```

--------------------------------

### Manage Credit Notes

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Functions for creating, retrieving, and rendering credit notes. Credit notes can be finalized upon creation. Document rendering is only possible for non-draft credit notes.

```typescript
createCreditNote(creditNote: CreditNoteCreate, optionalFinalized?: OptionalFinalized): Promise<Result<CreditNoteCreateResponse, RequestError>>
retrieveCreditNote(id: string): Promise<Result<CreditNoteRetrieveResponse, RequestError>>
renderCreditNoteDocumentFileId(id: string): Promise<Result<DocumentFileId, RequestError>>
```

--------------------------------

### Manage Quotations

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Provides functions to create, retrieve, and render quotations. Rendering document files is only available for quotations not in 'draft' status. The version property is required for updates.

```typescript
createQuotation(quotation: QuotationCreate, optionalFilter?: OptionalFinalized): Promise<Result<QuotationCreate, RequestError>>
retrieveQuotation(id: string): Promise<Result<Partial<Quotation>, RequestError>>
renderQuotationDocumentFileId(id: string): Promise<Result<DocumentFileId, RequestError>>
```

--------------------------------

### Retrieve Profile

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Fetches the user's profile information. The result is returned within a Promise that resolves to a Result type, indicating success with Profile data or a RequestError.

```typescript
retrieveProfile(): Promise<Result<Profile, RequestError>>
```

--------------------------------

### Create Credit Note with lexoffice Client JS

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Generates a new credit note for a customer using the lexoffice client. Requires customer details, line items for the credit, and pricing. The credit note can be finalized upon creation. Handles creation failures.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Create credit note
const creditNote = {
  voucherDate: '2023-06-15T00:00:00.000+02:00',
  address: {
    name: 'Customer Name',
    street: 'Straße 123',
    city: 'Berlin',
    zip: '10115',
    countryCode: 'DE',
  },
  lineItems: [{
    type: 'custom',
    name: 'Refund for returned product',
    quantity: 1,
    unitName: 'piece',
    unitPrice: {
      currency: 'EUR',
      netAmount: 50.00,
      taxRatePercentage: 19,
    },
  }],
  totalPrice: {
    currency: 'EUR',
  },
  taxConditions: {
    taxType: 'net',
  },
  title: 'Credit Note',
  introduction: 'Credit for returned items',
};

const creditNoteResult = await client.createCreditNote(creditNote, { finalize: true });

if (creditNoteResult.ok) {
  const createdCreditNote = creditNoteResult.val;
  console.log('Credit note created:', createdCreditNote.id);
  console.log('Resource URI:', createdCreditNote.resourceUri);
} else {
  console.error('Creation failed:', creditNoteResult.val.message);
}
```

--------------------------------

### Invoice API

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Manages invoices, including creation, retrieval, and rendering document files.

```APIDOC
## Invoice API

### Description
Manages invoices, including creation, retrieval, and rendering document files.

### Methods

- **createInvoice**
  - **Method**: POST (assumed)
  - **Endpoint**: /invoices
  - **Description**: Creates a new invoice.
  - **Request Body**: `InvoiceCreate | XRechnung`
  - **Query Parameters**:
    - **optionalFinalized** (OptionalFinalized) - Optional - Whether to finalize the invoice upon creation.

- **retrieveInvoice**
  - **Method**: GET (assumed)
  - **Endpoint**: /invoices/{id}
  - **Description**: Retrieves a specific invoice by its ID.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the invoice.

- **renderInvoiceDocumentFileId**
  - **Method**: GET (assumed)
  - **Endpoint**: /invoices/{id}/document
  - **Description**: Renders the document file for a specific invoice.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the invoice.
```

--------------------------------

### POST /files/upload

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Uploads a file to the system. The file can be of various types, such as a voucher.

```APIDOC
## POST /files/upload

### Description
Uploads a file to the system. The file can be of various types, such as a voucher.

### Method
POST

### Endpoint
/files/upload

### Parameters
#### Request Body
- **file** (File) - Required - The file to be uploaded.
- **type** (string) - Required - The type of the file (e.g., 'voucher').

### Request Example
```json
{
  "file": "<binary file data>",
  "type": "voucher"
}
```

### Response
#### Success Response (200)
- **uploadedFile** (object) - Information about the uploaded file.

#### Response Example
```json
{
  "uploadedFile": {
    // ... file details ...
  }
}
```
```

--------------------------------

### Manage Vouchers

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Comprehensive voucher management functions including creation, retrieval, update, filtering, and file uploads. Updates require the 'version' property. File uploads are supported for specific voucher types.

```typescript
createVoucher(voucher: CreateVoucher): Promise<Result<VoucherCreateResponse, RequestError>>
retrieveVoucher(id: string): Promise<Result<Partial<Voucher>, RequestError>>
updateVoucher(id: string, voucher: CreateVoucher): Promise<Result<VoucherCreateResponse, RequestError>>
filterVoucher(voucherNumber: VoucherNumber): Promise<Result<Partial<Vouchers>, RequestError>>
uploadFileToVoucher(data: FormData, id: string): Promise<Result<FileResponse, RequestError>>
```

--------------------------------

### Credit Note API

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Manages credit notes, including creation, retrieval, and rendering document files.

```APIDOC
## Credit Note API

### Description
Manages credit notes, including creation, retrieval, and rendering document files.

### Methods

- **createCreditNote**
  - **Method**: POST (assumed)
  - **Endpoint**: /credit-notes
  - **Description**: Creates a new credit note.
  - **Request Body**: `CreditNoteCreate`
  - **Query Parameters**:
    - **optionalFinalized** (OptionalFinalized) - Optional - Whether to finalize the credit note upon creation.

- **retrieveCreditNote**
  - **Method**: GET (assumed)
  - **Endpoint**: /credit-notes/{id}
  - **Description**: Retrieves a specific credit note by its ID.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the credit note.

- **renderCreditNoteDocumentFileId**
  - **Method**: GET (assumed)
  - **Endpoint**: /credit-notes/{id}/document
  - **Description**: Renders the document file for a specific credit note.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the credit note.
```

--------------------------------

### Event Subscription API

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Manages event subscriptions for receiving real-time notifications.

```APIDOC
## Event Subscription API

### Description
Manages event subscriptions for receiving real-time notifications.

### Methods

- **createEventSubscription**
  - **Method**: POST (assumed)
  - **Endpoint**: /event-subscriptions
  - **Description**: Creates a new event subscription.
  - **Request Body**: `EventSubscriptionCreate`

- **retrieveEventSubscription**
  - **Method**: GET (assumed)
  - **Endpoint**: /event-subscriptions/{id}
  - **Description**: Retrieves a specific event subscription by its ID.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the event subscription.

- **retrieveAllEventSubscriptions**
  - **Method**: GET (assumed)
  - **Endpoint**: /event-subscriptions
  - **Description**: Retrieves all existing event subscriptions.

- **deleteEventSubscription**
  - **Method**: DELETE (assumed)
  - **Endpoint**: /event-subscriptions/{id}
  - **Description**: Deletes a specific event subscription by its ID.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the event subscription.
```

--------------------------------

### Manage Invoices

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Functions for creating, retrieving, and rendering invoice documents. Invoices can be created from InvoiceCreate objects or XRechnung format. Document rendering is restricted to non-draft invoices.

```typescript
createInvoice(invoice: InvoiceCreate | XRechnung, optionalFinalized?: OptionalFinalized): Promise<Result<InvoiceCreateResponse, RequestError>>
retrieveInvoice(id: string): Promise<Result<InvoiceRetrieveResponse, RequestError>>
renderInvoiceDocumentFileId(id: string): Promise<Result<DocumentFileId, RequestError>>
```

--------------------------------

### POST /invoices

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Creates a new invoice with the provided details. The invoice can be finalized upon creation.

```APIDOC
## POST /invoices

### Description
Creates a new invoice with the provided details. The invoice can be finalized upon creation.

### Method
POST

### Endpoint
/invoices

### Parameters
#### Query Parameters
- **finalize** (boolean) - Optional - If set to true, the invoice will be finalized after creation.

#### Request Body
- **voucherDate** (string) - Required - The date the voucher was issued.
- **address** (object) - Required - The address details for the invoice.
  - **name** (string) - Required - The name of the recipient.
  - **supplement** (string) - Optional - Additional address information.
  - **street** (string) - Required - The street name and number.
  - **city** (string) - Required - The city name.
  - **zip** (string) - Required - The postal code.
  - **countryCode** (string) - Required - The ISO country code.
- **lineItems** (array) - Required - An array of items included in the invoice.
  - **type** (string) - Required - The type of line item (e.g., 'custom', 'text').
  - **name** (string) - Required - The name or title of the item.
  - **quantity** (number) - Optional - The quantity of the item.
  - **unitName** (string) - Optional - The unit of measurement for the quantity.
  - **unitPrice** (object) - Optional - The price details for the unit.
    - **currency** (string) - Required - The currency code (e.g., 'EUR').
    - **netAmount** (number) - Required - The net amount per unit.
    - **taxRatePercentage** (number) - Required - The tax rate percentage.
  - **discountPercentage** (number) - Optional - The discount percentage applied to the item.
  - **description** (string) - Optional - A detailed description of the item.
- **totalPrice** (object) - Required - The total price of the invoice.
  - **currency** (string) - Required - The currency code.
- **taxConditions** (object) - Required - Tax-related conditions.
  - **taxType** (string) - Required - The type of tax (e.g., 'net').
- **shippingConditions** (object) - Optional - Shipping details.
  - **shippingDate** (string) - Required - The date of shipping.
  - **shippingType** (string) - Required - The type of shipping.
- **title** (string) - Required - The title of the invoice.
- **introduction** (string) - Optional - An introductory message for the invoice.
- **remark** (string) - Optional - A remark or note for the invoice.

### Request Example
```json
{
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "address": {
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0
    },
    {
      "type": "text",
      "name": "Strukturieren Sie Ihre Belege durch Text-Elemente.",
      "description": "Das hilft beim Verständnis"
    }
  ],
  "totalPrice": {
    "currency": "EUR"
  },
  "taxConditions": {
    "taxType": "net"
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingType": "delivery"
  },
  "title": "Rechnung",
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf"
}
```

### Response
#### Success Response (200)
- **invoice** (object) - The created invoice object.

#### Response Example
```json
{
  "invoice": {
    // ... invoice details ...
  }
}
```
```

--------------------------------

### Quotation API

Source: https://github.com/elbstack/lexoffice-client-js/blob/main/README.md

Manages quotations, including creation, retrieval, and rendering document files.

```APIDOC
## Quotation API

### Description
Manages quotations, including creation, retrieval, and rendering document files.

### Methods

- **createQuotation**
  - **Method**: POST (assumed)
  - **Endpoint**: /quotations
  - **Description**: Creates a new quotation.
  - **Request Body**: `QuotationCreate`
  - **Query Parameters**:
    - **optionalFilter** (OptionalFinalized) - Optional - Specifies if the quotation should be finalized upon creation.

- **retrieveQuotation**
  - **Method**: GET (assumed)
  - **Endpoint**: /quotations/{id}
  - **Description**: Retrieves a specific quotation by its ID.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the quotation.

- **renderQuotationDocumentFileId**
  - **Method**: GET (assumed)
  - **Endpoint**: /quotations/{id}/document
  - **Description**: Renders the document file for a specific quotation.
  - **Path Parameters**:
    - **id** (string) - Required - The unique identifier of the quotation.
```

--------------------------------

### Create Quotation with lexoffice Client JS

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Creates a new sales quotation for a customer using the lexoffice client. Requires customer details, line items, and pricing information. The quotation can be finalized upon creation.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Create quotation
const quotation = {
  voucherDate: '2023-06-01T00:00:00.000+02:00',
  address: {
    name: 'Customer Company GmbH',
    street: 'Kundenstraße 99',
    city: 'München',
    zip: '80331',
    countryCode: 'DE',
  },
  lineItems: [{
    type: 'custom',
    name: 'Consulting Service',
    description: 'Software architecture consulting',
    quantity: 10,
    unitName: 'hours',
    unitPrice: {
      currency: 'EUR',
      netAmount: 100.00,
      taxRatePercentage: 19,
    },
  }],
  totalPrice: {
    currency: 'EUR',
  },
  taxConditions: {
    taxType: 'net',
  },
  title: 'Quotation for Consulting Services',
  introduction: 'Thank you for your interest. Please find our quotation below.',
  remark: 'Valid for 30 days',
};

const quotationResult = await client.createQuotation(quotation, { finalize: true });

if (quotationResult.ok) {
  const createdQuotation = quotationResult.val;
  console.log('Quotation created:', createdQuotation.id);
} else {
  console.error('Failed:', quotationResult.val.message);
}
```

--------------------------------

### Upload File to Voucher API

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Attaches a previously uploaded file to a specific voucher in lexoffice.

```APIDOC
## POST /vouchers/{voucherId}/attachments

### Description
Attaches a file to an existing voucher.

### Method
POST

### Endpoint
/vouchers/{voucherId}/attachments

### Parameters
#### Path Parameters
- **voucherId** (string) - Required - The unique identifier of the voucher to attach the file to.

#### Request Body
- **file** (FormData) - Required - The file to attach. Use `fs.createReadStream` for file input.

### Request Example
```json
{
  "file": "./receipt.pdf"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the attachment.
- **documentFileId** (string) - The identifier for the document file that was attached.

#### Response Example
```json
{
  "id": "attachment-uuid-here",
  "documentFileId": "document-file-uuid-here"
}
```
```

--------------------------------

### Retrieve All Event Subscriptions with TypeScript

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Lists all active event subscriptions using the lexoffice client. It retrieves subscription details like ID, event type, and callback URL. Requires an API key for authentication.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Retrieve all subscriptions
const subscriptionsResult = await client.retrieveAllEventSubscriptions();

if (subscriptionsResult.ok) {
  const subscriptions = subscriptionsResult.val;
  console.log('Total subscriptions:', subscriptions.content?.length);

  subscriptions.content?.forEach(sub => {
    console.log('Subscription ID:', sub.subscriptionId);
    console.log('Event type:', sub.eventType);
    console.log('Callback URL:', sub.callbackUrl);
  });
} else {
  console.error('Retrieval failed:', subscriptionsResult.val.message);
}
```

--------------------------------

### Retrieve Credit Note with lexoffice Client JS

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Fetches an existing credit note from lexoffice using its unique identifier. Provides details like voucher number, total amount, and status. Includes error handling for non-existent credit notes.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Retrieve credit note
const creditNoteResult = await client.retrieveCreditNote('credit-note-uuid-here');

if (creditNoteResult.ok) {
  const creditNote = creditNoteResult.val;
  console.log('Credit note number:', creditNote.voucherNumber);
  console.log('Total amount:', creditNote.totalPrice?.totalGrossAmount);
  console.log('Status:', creditNote.voucherStatus);
} else {
  console.error('Not found:', creditNoteResult.val.message);
}
```

--------------------------------

### Download File API

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Downloads a file from lexoffice using its document file ID. Supports rendering the file as PDF or returning the original format.

```APIDOC
## GET /files/{documentFileId}

### Description
Downloads a file by its document file ID.

### Method
GET

### Endpoint
/files/{documentFileId}

### Parameters
#### Path Parameters
- **documentFileId** (string) - Required - The unique identifier of the document file to download.

#### Query Parameters
- **renderType** (string) - Optional - The desired format for the downloaded file. Accepts 'pdf' or 'original'. Defaults to original.

### Request Example
```json
{
  "renderType": "pdf"
}
```

### Response
#### Success Response (200)
- **fileBuffer** (ArrayBuffer) - The content of the file as an ArrayBuffer.

#### Response Example
(Binary file content - example omitted for brevity)
```

--------------------------------

### Retrieve Voucher from lexoffice

Source: https://context7.com/elbstack/lexoffice-client-js/llms.txt

Retrieves an existing voucher from lexoffice by its unique ID. Requires the `@elbstack/lexoffice-client-js` library. It takes the voucher ID as input and returns the voucher details if found, or an error message.

```typescript
import { Client } from '@elbstack/lexoffice-client-js';

const client = new Client('your-api-key');

// Retrieve voucher
const voucherResult = await client.retrieveVoucher('voucher-uuid-here');

if (voucherResult.ok) {
  const voucher = voucherResult.val;
  console.log('Voucher number:', voucher.voucherNumber);
  console.log('Voucher type:', voucher.type);
  console.log('Total items:', voucher.voucherItems?.length);

  voucher.voucherItems?.forEach(item => {
    console.log('Item amount:', item.amount);
    console.log('Tax rate:', item.taxRatePercent + '%');
  });
} else {
  console.error('Voucher not found:', voucherResult.val.message);
}
```