### Install and Configure Billomat Symfony Bundle

Source: https://context7.com/phobetor/billomat/llms.txt

Install the Billomat Symfony bundle using Composer and configure API credentials in app/config/config.yml. Optional API app ID and secret can also be provided.

```bash
# Install the Symfony bundle
composer require phobetor/billomat-bundle

# Configure in app/config/config.yml
phobetor_billomat:
    billomat_id: "%billomat_id%"
    api_key: "%billomat_api_key%"
    api_app_id: "%billomat_app_id%"        # Optional
    api_app_secret: "%billomat_app_secret%" # Optional

```

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

### Install Billomat PHP Client via Composer

Source: https://github.com/phobetor/billomat/blob/master/README.md

Use this command to add the Billomat client library to your project dependencies.

```sh
php composer.phar require phobetor/billomat:~1.5
```

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

### Get a Client by ID

Source: https://github.com/phobetor/billomat/blob/master/README.md

Retrieve a specific client from Billomat using its unique ID. Ensure the client object is properly initialized.

```php
// Get the client with id 133713371337
$client = $billomat->getClient(array(
    'id' => 133713371337
));
```

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

### GET /invoices

Source: https://context7.com/phobetor/billomat/llms.txt

Retrieve a list of invoices with support for filtering by client, status, date range, and payment type.

```APIDOC
## GET /invoices

### Description
Retrieve a list of invoices with comprehensive filtering options.

### Method
GET

### Endpoint
/invoices

### Parameters
#### Query Parameters
- **per_page** (integer) - Optional - Number of results per page
- **page** (integer) - Optional - Page number
- **client_id** (integer) - Optional - Filter by client ID
- **status** (string) - Optional - Comma-separated list of statuses (e.g., DRAFT,OPEN,OVERDUE)
- **from** (string) - Optional - Start date (YYYY-MM-DD)
- **to** (string) - Optional - End date (YYYY-MM-DD)
- **payment_type** (string) - Optional - Filter by payment type
- **tags** (string) - Optional - Filter by tags
- **group_by** (string) - Optional - Group results by client, status, day, week, month, or year
- **order_by** (string) - Optional - Sort order (e.g., date DESC)
```

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

### Initialize Billomat Client

Source: https://context7.com/phobetor/billomat/llms.txt

Instantiate the client with credentials and configure rate limit handling.

```php
<?php
use Phobetor\\Client\\BillomatClient;

// Basic authentication with API key only
$billomat = new BillomatClient('my-billomat-id', 'my-api-key');

// Recommended: Authentication with registered app (higher rate limits)
$billomat = new BillomatClient(
    'my-billomat-id',
    'my-api-key',
    'my-app-id',
    'my-app-secret'
);

// With automatic rate limit handling for CLI/async processes
$billomat = new BillomatClient(
    'my-billomat-id',
    'my-api-key',
    'my-app-id',
    'my-app-secret',
    true  // Enable automatic waiting for rate limit reset
);

// Or enable rate limit handling after construction
$billomat->setDoWaitForRateLimitReset(true);

// Check current rate limit status
$remaining = $billomat->getRateLimitRemaining();  // Returns remaining requests
$resetTime = $billomat->getRateLimitReset();      // Returns UTC timestamp of reset
```

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

### Instantiate Billomat Client

Source: https://github.com/phobetor/billomat/blob/master/README.md

Basic instantiation of the Billomat client requires your API ID and key. For apps with higher rate limits, include app ID and secret.

```php
use Phobetor\Billomat\Client\BillomatClient;

$billomat = new BillomatClient('my-id', 'my-api-key');
```

```php
use Phobetor\Billomat\Client\BillomatClient;

$billomat = new BillomatClient('my-id', 'my-api-key', 'my-api-app-id', 'my-api-app-secret');
```

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

### Manage Credit Notes with PHP

Source: https://context7.com/phobetor/billomat/llms.txt

Handle credit note creation, completion, PDF generation, and email distribution.

