### Installation

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Instructions on how to install the wFirma SDK using Composer.

```APIDOC
## Installation

Use composer:

```bash
composer require webit/w-firma-api
```

| Version | PHP Version | Known issues |
|---------|-------------|--------------|
| 1.x     | <= 7.0      |              |
| 2.x     | >= 7.1      | [#50 Call to a member function code() on null](https://github.com/dbojdo/wFirma/issues/50) |
| 3.x     | >= 8.1      |              |
```

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

### Install wFirma API SDK using Composer

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Use this command to add the wFirma API SDK to your project via Composer.

```bash
composer require webit/w-firma-api
```

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

### ApiFactory Usage

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Example of how to use ApiFactory to create API instances for wFirma modules.

```APIDOC
### ApiFactory

In order to create API for given module use ***ModuleApiFactory***.

```php
<?php

use Webit\WFirmaSDK\Entity\ModuleApiFactory;
use Webit\WFirmaSDK\Entity\EntityApiFactory;

$entityApiFactory = new EntityApiFactory();
$entityApi = $entityApiFactory->create($auth);

$apiFactory = new ModuleApiFactory($entityApi);
```
```

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

### Create, Find, Get, and Delete Tags

Source: https://context7.com/dbojdo/wfirma/llms.txt

Demonstrates the basic CRUD operations for tags using the TagsApi. Ensure the TagsApi is initialized via the apiFactory.

```php
<?php

use Webit\WFirmaSDK\Tags\Tag;
use Webit\WFirmaSDK\Tags\TagId;
use Webit\WFirmaSDK\Tags\TagIds;
use Webit\WFirmaSDK\Entity\Parameters\Parameters;
use Webit\WFirmaSDK\Entity\Parameters\Conditions;

/** @var \Webit\WFirmaSDK\Tags\TagsApi $api */
$api = $apiFactory->tagsApi();

// Create a new tag
$tag = new Tag('VIP Client');
$tag = $api->add($tag);
echo "Tag created with ID: " . $tag->id()->id();

// Find all tags
$tags = $api->find();

// Find tags by name
$parameters = Parameters::findParameters(
    Conditions::like('name', '%Client%')
);
$tags = $api->find($parameters);

// Get tag by ID
$tag = $api->get(TagId::create(5));

// Delete tag
$api->delete(TagId::create(5));

// Count tags
$count = $api->count();

```

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

### Handle API Exceptions in PHP

Source: https://context7.com/dbojdo/wfirma/llms.txt

This example demonstrates how to catch various specific exceptions thrown by the wFirma SDK, including authentication, validation, and rate limit errors. It also includes a general catch block for unexpected issues.

```php
<?php

use Webit\WFirmaSDK\Entity\Exception\ApiException;
use Webit\WFirmaSDK\Entity\Exception\AuthException;
use Webit\WFirmaSDK\Entity\Exception\NotFoundException;
use Webit\WFirmaSDK\Entity\Exception\ValidationException;
use Webit\WFirmaSDK\Entity\Exception\InputErrorException;
use Webit\WFirmaSDK\Entity\Exception\AccessDenied;
use Webit\WFirmaSDK\Entity\Exception\TotalRequestsLimitExceededException;
use Webit\WFirmaSDK\Entity\Exception\AuthFailedLimitWait5MinutesException;
use Webit\WFirmaSDK\Invoices\InvoiceId;

try {
    $invoice = $apiFactory->invoicesApi()->get(InvoiceId::create(99999));

} catch (AuthException $e) {
    // Invalid credentials
    echo "Authentication failed: " . $e->getMessage();

} catch (AuthFailedLimitWait5MinutesException $e) {
    // Too many failed auth attempts
    echo "Too many login attempts. Please wait 5 minutes.";

} catch (NotFoundException $e) {
    // Entity not found
    echo "Invoice not found";

} catch (AccessDenied $e) {
    // Insufficient permissions
    echo "Access denied: " . $e->getMessage();

} catch (ValidationException $e) {
    // Validation errors
    echo "Validation error: " . $e->getMessage();

} catch (InputErrorException $e) {
    // Invalid input data
    echo "Input error: " . $e->getMessage();

} catch (TotalRequestsLimitExceededException $e) {
    // API rate limit exceeded
    echo "Rate limit exceeded. Please try again later.";

} catch (ApiException $e) {
    // General API error (base class for all API exceptions)
    echo "API error: " . $e->getMessage();

} catch (\Throwable $e) {
    // Unexpected errors
    echo "Unexpected error: " . $e->getMessage();
}

```

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

### Add, Edit, Delete, and Get Contractor

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Shows how to manage contractors, including adding new ones, modifying existing ones, deleting them, and retrieving them by ID.

```php
<?php
use Webit\WFirmaSDK\Contractors\Contractor;

/** @var \Webit\WFirmaSDK\Contractors\ContractorsApi $api */
$api = $apiFactory->contractorsApi($auth);

// add a new contractor
$contractor = new Contractor('my-new-contractor');
$contractor = $api->add($contractor);

// edit the contractor
$contractor->rename('new name', 'new alt name');
$contractor = $api->edit($contractor);

// delete the contractor
$api->delete($contractor->id());

// get contractor by id
$contractor = $api->get(\Webit\WFirmaSDK\Contractors\ContractorId::create(123));

```

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