```php
<?php
// List credit notes
$creditNotes = $billomat->getCreditNotes(array(
    'client_id' => 133713371337,
    'status' => 'OPEN',
    'from' => '2024-01-01',
    'to' => '2024-12-31',
    'per_page' => 50
));

// Get a specific credit note
$creditNote = $billomat->getCreditNote(array('id' => 54321));

// Create credit note (optionally linked to an invoice)
$newCreditNote = $billomat->createCreditNote(array(
    'credit-note' => array(
        'client_id' => 133713371337,
        'invoice_id' => 98765,  // Optional: reference original invoice
        'number_pre' => 'CN-',
        'date' => '2024-03-20',
        'title' => 'Credit Note for Invoice INV-98765',
        'intro' => 'We hereby credit you the following amount:',
        'note' => 'Refund for returned items.',
        'currency_code' => 'EUR',
        'net_gross' => 'NET',
        'credit-note-items' => array(
            'credit-note-item' => array(
                array(
                    'quantity' => 2,
                    'unit' => 'pieces',
                    'unit_price' => 100.00,
                    'title' => 'Returned product refund',
                    'tax_rate' => 19.0
                )
            )
        )
    )
));

// Update credit note
$billomat->updateCreditNote(array(
    'id' => 54321,
    'credit-note' => array(
        'note' => 'Updated note'
    )
));

// Complete credit note
$billomat->completeCreditNote(array(
    'id' => 54321,
    'complete' => array('template_id' => 456)
));

// Get credit note PDF
$response = $billomat->getCreditNotePdf(array(
    'id' => 54321,
    'format' => 'pdf'
));
file_put_contents('credit-note.pdf', (string)$response->getBody());

// Send credit note via email
$billomat->sendCreditNoteEmail(array(
    'id' => 54321,
    'email' => array(
        'recipients' => array('to' => 'customer@acme.com'),
        'subject' => 'Credit Note {credit_note_number}',
        'body' => 'Please find your credit note attached.'
    )
));

// Upload digital signature
$billomat->signCreditNote(array(
    'id' => 54321,
    'signature' => array(
        'base64file' => base64_encode(file_get_contents('signed-credit-note.pdf'))
    )
));

// Delete credit note
$billomat->deleteCreditNote(array('id' => 54321));
```

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

### Create a New Client

Source: https://github.com/phobetor/billomat/blob/master/README.md

Create a new client in Billomat by providing the necessary client details, including number and name. This method follows the CRUD schema.

```php
// Create a new client
$client = $billomat->createClient(array(
    'client' => array(
        'number' => 424242424242,
        'name' => 'client-name'
    )
));
```

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

### Manage Tax Settings

Source: https://context7.com/phobetor/billomat/llms.txt

Configure tax rates and tax-free country settings. This includes listing, retrieving, creating, updating, and deleting tax rates, as well as managing country-specific tax exemptions.

```php
<?php
// List all taxes
$taxes = $billomat->getTaxes(array('per_page' => 100));

// Get specific tax
$tax = $billomat->getTax(array('id' => 1));

// Create a tax rate
$newTax = $billomat->createTax(array(
    'tax' => array(
        'name' => 'Reduced VAT',
        'rate' => 7.0,
        'is_default' => 0  // 0 or 1
    )
));

// Update tax
$billomat->updateTax(array(
    'id' => 1,
    'tax' => array('rate' => 19.0)
));

// Delete tax
$billomat->deleteTax(array('id' => 1));

// Manage tax-free countries
$countryTaxes = $billomat->getCountryTaxes(array('per_page' => 100));
$countryTax = $billomat->getCountryTax(array('id' => 10));

$billomat->createCountryTax(array(
    'country-tax' => array('country_code' => 'CH')  // ISO 3166 Alpha-2
));

$billomat->updateCountryTax(array(
    'id' => 10,
    'country-tax' => array('country_code' => 'US')
));

$billomat->deleteCountryTax(array('id' => 10));
```

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

### Migrate BillomatClient Constructor

Source: https://github.com/phobetor/billomat/blob/master/UPGRADE-2.0.0.md

Updates the constructor instantiation to accommodate the new signature requirements for registered and unregistered applications.

```php
// BillomatClient::LATEST_API_VERSION needed to be set explicitly
// when the fourth parameter is in use
new BillomatClient('billomat-id', 'api-key', BillomatClient::LATEST_API_VERSION, true);
```

```php
// without a registered application
new BillomatClient('billomat-id', 'api-key', null, null, true);
// with a registered application
new BillomatClient('billomat-id', 'api-key', 'app-id', 'app-secret', true);
```

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

### Manage Client Properties

Source: https://context7.com/phobetor/billomat/llms.txt

Create, read, update, and delete custom properties for clients. These properties can be of type TEXTFIELD and have a default value.

```php
// Client Properties
$clientProps = $billomat->getClientProperties(array('per_page' => 100));

$billomat->createClientProperty(array(
    'client-property' => array(
        'name' => 'Customer Tier',
        'type' => 'TEXTFIELD',
        'default_value' => 'Standard'
    )
));

$billomat->updateClientProperty(array(
    'id' => 2,
    'client-property' => array('name' => 'Account Tier')
));

$billomat->deleteClientProperty(array('id' => 2));
```

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

### Manage Articles and Properties via Billomat API

Source: https://context7.com/phobetor/billomat/llms.txt

Provides methods for listing, creating, updating, and deleting articles, along with managing custom property values for specific articles.

```php
<?php
// List all articles with filtering
$articles = $billomat->getArticles(array(
    'per_page' => 100,
    'page' => 1,
    'article_number' => 'ART-001',
    'title' => 'Consulting',
    'currency_code' => 'EUR',
    'tags' => 'service,hourly'
));

// Get a specific article
$article = $billomat->getArticle(array('id' => 42));

// Create an article with multiple price groups
$newArticle = $billomat->createArticle(array(
    'article' => array(
        'number_pre' => 'ART-',
        'number' => 100,
        'title' => 'Web Development Services',
        'description' => 'Professional web development hourly rate',
        'sales_price' => 150.00,       // Default price
        'sales_price2' => 135.00,      // Price for pricegroup 2
        'sales_price3' => 120.00,      // Price for pricegroup 3
        'currency_code' => 'EUR',
        'unit_id' => 1,                // Reference to unit
        'tax_id' => 1                  // Reference to tax rate
    )
));

// Update an article
$billomat->updateArticle(array(
    'id' => 42,
    'article' => array(
        'sales_price' => 175.00,
        'description' => 'Updated description'
    )
));

// Delete an article
$billomat->deleteArticle(array('id' => 42));

// Manage article property values
$articleProps = $billomat->getArticlePropertyValues(array('article_id' => 42));

$billomat->setArticlePropertyValue(array(
    'article-property-value' => array(
        'article_id' => 42,
        'article_property_id' => 10,
        'value' => 'Custom attribute value'
    )
));
```

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

### Manage Reminder Texts (Dunning Levels)

Source: https://context7.com/phobetor/billomat/llms.txt

Create, read, update, and delete reminder texts for dunning levels. Includes settings for subject, body, and charges associated with late payments.

```php
// Reminder Texts (Dunning Levels)
$reminderTexts = $billomat->getReminderTexts(array('per_page' => 100));
$reminderText = $billomat->getReminderText(array('id' => 1));

$billomat->createReminderText(array(
    'reminder-text' => array(
        'sorting' => 1,
        'name' => 'First Reminder',
        'subject' => 'Payment Reminder - Invoice {invoice_number}',
        'header' => 'This is a friendly reminder that the following invoice is overdue:',
        'footer' => 'Please process payment at your earliest convenience.',
        'charge_name' => 'Late Fee',
        'charge_description' => 'Administrative fee for overdue payment',
        'charge_amount' => 10.00
    )
));

$billomat->updateReminderText(array(
    'id' => 1,
    'reminder-text' => array('charge_amount' => 15.00)
));

$billomat->deleteReminderText(array('id' => 1));
```

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

### Manage Article Properties

Source: https://context7.com/phobetor/billomat/llms.txt

Create, read, update, and delete custom properties for articles. Supported types include TEXTFIELD and TEXTAREA. Use is_nvl to set a default value if none is provided.

```php
<?php
// Article Properties
$articleProps = $billomat->getArticleProperties(array('per_page' => 100));
$articleProp = $billomat->getArticleProperty(array('id' => 1));

$billomat->createArticleProperty(array(
    'article-property' => array(
        'name' => 'SKU',
        'type' => 'TEXTFIELD',  // TEXTFIELD, TEXTAREA, CHECKBOX
        'default_value' => '',
        'is_nvl' => 1  // Use default if no value set
    )
));

$billomat->updateArticleProperty(array(
    'id' => 1,
    'article-property' => array('name' => 'Stock Keeping Unit')
));

$billomat->deleteArticleProperty(array('id' => 1));
```

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

### User Property Methods

Source: https://github.com/phobetor/billomat/blob/master/README.md

Methods for managing user properties within the Billomat system.

```APIDOC
## User Property Methods

### Description
Manage custom user properties via the Billomat API.

### Methods
- getUserProperties(array $args)
- getUserProperty(array $args)
- createUserProperty(array $args)
- updateUserProperty(array $args)
- deleteUserProperty(array $args)
```

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

### Manage User Property Values

Source: https://context7.com/phobetor/billomat/llms.txt

Set and retrieve custom property values for users. Requires user ID, user property ID, and the value itself.

```php
// User Property Values
$userPropValues = $billomat->getUserPropertyValues(array('user_id' => 1));
$userPropValue = $billomat->getUserPropertyValue(array('id' => 100));

$billomat->setUserPropertyValue(array(
    'user-property-value' => array(
        'user_id' => 1,
        'user_property_id' => 3,
        'value' => 'Engineering'
    )
));
```

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

### Manage Billomat Document Templates

Source: https://context7.com/phobetor/billomat/llms.txt

This section covers operations for listing, retrieving, creating, updating, and deleting document templates. Templates can be filtered by type and preview images can be generated.