### Add, Get, Edit, and Delete Invoice

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Demonstrates the lifecycle of an invoice, from creation with contractor and content details to retrieval, modification, and deletion.

```php
<?php
use Webit\WFirmaSDK\Contractors\Contractor;
use Webit\WFirmaSDK\Contractors\InvoiceAddress;
use Webit\WFirmaSDK\Invoices\InvoicesContent;
use Webit\WFirmaSDK\Goods\GoodId;
use Webit\WFirmaSDK\Invoices\Payment;
use Webit\WFirmaSDK\Payments\PaymentMethod;

/** @var \Webit\WFirmaSDK\Invoices\InvoicesApi $api */
$api = $apiFactory->invoicesApi();

// add a new invoice
$invoice = \Webit\WFirmaSDK\Invoices\Invoice::forContractor(
    new Contractor(
        'client name',
        'alt name',
        '1234565432', // vat no
        null, // regon
        new InvoiceAddress(
            'ul. Mokra 12',
            '01-006',
            'Warszawa',
            'PL'
        )
    ),
    Payment::create(PaymentMethod::transfer())
);

$invoice->addInvoiceContent(
    InvoicesContent::fromGoodId(
        GoodId::create(123),
        3,
        123.32,
        23
    )
);

$invoice->addInvoiceContent(
    InvoicesContent::fromName(
        'some stuff',
        'szt.',
        3,
        123.32,
        23
    )
);

$invoice = $api->add($invoice);

// get invoice by id
$invoice = $api->get(\Webit\WFirmaSDK\Invoices\InvoiceId::create(123));

// edit the invoice
$invoice->changePayment(
    $invoice->payment()->withPaymentDate(new \DateTime())
);

// do some more edits
$invoice = $api->edit($invoice);

// delete the invoice
$api->delete($invoice->id());

```

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

### TagsApi - Organization with Tags

Source: https://context7.com/dbojdo/wfirma/llms.txt

Manage tags for organizing invoices, contractors, and other entities. Includes creating, finding, getting, and deleting tags.

```APIDOC
## TagsApi - Organization with Tags

Tags allow you to categorize and organize invoices, contractors, and other entities for easier filtering and reporting.

### Create a new tag

**Method**: POST (implied by SDK usage)
**Endpoint**: /tags

**Request Body**: 
- **name** (string) - Required - The name of the tag.

### Request Example
```php
use Webit\WFirmaSDK\Tags\Tag;

$tag = new Tag('VIP Client');
$tag = $api->add($tag);
```

### Response
#### Success Response (200)
- **id** (TagId) - The ID of the newly created tag.

### Find all tags

**Method**: GET (implied by SDK usage)
**Endpoint**: /tags

### Find tags by name

**Method**: GET (implied by SDK usage)
**Endpoint**: /tags

**Query Parameters**:
- **name** (string) - Optional - Filter tags by name (supports LIKE operator).

### Request Example
```php
use Webit\WFirmaSDK\Entity\Parameters\Parameters;
use Webit\WFirmaSDK\Entity\Parameters\Conditions;

$parameters = Parameters::findParameters(
    Conditions::like('name', '%Client%')
);
$tags = $api->find($parameters);
```

### Get tag by ID

**Method**: GET (implied by SDK usage)
**Endpoint**: /tags/{id}

**Path Parameters**:
- **id** (TagId) - Required - The ID of the tag to retrieve.

### Delete tag

**Method**: DELETE (implied by SDK usage)
**Endpoint**: /tags/{id}

**Path Parameters**:
- **id** (TagId) - Required - The ID of the tag to delete.

### Count tags

**Method**: GET (implied by SDK usage)
**Endpoint**: /tags/count

### Response
#### Success Response (200)
- **count** (integer) - The total number of tags.
```

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

### Resolve VAT Codes using API with Caching

Source: https://context7.com/dbojdo/wfirma/llms.txt

Initializes a VAT code ID repository that fetches codes from the API, with optional PSR-16 compatible caching for performance. Requires 'symfony/cache' package for the example cache implementation.

```php
<?php

use Webit\WFirmaSDK\Vat\Repository\VatCodeIdRepositoryFactory;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
use Webit\WFirmaSDK\Invoices\InvoicesContent;
use Webit\WFirmaSDK\Vat\VatRate;

// Option 2: Create repository that fetches VAT codes from API
// With optional PSR-16 compatible cache for performance
$vatCodesApi = $apiFactory->vatCodesApi();

// Using Symfony Cache (requires symfony/cache package)
$cache = new Psr16Cache(new FilesystemAdapter(
    'vat_codes',           // Namespace
    3600,                  // Default TTL (1 hour)
    '/tmp/cache'           // Cache directory
));

$repository = VatCodeIdRepositoryFactory::createWithApi(
    $vatCodesApi,
    $cache  // Optional: pass null to disable caching
);

// Now use in invoice content
$vatCodeId = $repository->getByCode('23');

$content = InvoicesContent::fromName(
    'Service',
    'h',
    10,
    200.00,
    VatRate::fromVatCodeId($vatCodeId)
);

```

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