```php
<?php
// List all templates filtered by type
$templates = $billomat->getTemplates(array(
    'type' => 'INVOICE',  // INVOICE, OFFER, CONFIRMATION, REMINDER, DELIVERY_NOTE, CREDIT_NOTE
    'per_page' => 50
));

// Get a specific template
$template = $billomat->getTemplate(array('id' => 123));

// Get template preview image
$response = $billomat->getTemplatePreview(array(
    'id' => 123,
    'format' => 'png'  // png, gif, jpg
));
file_put_contents('template-preview.png', (string)$response->getBody());

// Create a new template
$newTemplate = $billomat->createTemplate(array(
    'template' => array(
        'name' => 'Invoice Template 2024',
        'type' => 'INVOICE',
        'format' => 'docx',  // doc, docx, rtf
        'base64file' => base64_encode(file_get_contents('invoice-template.docx'))
    )
));

// Update a template
$billomat->updateTemplate(array(
    'id' => 123,
    'template' => array(
        'name' => 'Invoice Template 2024 - Updated',
        'base64file' => base64_encode(file_get_contents('invoice-template-v2.docx'))
    )
));

// Delete a template
$billomat->deleteTemplate(array('id' => 123));
```

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

### Reminder Text Methods

Source: https://github.com/phobetor/billomat/blob/master/README.md

Methods for managing reminder text templates.

```APIDOC
## Reminder Text Methods

### Description
Manage text templates used for payment reminders.

### Methods
- getReminderTexts(array $args)
- getReminderText(array $args)
- createReminderText(array $args)
- updateReminderText(array $args)
- deleteReminderText(array $args)
```

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

### Manage User Properties

Source: https://context7.com/phobetor/billomat/llms.txt

Create, read, update, and delete custom properties for users. These properties can be of type TEXTFIELD and have a default value.

```php
// User Properties
$userProps = $billomat->getUserProperties(array('per_page' => 100));

$billomat->createUserProperty(array(
    'user-property' => array(
        'name' => 'Department',
        'type' => 'TEXTFIELD'
    )
));

$billomat->updateUserProperty(array(
    'id' => 3,
    'user-property' => array('default_value' => 'Sales')
));

$billomat->deleteUserProperty(array('id' => 3));
```

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

### Configuring Automatic Rate Limit Waiting

Source: https://github.com/phobetor/billomat/blob/master/README.md

Methods to enable automatic waiting for rate limit resets, suitable for CLI or asynchronous processes.

```php
use Phobetor\Billomat\Client\BillomatClient;

// setting the fifth parameter to true enables waiting for rate limit
$billomat = new BillomatClient('my-id', 'my-api-key', 'my-api-app-id', 'my-api-app-secret', true);
```

```php
$billomat->setDoWaitForRateLimitReset(true);
```

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

### Manage Invoice Payments with PHP

Source: https://context7.com/phobetor/billomat/llms.txt

Record and retrieve payment information for invoices, including support for various payment types.

```php
<?php
// Get all payments with filtering
$payments = $billomat->getInvoicePayments(array(
    'invoice_id' => 98765,
    'from' => '2024-01-01',
    'to' => '2024-12-31',
    'type' => 'BANK_TRANSFER',
    'user_id' => 1
));

// Get a specific payment
$payment = $billomat->getInvoicePayment(array('id' => 222));

// Record a payment
$newPayment = $billomat->createInvoicePayment(array(
    'invoice-payment' => array(
        'invoice_id' => 98765,
        'amount' => 1500.00,
        'date' => '2024-03-20',
        'type' => 'BANK_TRANSFER',  // CREDIT_NOTE, BANK_CARD, BANK_TRANSFER, DEBIT, CASH, CHECK, PAYPAL, CREDIT_CARD, COUPON, MISC
        'comment' => 'Wire transfer received',
        'mark_invoice_as_paid' => 1  // 0 or 1
    )
));

// Delete a payment
$billomat->deleteInvoicePayment(array('id' => 222));
```

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

### Tax Settings API

Source: https://context7.com/phobetor/billomat/llms.txt

Endpoints for managing tax rates and tax-free country configurations.

```APIDOC
## GET /taxes

### Description
Retrieve a list of all configured tax rates.

### Method
GET

## POST /taxes

### Description
Create a new tax rate configuration.

### Method
POST

### Request Body
- **tax** (object) - Required - Contains name, rate, and is_default status.
```

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

### POST /invoices

Source: https://context7.com/phobetor/billomat/llms.txt

Create a new invoice including client details, line items, and payment terms.

```APIDOC
## POST /invoices

### Description
Create a new invoice with line items and specific billing configurations.

### Method
POST

### Endpoint
/invoices

### Request Body
- **invoice** (object) - Required - The invoice data object
- **invoice.client_id** (integer) - Required - ID of the client
- **invoice.invoice-items** (array) - Required - List of line items for the invoice
```

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

### Catching Billomat API Exceptions

Source: https://github.com/phobetor/billomat/blob/master/README.md

Demonstrates handling specific API errors by catching typed exceptions that implement ExceptionInterface.