### Configure Doctrine Annotation Registry

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Configure the AnnotationRegistry for Doctrine if you are not using AnnotationRegistry 2.0. This is typically needed for older versions or specific setups.

```php
<?php
use Doctrine\Common\Annotations\AnnotationRegistry;
$loader = include __DIR__.'/vendor/autoload.php'; // composer's autoload.php
AnnotationRegistry::registerLoader(array($loader, 'loadClass'));
```

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

### Get VatCodeId from VAT Rate Code with API Cache

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Creates a VatCodeIdRepository that fetches mappings from the API and caches them using a PSR-16 compatible cache implementation. Requires 'psr/simple-cache-implementation'.

```php
use Webit\WFirmaSDK\Vat\Repository\VatCodeIdRepositoryFactory;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

$repository = VatCodeIdRepositoryFactory::createWithApi(
  $api = $apiFactory->vatCodesApi(),
  new Psr16Cache(new FilesystemAdapter()) // use cache adapter of your choice (no cache by default)
);

$repository->getByCode('23'); // returns new VatCodeId(222);

```

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

### Get VatCodeId from VAT Rate Code with Custom Map

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Creates a VatCodeIdRepository using a custom static map for translating VAT rate codes to VatCodeIds. Useful for predefined mappings.

```php
use Webit\WFirmaSDK\Vat\Repository\VatCodeIdRepositoryFactory;

$repository = VatCodeIdRepositoryFactory::createWithMap(
  ['23' => 222, '8' => 223] // provide your static ID mapping
);

$repository->getByCode('23'); // returns new VatCodeId(222);

```

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

### Authentication with API Keys

Source: https://context7.com/dbojdo/wfirma/llms.txt

This snippet demonstrates how to authenticate with the wFirma API using API keys and initialize the necessary API factories.

```APIDOC
## Authentication with API Keys

### Description
Authentication is required for all API operations. The SDK supports API key-based authentication which is the recommended method for connecting to wFirma.

### Method
N/A (This is a setup and authentication example)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php

use Webit\WFirmaSDK\Auth\ApiKeysAuth;
use Webit\WFirmaSDK\Entity\EntityApiFactory;
use Webit\WFirmaSDK\Entity\ModuleApiFactory;

// Create authentication with API keys
// Get your API keys from: https://doc.wfirma.pl/#autoryzacja
$auth = new ApiKeysAuth(
    'your-access-key',      // Access key from wFirma
    'your-secret-key',      // Secret key from wFirma
    'your-app-key',         // Application key from wFirma
    1123                    // Optional: Company ID (required for multi-company accounts)
);

// Initialize the API factory chain
$entityApiFactory = new EntityApiFactory();
$entityApi = $entityApiFactory->create($auth);
$apiFactory = new ModuleApiFactory($entityApi);

// Now you can access all module APIs
$invoicesApi = $apiFactory->invoicesApi();
$contractorsApi = $apiFactory->contractorsApi();
$paymentsApi = $apiFactory->paymentsApi();
// ... other module APIs
?>
```

### Response
#### Success Response (200)
N/A (This is a setup example)

#### Response Example
N/A
```

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

### Create Module API Instance

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Use ModuleApiFactory to create API instances for different wFirma modules after setting up authentication and an EntityApi.

```php
<?php

use Webit\WFirmaSDK\Entity\ModuleApiFactory;
use Webit\WFirmaSDK\Entity\EntityApiFactory;

$entityApiFactory = new EntityApiFactory();
$entityApi = $entityApiFactory->create($auth);

$apiFactory = new ModuleApiFactory($entityApi);
```

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

### Authenticate with wFirma API using API Keys

Source: https://context7.com/dbojdo/wfirma/llms.txt

Set up API key authentication for the wFirma SDK. Ensure you have your access, secret, and application keys from the wFirma platform. The company ID is optional but required for multi-company accounts.

```php
<?php

use Webit\WFirmaSDK\Auth\ApiKeysAuth;
use Webit\WFirmaSDK\Entity\EntityApiFactory;
use Webit\WFirmaSDK\Entity\ModuleApiFactory;

// Create authentication with API keys
// Get your API keys from: https://doc.wfirma.pl/#autoryzacja
$auth = new ApiKeysAuth(
    'your-access-key',      // Access key from wFirma
    'your-secret-key',      // Secret key from wFirma
    'your-app-key',         // Application key from wFirma
    1123                    // Optional: Company ID (required for multi-company accounts)
);

// Initialize the API factory chain
$entityApiFactory = new EntityApiFactory();
$entityApi = $entityApiFactory->create($auth);
$apiFactory = new ModuleApiFactory($entityApi);

// Now you can access all module APIs
$invoicesApi = $apiFactory->invoicesApi();
$contractorsApi = $apiFactory->contractorsApi();
$paymentsApi = $apiFactory->paymentsApi();
// ... other module APIs

```

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

### Manage Contractors with WFirma SDK

Source: https://context7.com/dbojdo/wfirma/llms.txt

Utilize the ContractorsApi for managing contractor details. This includes creating new contractors with extensive information, retrieving them by ID, editing existing ones, and deleting them. You can also count the total number of contractors.

```php
<?php

use Webit\WFirmaSDK\Contractors\Contractor;
use Webit\WFirmaSDK\Contractors\ContractorId;
use Webit\WFirmaSDK\Contractors\InvoiceAddress;
use Webit\WFirmaSDK\Contractors\ContactDetails;
use Webit\WFirmaSDK\Contractors\PaymentSettings;
use Webit\WFirmaSDK\Payments\PaymentMethod;

/** @var \Webit\WFirmaSDK\Contractors\ContractorsApi $api */
$api = $apiFactory->contractorsApi();

// Create a new contractor with full details
$contractor = new Contractor(
    'Tech Solutions Ltd',             // Company name
    'Tech Solutions',                 // Alternative name
    '9876543210',                     // VAT ID (NIP)
    '123456789',                      // REGON
    new InvoiceAddress(
        'ul. Techniczna 5',
        '00-001',
        'Krakow',
        'PL'
    ),
    null,                             // Contact address (if different)
    new ContactDetails(
        '+48 123 456 789',            // Phone
        'tech.solutions',             // Skype
        '+48 123 456 780',            // Fax
        'contact@techsolutions.pl',
        'https://techsolutions.pl'
    ),
    'Premium client',                 // Description
    true,                             // Is buyer
    false,                            // Is seller
    'PL12345678901234567890123456',   // Bank account number
    new PaymentSettings(
        14,                           // Payment days
        PaymentMethod::transfer(),    // Default payment method
        5.0,                          // Discount percent
        true                          // Send payment reminders
    )
);

$contractor = $api->add($contractor);
echo "Contractor created with ID: " . $contractor->id()->id();

// Get contractor by ID
$contractor = $api->get(ContractorId::create(789));

// Edit contractor
$contractor->rename('New Company Name', 'New Alt Name');
$contractor->changeDescription('Updated description');
$contractor = $api->edit($contractor);

// Delete contractor
$api->delete(ContractorId::create(789));

// Count total contractors
$totalCount = $api->count();
echo "Total contractors: " . $totalCount;
```

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

### Module APIs

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Overview of the available wFirma modules and their supported API operations.

```APIDOC
### Module APIs

Every main module has it's own instance of the API exposing supported methods.

* **Company Accounts**: find, findAll, get, count,
* **Contractors**: add, edit, delete, find, findAll, get, count
* **Declaration Countries**: find, findAll, get, count
* **Goods**: add, edit, delete, find, get
* **Invoice Deliveries**: add, delete, find, findAll, get, count
* **Invoice Descriptions**: find, findAll, get, count
* **Invoices**: add, edit, delete, find, findAll, get, count, fiscalise, unfiscalise, download, send
* **Payments**: add, edit, delete, find, findAll, get
* **Notes**: add, edit, delete, find, findAll, get, count
* **Series**: add, edit, delete, find, findAll, get, count
* **Tags**: add, edit, delete, find, findAll, get, count
* **TranslationLanguages**: find, findAll, get, count
* **VatCodes**: find, findAll, get, count
* **Expenses**: find, get
```

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

### PHPUnit Test Execution

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Commands to set up and run PHPUnit tests for the project. This involves copying the configuration file, editing credentials, and executing tests via Docker Compose.

```bash
cp phpunit.xml.dist phpunit.xml
vim phpunit.xml // edit your username and password

docker-compose run --rm composer
docker-compose run --rm phpunit

```

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

### Manage Invoices with WFirma SDK

Source: https://context7.com/dbojdo/wfirma/llms.txt

Use the InvoicesApi to perform operations on existing invoices. This includes retrieval, editing payment dates, downloading as PDF, sending via email, fiscalization, unfiscalization, and deletion. Ensure you have the necessary InvoiceId and potentially DownloadParameters or SendParameters.

```php
<?php

use Webit\WFirmaSDK\Invoices\InvoiceId;
use Webit\WFirmaSDK\Invoices\DownloadParameters;
use Webit\WFirmaSDK\Invoices\SendParameters;
use Webit\WFirmaSDK\Contractors\ContractorId;

/** @var \Webit\WFirmaSDK\Invoices\InvoicesApi $api */
$api = $apiFactory->invoicesApi();

// Get invoice by ID
$invoiceId = InvoiceId::create(12345);
$invoice = $api->get($invoiceId);

// Update invoice payment date
$invoice->changePayment(
    $invoice->payment()->withPaymentDate(new \DateTime('+14 days'))
);
$invoice = $api->edit($invoice);

// Download invoice as PDF
$downloadParams = new DownloadParameters(); // Optional: customize output format
$file = $api->download($invoiceId, $downloadParams);
file_put_contents('invoice_12345.pdf', $file->content());

// Send invoice via email
$sendParams = new SendParameters();
$api->send($invoiceId, $sendParams);

// Fiscalize invoice (register with fiscal system)
$api->fiscalise($invoiceId);

// Unfiscalize invoice
$api->unfiscalise($invoiceId);

// Delete invoice
$api->delete($invoiceId);