```php
try {
    $client = $billomat->updateClient(array(
        'id' => 133713371337,
        'client' => array(
            'number' => 424242424242,
            'name' => 'client-name'
        )
    ));
}
catch (\Phobetor\Billomat\Exception\NotFoundException $e) {
    // There seems to be no such client.
}
catch (\Phobetor\Billomat\Exception\BadRequestException $e) {
    // Some of the given data must have been bad. $e->getMessage() could help.
}
catch (\Phobetor\Billomat\Exception\TooManyRequestsException $e) {
    // The rate limit was reached. $e->getRateLimitReset() returns the UTC timestamp of the next rate limit reset.
    // @see http://www.billomat.com/en/api/basics/rate-limiting for details about the rate limit.
}
catch (\Phobetor\Billomat\ExceptionInterface $e) {
    // Something else failed. Maybe there is no connection to the API servers.
}
```

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

### Manage Clients

Source: https://context7.com/phobetor/billomat/llms.txt

Perform CRUD operations on client records including filtering and pagination.

```php
<?php
// Get all clients with pagination and filtering
$clients = $billomat->getClients(array(
    'per_page' => 50,
    'page' => 1,
    'order_by' => 'name ASC',
    'name' => 'Acme',
    'country_code' => 'DE',
    'tags' => 'premium,active'
));

// Get a specific client by ID
$client = $billomat->getClient(array('id' => 133713371337));

// Get your own company information
$myself = $billomat->getClientMyself();

// Create a new client with full details
$newClient = $billomat->createClient(array(
    'client' => array(
        'name' => 'Acme Corporation',
        'street' => '123 Business Ave',
        'zip' => '10115',
        'city' => 'Berlin',
        'country_code' => 'DE',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'email' => 'john.doe@acme.com',
        'phone' => '+49 30 123456',
        'vat_number' => 'DE123456789',
        'tax_rule' => 'TAX',           // TAX, NO_TAX, or COUNTRY
        'net_gross' => 'NET',          // NET, GROSS, or SETTINGS
        'payment_types' => 'BANK_TRANSFER,PAYPAL',
        'due_days' => 30,
        'discount_rate' => 2.0,
        'discount_days' => 14,
        'note' => 'Premium customer - priority support'
    )
));

// Update an existing client
$billomat->updateClient(array(
    'id' => 133713371337,
    'client' => array(
        'name' => 'Acme Corp International',
        'archived' => 0  // 0=active, 1=archived
    )
));

// Delete a client
$billomat->deleteClient(array('id' => 133713371337));
```

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

### Manage Email Templates

Source: https://context7.com/phobetor/billomat/llms.txt

Create, read, update, and delete email templates for various document types like invoices, offers, and reminders. Templates can be set as default and include BCC options.

```php
// Email Templates
$emailTemplates = $billomat->getEmailTemplates(array('per_page' => 100));
$emailTemplate = $billomat->getEmailTemplate(array('id' => 1));

$billomat->createEmailTemplate(array(
    'email-template' => array(
        'name' => 'Invoice Email Template',
        'type' => 'INVOICES',  // INVOICES, OFFERS, CONFIRMATIONS, CREDIT_NOTES, DELIVERY_NOTES, REMINDERS
        'subject' => 'Invoice {invoice_number} from {company_name}',
        'text' => "Dear {client_name},\n\nPlease find attached invoice {invoice_number}.\n\nBest regards,\n{company_name}",
        'bcc' => 1,          // Send BCC to sender
        'is_default' => 1    // Set as default template
    )
));

$billomat->updateEmailTemplate(array(
    'id' => 1,
    'email-template' => array('subject' => 'Updated Invoice {invoice_number}')
));

$billomat->deleteEmailTemplate(array('id' => 1));
```

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

### Fetch Invoice PDF

Source: https://github.com/phobetor/billomat/blob/master/README.md

Retrieve an invoice as a PDF file. The response body contains the file content, which can be cast to a string.

```php
// Fetch an invoice pdf file
$response = $billomat->getInvoicePdf(array(
    'id' => 133713371337,
    'format' => 'pdf'
));
$content = (string)$response->getBody();
```

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

### Client Management API

Source: https://github.com/phobetor/billomat/blob/master/README.md

Methods for managing client records and their associated property values.

```APIDOC
## Client Methods

### Description
Methods to retrieve, create, update, and delete client information.

### Methods
- getClients(array $args)
- getClient(array $args)
- getClientMyself(array $args)
- createClient(array $args)
- updateClient(array $args)
- deleteClient(array $args)

### Property Methods
- getClientPropertyValues(array $args)
- getClientPropertyValue(array $args)
- setClientPropertyValue(array $args)
```

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

### Manage Invoice Items with PHP

Source: https://context7.com/phobetor/billomat/llms.txt

Perform CRUD operations on individual invoice line items using the Billomat client.

```php
<?php
// Get all items for an invoice
$items = $billomat->getInvoiceItems(array(
    'invoice_id' => 98765,
    'per_page' => 100,
    'order_by' => 'position ASC'
));

// Get a specific invoice item
$item = $billomat->getInvoiceItem(array('id' => 111));

// Add item to existing invoice
$newItem = $billomat->createInvoiceItem(array(
    'invoice-item' => array(
        'invoice_id' => 98765,
        'article_id' => 42,
        'quantity' => 5,
        'unit' => 'hours',
        'unit_price' => 150.00,
        'title' => 'Additional consulting',
        'tax_rate' => 19.0
    )
));

// Update an invoice item
$billomat->updateInvoiceItem(array(
    'id' => 111,
    'invoice-item' => array(
        'quantity' => 8,
        'description' => 'Extended consulting services'
    )
));

// Delete an invoice item
$billomat->deleteInvoiceItem(array('id' => 111));
```

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

### Email Template Methods

Source: https://github.com/phobetor/billomat/blob/master/README.md

Methods for managing email templates.

```APIDOC
## Email Template Methods

### Description
Manage email templates for system communications.

### Methods
- getEmailTemplates(array $args)
- getEmailTemplate(array $args)
- createEmailTemplate(array $args)
- updateEmailTemplate(array $args)
- deleteEmailTemplate(array $args)
```

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

### Manage Invoice Tags with PHP

Source: https://context7.com/phobetor/billomat/llms.txt

Categorize invoices using tags and retrieve tag clouds for reporting.

```php
<?php
// Get tag cloud (all tags with usage counts)
$tagCloud = $billomat->getInvoiceTagCloud();

// Get tags for specific invoice
$tags = $billomat->getInvoiceTags(array('invoice_id' => 98765));

// Get a specific tag
$tag = $billomat->getInvoiceTag(array('id' => 333));

// Add tag to invoice
$newTag = $billomat->createInvoiceTag(array(
    'invoice-tag' => array(
        'invoice_id' => 98765,
        'name' => 'project-alpha'
    )
));

// Remove tag from invoice
$billomat->deleteInvoiceTag(array('id' => 333));
```

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

### POST /invoices/{id}/complete

Source: https://context7.com/phobetor/billomat/llms.txt

Finalize a draft invoice to make it official, optionally specifying a PDF template.

```APIDOC
## POST /invoices/{id}/complete

### Description
Finalize (complete) an existing draft invoice.

### Method
POST

### Endpoint
/invoices/{id}/complete

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the invoice to complete

#### Request Body
- **complete** (object) - Optional - Completion settings
- **complete.template_id** (integer) - Optional - ID of the PDF template to use
```

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

### Tax Related Methods

Source: https://github.com/phobetor/billomat/blob/master/README.md

Methods for managing tax settings.

```APIDOC
## Tax Related Methods

### Description
Retrieve, create, update, and delete tax configurations.

### Methods
- getTaxes(array $args)
- getTax(array $args)
- createTax(array $args)
- updateTax(array $args)
- deleteTax(array $args)
```

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

### Credit Note Management API

Source: https://context7.com/phobetor/billomat/llms.txt

Create and manage credit notes for refunds and corrections.