// Create invoice for existing contractor (by ID)
$invoice = Invoice::forContractorOfId(
    ContractorId::create(456),        // Existing contractor ID
    Payment::create(PaymentMethod::cash())
);
$invoice->addInvoiceContent(
    InvoicesContent::fromName('Product', 'pcs', 1, 100.00, 23)
);
$invoice = $api->add($invoice);
```

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

### Authentication

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Details on how to authenticate with the wFirma API using ApiKeyAuth or BasicAuth.

```APIDOC
## Authentication

The library supports:
 * `ApiKeysAuth`
 * `BasicAuth` (deprecated)

### ApiKeyAuth

```php
<?php
use Webit\WFirmaSDK\Auth\ApiKeysAuth;

$auth = new ApiKeysAuth('your-access-key', 'your-secret-key', 'your-app-key', $companyId = 1123); // $companyId is optional
```

To get your API Keys follow the official documentation: [https://doc.wfirma.pl/#autoryzacja](https://doc.wfirma.pl/#autoryzacja)

### BasicAuth (deprecated)

This method will not be supported anymore by wFirma.

```php
<?php
use Webit\WFirmaSDK\Auth\BasicAuth;

$auth = new BasicAuth('your-user-name', 'your-password', $companyId = 1123); // $companyId is optional
```
```

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

### API Key Authentication

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Instantiate ApiKeysAuth with your access key, secret key, and app key. The company ID is optional.

```php
<?php
use Webit\WFirmaSDK\Auth\ApiKeysAuth;

$auth = new ApiKeysAuth('your-access-key', 'your-secret-key', 'your-app-key', $companyId = 1123); // $companyId is optional
```

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

### Basic Authentication (Deprecated)

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Instantiate BasicAuth with your username and password. The company ID is optional. Note that this method is deprecated and will not be supported by wFirma.

```php
<?php
use Webit\WFirmaSDK\Auth\BasicAuth;

$auth = new BasicAuth('your-user-name', 'your-password', $companyId = 1123); // $companyId is optional
```

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

### InvoicesApi - Creating Invoices

Source: https://context7.com/dbojdo/wfirma/llms.txt

This snippet demonstrates how to use the InvoicesApi to create new invoices, including adding line items and associating them with contractors.

```APIDOC
## POST /invoices

### Description
The InvoicesApi provides methods for creating, editing, deleting, and managing invoices. Invoices can be created for new contractors inline or linked to existing contractors by ID.

### Method
POST

### Endpoint
/invoices

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This endpoint accepts an `Invoice` object which can be constructed using static methods like `Invoice::forContractor()` and populated with `Contractor` and `InvoicesContent` objects.

### Request Example
```php
<?php

use Webit\WFirmaSDK\Contractors\Contractor;
use Webit\WFirmaSDK\Contractors\InvoiceAddress;
use Webit\WFirmaSDK\Invoices\Invoice;
use Webit\WFirmaSDK\Invoices\InvoicesContent;
use Webit\WFirmaSDK\Invoices\Payment;
use Webit\WFirmaSDK\Payments\PaymentMethod;
use Webit\WFirmaSDK\Goods\GoodId;

/** @var \Webit\WFirmaSDK\Invoices\InvoicesApi $api */
$api = $apiFactory->invoicesApi();

// Create invoice with a new contractor (contractor created inline)
$invoice = Invoice::forContractor(
    new Contractor(
        'ACME Corporation',           // Company name
        'ACME Corp',                  // Alternative name
        '1234567890',                 // VAT ID (NIP)
        null,                         // REGON (optional)
        new InvoiceAddress(
            'ul. Mokra 12',           // Street address
            '01-006',                 // Postal code
            'Warszawa',               // City
            'PL'                      // Country code
        )
    ),
    Payment::create(PaymentMethod::transfer()) // Payment by bank transfer
);

// Add invoice line items from product catalog (by Good ID)
$invoice->addInvoiceContent(
    InvoicesContent::fromGoodId(
        GoodId::create(123),          // Product ID from wFirma goods catalog
        3,                            // Quantity
        123.32,                       // Unit price (net)
        23                            // VAT rate (23%)
    )
);

// Add invoice line items by name (ad-hoc items)
$invoice->addInvoiceContent(
    InvoicesContent::fromName(
        'Consulting Services',        // Item name/description
        'h',                          // Unit (hours)
        8,                            // Quantity (8 hours)
        150.00,                       // Unit price (net)
        23                            // VAT rate (23%)
    )
);

// Save the invoice to wFirma
$invoice = $api->add($invoice);

echo "Invoice created with ID: " . $invoice->id()->id();
echo "Invoice number: " . $invoice->number()->fullNumber();
?>
```

### Response
#### Success Response (200)
- **id** (object) - The unique identifier of the created invoice.
- **number** (object) - The full number of the created invoice.

#### Response Example
```json
{
  "id": {
    "id": "12345"
  },
  "number": {
    "fullNumber": "2023/10/123"
  }
}
```
```

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

### Resolve VAT Codes using Static Map

Source: https://context7.com/dbojdo/wfirma/llms.txt

Creates a VAT code ID repository using a predefined static map. This is efficient when VAT code IDs are known beforehand.

```php
<?php

use Webit\WFirmaSDK\Vat\Repository\VatCodeIdRepositoryFactory;

// Option 1: Create repository with static VAT code mapping
// Useful when you know your VAT code IDs in advance
$repository = VatCodeIdRepositoryFactory::createWithMap([
    '23' => 222,    // Standard 23% VAT
    '8'  => 223,    // Reduced 8% VAT
    '5'  => 224,    // Reduced 5% VAT
    '0'  => 225,    // 0% VAT
    'zw' => 226,    // Exempt
    'np' => 227,    // Not applicable
]);

$vatCodeId = $repository->getByCode('23');
// Returns VatCodeId(222)

```

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

### Create an Invoice with a New Contractor

Source: https://context7.com/dbojdo/wfirma/llms.txt

Create a new invoice in wFirma, including a new contractor defined inline. This method allows for immediate creation of an invoice for a contractor not yet present in the system. Payment method is set to bank transfer.

```php
<?php

use Webit\WFirmaSDK\Contractors\Contractor;
use Webit\WFirmaSDK\Contractors\InvoiceAddress;
use Webit\WFirmaSDK\Invoices\Invoice;
use Webit\WFirmaSDK\Invoices\InvoicesContent;
use Webit\WFirmaSDK\Invoices\Payment;
use Webit\WFirmaSDK\Payments\PaymentMethod;
use Webit\WFirmaSDK\Goods\GoodId;

/** @var \Webit\WFirmaSDK\Invoices\InvoicesApi $api */
$api = $apiFactory->invoicesApi();

// Create invoice with a new contractor (contractor created inline)
$invoice = Invoice::forContractor(
    new Contractor(
        'ACME Corporation',           // Company name
        'ACME Corp',                  // Alternative name
        '1234567890',                 // VAT ID (NIP)
        null,                         // REGON (optional)
        new InvoiceAddress(
            'ul. Mokra 12',           // Street address
            '01-006',                 // Postal code
            'Warszawa',               // City
            'PL'                      // Country code
        )
    ),
    Payment::create(PaymentMethod::transfer()) // Payment by bank transfer
);

// Add invoice line items from product catalog (by Good ID)
$invoice->addInvoiceContent(
    InvoicesContent::fromGoodId(
        GoodId::create(123),          // Product ID from wFirma goods catalog
        3,                            // Quantity
        123.32,                       // Unit price (net)
        23                            // VAT rate (23%)
    )
);

// Add invoice line items by name (ad-hoc items)
$invoice->addInvoiceContent(
    InvoicesContent::fromName(
        'Consulting Services',        // Item name/description
        'h',                          // Unit (hours)
        8,                            // Quantity (8 hours)
        150.00,                       // Unit price (net)
        23                            // VAT rate (23%)
    )
);

// Save the invoice to wFirma
$invoice = $api->add($invoice);

echo "Invoice created with ID: " . $invoice->id()->id();
echo "Invoice number: " . $invoice->number()->fullNumber();

```

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

### Find, FindAll, and Count Series

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

Use these methods to retrieve, iterate over, or count series based on optional parameters. Parameters can include conditions, ordering, pagination, and specific fields.

```php
<?php
use Webit\WFirmaSDK\Entity\Parameters\Parameters;
use Webit\WFirmaSDK\Entity\Parameters\Conditions;
use Webit\WFirmaSDK\Entity\Parameters\Order;
use Webit\WFirmaSDK\Entity\Parameters\Pagination;
use Webit\WFirmaSDK\Entity\Parameters\Fields;

$parameters = Parameters::findParameters(
    Conditions::or(
        Conditions::eq('name', 'FA/'),
        Conditions::gt('id', '20')
    ),
    Order::ascending("name")->thenDescending("created"), // optional - ordering
    Pagination::create(20, 2), // optional - limit, page no
    Fields::fromArray(["id", "name"]) // optional - subset of fields to select
);

$seriesApi = $apiFactory->seriesApi();

$series = $seriesApi->find($parameters); // returns array of 20 Series (page 2)

// returns EntityIterator, allows to iterate over all the matching Series loaded in batches of 20
$series = $seriesApi->findAll($parameters);
/**
* @var int $i
* @var \Webit\WFirmaSDK\Series\Series $seriesItem */
foreach ($series as $i => $seriesItem) {
    // do some stuff on ALL the matching elements
}

$seriesCount = $seriesApi->count($parameters); // return number of matching series

```

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

### Find, FindAll, and Count APIs

Source: https://github.com/dbojdo/wfirma/blob/master/README.md

APIs for finding, finding all, and counting entities. These methods accept an optional Parameters argument for filtering, ordering, and pagination.

```APIDOC
## Find / FindAll / Count APIs

### Description
APIs exposing `find` / `findAll` / `count` methods that take an optional `Parameters` argument for filtering, ordering, and pagination.

### Method
GET (for find/findAll), GET (for count)

### Endpoint
`/api/entities/{entityType}/find`
`/api/entities/{entityType}/findAll`
`/api/entities/{entityType}/count`

### Parameters
#### Query Parameters
- **Parameters** (Object) - Optional - An object containing filtering, ordering, and pagination criteria.
  - **Conditions** (Object) - Optional - Conditions for filtering.
  - **Order** (Object) - Optional - Ordering criteria.
  - **Pagination** (Object) - Optional - Pagination settings (limit, page number).
  - **Fields** (Array) - Optional - Subset of fields to select.

### Request Example
```php
<?php
use Webit\WFirmaSDK\Entity\Parameters\Parameters;
use Webit\WFirmaSDK\Entity\Parameters\Conditions;
use Webit\WFirmaSDK\Entity\Parameters\Order;
use Webit\WFirmaSDK\Entity\Parameters\Pagination;
use Webit\WFirmaSDK\Entity\Parameters\Fields;

$parameters = Parameters::findParameters(
    Conditions::or(
        Conditions::eq('name', 'FA/'),
        Conditions::gt('id', '20')
    ),
    Order::ascending("name")->thenDescending("created"), // optional - ordering
    Pagination::create(20, 2), // optional - limit, page no
    Fields::fromArray(["id", "name"]) // optional - subset of fields to select
);

$seriesApi = $apiFactory->seriesApi();

// Find series with parameters
$series = $seriesApi->find($parameters); // returns array of 20 Series (page 2)

// Find all series with parameters (iterates over all matching elements)
$series = $seriesApi->findAll($parameters);
/**
* @var int $i
* @var \Webit\WFirmaSDK\Series\Series $seriesItem */
foreach ($series as $i => $seriesItem) {
    // do some stuff on ALL the matching elements
}

// Count series matching parameters
$seriesCount = $seriesApi->count($parameters); // return number of matching series
?>
```

### Response
#### Success Response (200)
- **Array of Entities** (Array) - A list of entities matching the criteria.
- **Integer** (Integer) - The count of entities matching the criteria (for count API).

#### Response Example
```json
{
  "example": "[Array of entity objects or count integer]"
}
```
```

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

### Build Complex Search Parameters with PHP

Source: https://context7.com/dbojdo/wfirma/llms.txt

Construct sophisticated search parameters using a fluent API for filtering, ordering, and selecting fields. This is useful for precise data retrieval from various module APIs.

```php
<?php

use Webit\WFirmaSDK\Entity\Parameters\Parameters;
use Webit\WFirmaSDK\Entity\Parameters\Conditions;
use Webit\WFirmaSDK\Entity\Parameters\Order;
use Webit\WFirmaSDK\Entity\Parameters\Pagination;
use Webit\WFirmaSDK\Entity\Parameters\Fields;

// Build complex search parameters
$parameters = Parameters::findParameters(
    // Conditions: combine with AND/OR logic
    Conditions::and(
        Conditions::like('name', '%Corp%'),           // Name contains "Corp"
        Conditions::or(
            Conditions::eq('country', 'PL'),          // Country is Poland
            Conditions::eq('country', 'DE')           // OR country is Germany
        ),
        Conditions::ge('created', '2024-01-01'),      // Created on or after date
        Conditions::isNotNull('nip')                  // Has VAT ID
    ),
    Order::descending('created')                      // Order by created date DESC
        ->thenAscending('name'),                      // Then by name ASC
    Pagination::create(50, 1),                        // 50 items per page, page 1
    Fields::fromArray(['id', 'name', 'nip', 'city']) // Select specific fields only
);

// Use parameters with ContractorsApi
$contractors = $apiFactory->contractorsApi()->find($parameters);

foreach ($contractors as $contractor) {
    echo $contractor->name() . ' - ' . $contractor->nip() . "\n";
}

// Available condition operators:
// Conditions::eq($field, $value)      - Equal
// Conditions::ne($field, $value)      - Not equal
// Conditions::gt($field, $value)      - Greater than
// Conditions::lt($field, $value)      - Less than
// Conditions::ge($field, $value)      - Greater than or equal
// Conditions::le($field, $value)      - Less than or equal
// Conditions::like($field, $value)    - LIKE pattern match
// Conditions::notLike($field, $value) - NOT LIKE pattern match
// Conditions::isNull($field)          - IS NULL
// Conditions::isNotNull($field)       - IS NOT NULL
// Conditions::in($field, $values)     - IN array of values
// Conditions::not($condition)         - Negate condition

// Count matching records
$count = $apiFactory->contractorsApi()->count($parameters);
echo "Found " . $count . " contractors matching criteria";

```

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

### InvoicesApi - Managing Existing Invoices

Source: https://context7.com/dbojdo/wfirma/llms.txt

Methods to retrieve, edit, delete invoices, and perform specialized actions like downloading PDF, sending via email, and fiscal register operations.

```APIDOC
## InvoicesApi - Managing Existing Invoices

### Description
Methods to retrieve, edit, delete invoices, and perform specialized actions like downloading PDF, sending via email, and fiscal register operations.

### Methods

#### GET /invoices/{id}

##### Description
Retrieves an invoice by its unique identifier.

##### Endpoint
`/invoices/{id}`

##### Parameters
*   **id** (InvoiceId) - Required - The unique identifier of the invoice.

##### Response
*   **Invoice** (object) - The retrieved invoice object.

#### PUT /invoices/{id}

##### Description
Edits an existing invoice. This is typically used after modifying properties of an invoice object retrieved via `get()`.

##### Endpoint
`/invoices/{id}`

##### Parameters
*   **invoice** (Invoice) - Required - The invoice object with updated information.

##### Response
*   **Invoice** (object) - The updated invoice object.

#### POST /invoices/download/{id}

##### Description
Downloads an invoice in PDF format.

##### Endpoint
`/invoices/download/{id}`

##### Parameters
*   **id** (InvoiceId) - Required - The unique identifier of the invoice.
*   **DownloadParameters** (object) - Optional - Parameters to customize the download format.

##### Response
*   **FileContent** (string) - The content of the PDF file.

#### POST /invoices/send/{id}

##### Description
Sends an invoice via email.

##### Endpoint
`/invoices/send/{id}`

##### Parameters
*   **id** (InvoiceId) - Required - The unique identifier of the invoice.
*   **SendParameters** (object) - Optional - Parameters for sending the email.

##### Response
*   (No specific response body detailed, likely a success/failure indicator).

#### POST /invoices/fiscalise/{id}

##### Description
Fiscalizes an invoice, registering it with the fiscal system.

##### Endpoint
`/invoices/fiscalise/{id}`

##### Parameters
*   **id** (InvoiceId) - Required - The unique identifier of the invoice.

##### Response
*   (No specific response body detailed, likely a success/failure indicator).

#### POST /invoices/unfiscalise/{id}

##### Description
Unfiscalizes an invoice, removing it from the fiscal system.

##### Endpoint
`/invoices/unfiscalise/{id}`

##### Parameters
*   **id** (InvoiceId) - Required - The unique identifier of the invoice.

##### Response
*   (No specific response body detailed, likely a success/failure indicator).

#### DELETE /invoices/{id}

##### Description
Deletes an invoice by its unique identifier.

##### Endpoint
`/invoices/{id}`

##### Parameters
*   **id** (InvoiceId) - Required - The unique identifier of the invoice.

##### Response
*   (No specific response body detailed, likely a success/failure indicator).

#### POST /invoices

##### Description
Adds a new invoice. Can be created for an existing contractor.

##### Endpoint
`/invoices`

##### Parameters
*   **invoice** (Invoice) - Required - The invoice object to be added.

##### Request Body Example
```json
{
  "contractorId": {"id": 456},
  "payment": {"method": "cash"},
  "content": [
    {
      "name": "Product",
      "unit": "pcs",
      "quantity": 1,
      "price": 100.00,
      "vatRate": 23
    }
  ]
}
```

##### Response
*   **Invoice** (object) - The newly created invoice object.
```

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

### ContractorsApi - Managing Contractors

Source: https://context7.com/dbojdo/wfirma/llms.txt

Handles contractor (customer/supplier) management including creating, editing, and searching for business partners.

```APIDOC
## ContractorsApi - Managing Contractors

### Description
Handles contractor (customer/supplier) management including creating, editing, and searching for business partners.

### Methods

#### POST /contractors

##### Description
Creates a new contractor with specified details.

##### Endpoint
`/contractors`

##### Parameters
*   **contractor** (Contractor) - Required - The contractor object to be created.

##### Request Body Example
```json
{
  "companyName": "Tech Solutions Ltd",
  "alternativeName": "Tech Solutions",
  "vatId": "9876543210",
  "regon": "123456789",
  "invoiceAddress": {
    "street": "ul. Techniczna 5",
    "zipCode": "00-001",
    "city": "Krakow",
    "countryCode": "PL"
  },
  "contactAddress": null,
  "contactDetails": {
    "phone": "+48 123 456 789",
    "skype": "tech.solutions",
    "fax": "+48 123 456 780",
    "email": "contact@techsolutions.pl",
    "website": "https://techsolutions.pl"
  },
  "description": "Premium client",
  "isBuyer": true,
  "isSeller": false,
  "bankAccount": "PL12345678901234567890123456",
  "paymentSettings": {
    "paymentDays": 14,
    "defaultPaymentMethod": "transfer",
    "discountPercent": 5.0,
    "sendReminders": true
  }
}
```

##### Response
*   **Contractor** (object) - The newly created contractor object, including its ID.

#### GET /contractors/{id}

##### Description
Retrieves a contractor by their unique identifier.

##### Endpoint
`/contractors/{id}`

##### Parameters
*   **id** (ContractorId) - Required - The unique identifier of the contractor.

##### Response
*   **Contractor** (object) - The retrieved contractor object.

#### PUT /contractors/{id}

##### Description
Edits an existing contractor's details.

##### Endpoint
`/contractors/{id}`

##### Parameters
*   **contractor** (Contractor) - Required - The contractor object with updated information.

##### Response
*   **Contractor** (object) - The updated contractor object.

#### DELETE /contractors/{id}

##### Description
Deletes a contractor by their unique identifier.

##### Endpoint
`/contractors/{id}`

##### Parameters
*   **id** (ContractorId) - Required - The unique identifier of the contractor.

##### Response
*   (No specific response body detailed, likely a success/failure indicator).

#### GET /contractors/count

##### Description
Retrieves the total count of contractors.

##### Endpoint
`/contractors/count`

##### Response
*   **count** (integer) - The total number of contractors.
```