```APIDOC
## Credit Note Management API

### Description
Create and manage credit notes for refunds and corrections.

### Methods
- **GET /credit_notes**: List credit notes.
- **GET /credit_notes/{id}**: Get a specific credit note.
- **POST /credit_notes**: Create a credit note.
- **PUT /credit_notes/{id}**: Update a credit note.
- **POST /credit_notes/{id}/complete**: Complete a credit note.
- **GET /credit_notes/{id}/pdf**: Get the PDF of a credit note.
- **POST /credit_notes/{id}/email**: Send a credit note via email.
- **POST /credit_notes/{id}/sign**: Upload a digital signature for a credit note.
- **DELETE /credit_notes/{id}**: Delete a credit note.

### Parameters
#### GET /credit_notes
- **client_id** (integer) - Optional - Filter by client ID.
- **status** (string) - Optional - Filter by status (e.g., 'OPEN').
- **from** (date) - Optional - Filter by date from.
- **to** (date) - Optional - Filter by date to.
- **per_page** (integer) - Optional - Number of items per page.

#### GET /credit_notes/{id}
- **id** (integer) - Required - The ID of the credit note.

#### POST /credit_notes
##### Request Body
- **credit-note** (object) - Required
  - **client_id** (integer) - Required - The ID of the client.
  - **invoice_id** (integer) - Optional - Reference to the original invoice.
  - **number_pre** (string) - Optional - Prefix for the credit note number.
  - **date** (date) - Required - The date of the credit note.
  - **title** (string) - Optional - The title of the credit note.
  - **intro** (string) - Optional - Introductory text.
  - **note** (string) - Optional - Additional notes.
  - **currency_code** (string) - Required - The currency code (e.g., 'EUR').
  - **net_gross** (string) - Required - Whether amounts are 'NET' or 'GROSS'.
  - **credit-note-items** (object) - Required
    - **credit-note-item** (array) - Required
      - **quantity** (float) - Required - Quantity of the item.
      - **unit** (string) - Optional - Unit of measurement.
      - **unit_price** (float) - Required - Price per unit.
      - **title** (string) - Required - Title of the item.
      - **tax_rate** (float) - Optional - Tax rate.

#### PUT /credit_notes/{id}
##### Request Body
- **id** (integer) - Required - The ID of the credit note to update.
- **credit-note** (object) - Required - Fields to update.
  - **note** (string) - Optional - Updated note.

#### POST /credit_notes/{id}/complete
##### Request Body
- **id** (integer) - Required - The ID of the credit note.
- **complete** (object) - Required
  - **template_id** (integer) - Required - The ID of the template to use.

#### GET /credit_notes/{id}/pdf
- **id** (integer) - Required - The ID of the credit note.
- **format** (string) - Required - The desired format (e.g., 'pdf').

#### POST /credit_notes/{id}/email
##### Request Body
- **id** (integer) - Required - The ID of the credit note.
- **email** (object) - Required
  - **recipients** (object) - Required
    - **to** (string) - Required - Recipient email address.
  - **subject** (string) - Required - Email subject.
  - **body** (string) - Required - Email body.

#### POST /credit_notes/{id}/sign
##### Request Body
- **id** (integer) - Required - The ID of the credit note.
- **signature** (object) - Required
  - **base64file** (string) - Required - The digital signature as a base64 encoded string.

#### DELETE /credit_notes/{id}
- **id** (integer) - Required - The ID of the credit note to delete.

### Response Examples
#### GET /credit_notes (Success)
```json
{
  "credit_notes": [
    {
      "id": 54321,
      "client_id": 133713371337,
      "invoice_id": 98765,
      "number_pre": "CN-",
      "date": "2024-03-20",
      "title": "Credit Note for Invoice INV-98765",
      "intro": "We hereby credit you the following amount:",
      "note": "Refund for returned items.",
      "currency_code": "EUR",
      "net_gross": "NET"
    }
  ]
}
```
#### POST /credit_notes (Success)
```json
{
  "credit-note": {
    "id": 54322,
    "client_id": 133713371337,
    "invoice_id": 98765,
    "number_pre": "CN-",
    "date": "2024-03-20",
    "title": "Credit Note for Invoice INV-98765",
    "intro": "We hereby credit you the following amount:",
    "note": "Refund for returned items.",
    "currency_code": "EUR",
    "net_gross": "NET",
    "credit-note-items": {
      "credit-note-item": [
        {
          "quantity": 2,
          "unit": "pieces",
          "unit_price": 100.00,
          "title": "Returned product refund",
          "tax_rate": 19.0
        }
      ]
    }
  }
}
```
#### PUT /credit_notes/{id} (Success)
```json
{
  "credit-note": {
    "id": 54321,
    "client_id": 133713371337,
    "invoice_id": 98765,
    "number_pre": "CN-",
    "date": "2024-03-20",
    "title": "Credit Note for Invoice INV-98765",
    "intro": "We hereby credit you the following amount:",
    "note": "Updated note",
    "currency_code": "EUR",
    "net_gross": "NET"
  }
}
```
```

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

### Manage Credit Note Items and Payments

Source: https://context7.com/phobetor/billomat/llms.txt

Use these methods to retrieve, create, update, and delete credit note items and their associated payment records. Ensure correct IDs and data structures are provided for each operation.

```php
<?php
// Credit Note Items
$items = $billomat->getCreditNoteItems(array('credit_note_id' => 54321));
$item = $billomat->getCreditNoteItem(array('id' => 444));

$billomat->createCreditNoteItem(array(
    'credit-note-item' => array(
        'credit_note_id' => 54321,
        'quantity' => 1,
        'unit_price' => 50.00,
        'title' => 'Service credit',
        'tax_rate' => 19.0
    )
));

$billomat->updateCreditNoteItem(array(
    'id' => 444,
    'credit-note-item' => array('quantity' => 2)
));

$billomat->deleteCreditNoteItem(array('id' => 444));

// Credit Note Payments
$payments = $billomat->getCreditNotePayments(array(
    'credit_note_id' => 54321,
    'from' => '2024-01-01',
    'to' => '2024-12-31',
    'type' => 'BANK_TRANSFER'
));

$billomat->createCreditNotePayment(array(
    'credit-note-payment' => array(
        'credit_note_id' => 54321,
        'amount' => 238.00,
        'date' => '2024-03-25',
        'type' => 'BANK_TRANSFER',  // CREDIT_NOTE, BANK_TRANSFER, DEBIT, CASH, PAYPAL, CREDIT_CARD, MISC
        'comment' => 'Refund issued',
        'mark_credit_note_as_paid' => 1
    )
));

$billomat->deleteCreditNotePayment(array('id' => 555));
```

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

### Manage Client Properties

Source: https://context7.com/phobetor/billomat/llms.txt

Access and modify custom property values associated with client records.

```php
<?php
// Get all property values for a specific client
$propertyValues = $billomat->getClientPropertyValues(array(
    'client_id' => 133713371337,
    'per_page' => 100
));

// Get a specific property value
$propertyValue = $billomat->getClientPropertyValue(array('id' => 456));

// Set a client property value
$billomat->setClientPropertyValue(array(
    'client-property-value' => array(
        'client_id' => 133713371337,
        'client_property_id' => 789,  // ID of the property definition
        'value' => 'Enterprise Plan'
    )
));
```

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

### Template Management API

Source: https://context7.com/phobetor/billomat/llms.txt

Endpoints for managing document templates including listing, previewing, creating, updating, and deleting templates.

```APIDOC
## GET /templates

### Description
List all document templates filtered by type.

### Method
GET

### Parameters
#### Query Parameters
- **type** (string) - Optional - Template type (INVOICE, OFFER, etc.)
- **per_page** (integer) - Optional - Number of results per page.

## POST /templates

### Description
Create a new document template.

### Method
POST

### Request Body
- **template** (object) - Required - Contains name, type, format, and base64file.
```

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

### Update an Existing Client

Source: https://github.com/phobetor/billomat/blob/master/README.md

Update a client's information in Billomat by providing its ID and the new client data. This method maps directly to the Billomat API's update functionality.

```php
// Update a client
$client = $billomat->updateClient(array(
    'id' => 133713371337,
    'client' => array(
        'number' => 424242424242,
        'name' => 'client-name'
    )
));
```

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

### Handle Billomat API Exceptions in PHP

Source: https://context7.com/phobetor/billomat/llms.txt

Catch specific Billomat API exceptions like NotFoundException, BadRequestException, UnauthorizedException, and TooManyRequestsException for precise error handling. A general ExceptionInterface catch-all is also provided.

```php
<?php
use Phobetor\Billomat\Exception\NotFoundException;
use Phobetor\Billomat\Exception\BadRequestException;
use Phobetor\Billomat\Exception\UnauthorizedException;
use Phobetor\Billomat\Exception\TooManyRequestsException;
use Phobetor\Billomat\Exception\ExceptionInterface;

try {
    $client = $billomat->updateClient(array(
        'id' => 133713371337,
        'client' => array(
            'name' => 'Updated Name',
            'email' => 'invalid-email'  // Will cause BadRequestException
        )
    ));

    echo "Client updated successfully\n";

} catch (NotFoundException $e) {
    // HTTP 404 - Resource not found
    echo "Client not found: " . $e->getMessage() . "\n";

} catch (BadRequestException $e) {
    // HTTP 400 - Invalid data submitted
    echo "Invalid data: " . $e->getMessage() . "\n";

} catch (UnauthorizedException $e) {
    // HTTP 401 - Authentication failed
    echo "Authentication failed: " . $e->getMessage() . "\n";

} catch (TooManyRequestsException $e) {
    // HTTP 429 - Rate limit exceeded
    echo "Rate limit exceeded. Remaining: " . $e->getRateLimitRemaining() . "\n";
    echo "Reset time (UTC timestamp): " . $e->getRateLimitReset() . "\n";

    // Calculate wait time
    $resetTime = new DateTime('@' . $e->getRateLimitReset());
    $now = new DateTime('now', new DateTimeZone('UTC'));
    $waitSeconds = $resetTime->getTimestamp() - $now->getTimestamp();
    echo "Wait {$waitSeconds} seconds before retrying\n";

} catch (ExceptionInterface $e) {
    // Catch-all for any Billomat API error
    echo "API Error: " . $e->getMessage() . " (Code: " . $e->getCode() . ")\n";
}

```

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

### Use Billomat Client in Symfony Controller

Source: https://context7.com/phobetor/billomat/llms.txt

Retrieve the Billomat client service within a Symfony controller to perform operations like creating invoices. The client is typically accessed via the 'phobetor_billomat.client' service ID.

```php
<?php
// Use in controllers or services
class InvoiceController extends Controller
{
    public function createAction()
    {
        $billomat = $this->get('phobetor_billomat.client');

        $invoice = $billomat->createInvoice(array(
            'invoice' => array(
                'client_id' => 123,
                // ... invoice data
            )
        ));

        return $this->json($invoice);
    }
}

```

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

### Reminder Texts API

Source: https://context7.com/phobetor/billomat/llms.txt

Endpoints for managing dunning levels and reminder communication settings.

```APIDOC
## POST /reminder-texts

### Description
Create a new reminder text (dunning level).

### Method
POST

### Request Body
- **reminder-text** (object) - Required - Contains sorting, name, subject, header, footer, charge_name, charge_description, and charge_amount.
```