diff --git a/README.md b/README.md index b1431e9..567c8b5 100644 --- a/README.md +++ b/README.md @@ -8,28 +8,28 @@ ## Requirements -PHP: >= 8.1 -Extensions: +PHP: >= 8.1 +Extensions: - [Composer](https://getcomposer.org/) - [PHP-JSON](https://www.php.net/manual/en/book.json.php) - [PSR-18 HTTP-Client](https://packagist.org/providers/psr/http-client-implementation) ## Install -composer: +composer: `composer require sysix/lex-office-api` ## Usage -Search for the [official API Documentation](https://developers.lexoffice.io/docs/). +Search for the [official API Documentation](https://developers.lexoffice.io/docs/). You need an [API Key](https://app.lexoffice.de/addons/public-api) for that. ### Basic ```php // store keys in .env file -$apiKey = getenv('LEXOFFICE_API_KEY'); +$apiKey = getenv('LEXOFFICE_API_KEY'); -// in this example we are using guzzlehttp/guzzle package, it can be any PSR-18 HTTP Client +// in this example we are using guzzlehttp/guzzle package, it can be any PSR-18 HTTP Client // see: https://packagist.org/providers/psr/http-client-implementation $httpClient = \GuzzleHttp\Client(); $api = new \Sysix\LexOffice\Api($apiKey, $httpClient); @@ -37,13 +37,13 @@ $api = new \Sysix\LexOffice\Api($apiKey, $httpClient); ### Optimize your HTTP Client -This library only prepares the `\Psr\Http\Message\RequestInterface` for the HTTP Client and returns its Response. -There are almost no error checks, no caching and no rate limiting. Your PSR-18 HTTP Client should come with a way to deal with it. +This library only prepares the `\Psr\Http\Message\RequestInterface` for the HTTP Client and returns its Response. +There are almost no error checks, no caching and no rate limiting. Your PSR-18 HTTP Client should come with a way to deal with it. Here is a example with `guzzlehttp/guzzle` , `kevinrob/guzzle-cache-middleware` and `spatie/guzzle-rate-limiter-middleware`: ```php -$apiKey = getenv('LEXOFFICE_API_KEY'); +$apiKey = getenv('LEXOFFICE_API_KEY'); $stack = \GuzzleHttp\HandlerStack::create(); $stack->push(new \Kevinrob\GuzzleCache\CacheMiddleware(), 'cache'); @@ -72,7 +72,7 @@ $client->type = 'PRODUCT'; // get a page -$response = $client->getPage(0); +$response = $client->getPage(0); // other methods $response = $client->get($entityId); @@ -96,7 +96,7 @@ $client->customer = true; $client->vendor = false; // get a page -$response = $client->getPage(0); +$response = $client->getPage(0); // other methods $response = $client->get($entityId); @@ -118,9 +118,13 @@ $response = $api->creditNote()->create($data); $response = $api->creditNote()->create($data, true); // finalized $response = $api->creditNote()->pursue($precedingSalesVoucherId, $data); $response = $api->creditNote()->pursue($precedingSalesVoucherId, $data, true); // finalized +$response = $api->creditNote()->file($entityId); // get file content +$response = $api->creditNote()->file($entityId, 'application/xml'); // as XRechnung + +// deprecated methods: $response = $api->creditNote()->document($entityId); // get document ID $response = $api->creditNote()->document($entityId, true); // get file content -$response = $api->creditNote()->document($entityId, true, 'image/*'); // accept only images +$response = $api->creditNote()->document($entityId, true, 'application/xml'); // as XRechnung ``` ### Deliverys Notes Endpoint @@ -129,9 +133,11 @@ $voucherList = $api->deliveryNote()->getVoucherListClient(); // see VoucherlistC $response = $api->deliveryNote()->get($entityId); $response = $api->deliveryNote()->create($data); $response = $api->deliveryNote()->pursue($precedingSalesVoucherId, $data); +$response = $api->deliveryNote()->file($entityId); // get file content + +// deprecated methods: $response = $api->deliveryNote()->document($entityId); // get document ID $response = $api->deliveryNote()->document($entityId, true); // get file content -$response = $api->deliveryNote()->document($entityId, true, 'image/*'); // accept only images ``` ### Down Payment Invoices Endpoint @@ -139,18 +145,24 @@ $response = $api->deliveryNote()->document($entityId, true, 'image/*'); // accep $voucherList = $api->downPaymentInvoice()->getVoucherListClient(); // see VoucherlistClient Documentation $response = $api->downPaymentInvoice()->get($entityId); $response = $api->downPaymentInvoice()->create($data); +$response = $api->downPaymentInvoice()->file($entityId); // get file content +$response = $api->downPaymentInvoice()->file($entityId, 'application/xml'); // as XRechnung + +// deprecated methods: $response = $api->downPaymentInvoice()->document($entityId); // get document ID $response = $api->downPaymentInvoice()->document($entityId, true); // get file content -$response = $api->downPaymentInvoice()->document($entityId, true, 'image/*'); // accept only images +$response = $api->downPaymentInvoice()->document($entityId, true, 'application/xml'); // as XRechnung ``` ### Dunnings Endpoint ```php $response = $api->dunning()->get($entityId); $response = $api->dunning()->pursue($precedingSalesVoucherId, $data); +$response = $api->dunning()->file($entityId); // get file content + +// deprecated methods: $response = $api->dunning()->document($entityId); // get document ID $response = $api->dunning()->document($entityId, true); // get file content -$response = $api->dunning()->document($entityId, true, 'image/*'); // accept only images ``` ### Event Subscriptions Endpooint @@ -177,10 +189,13 @@ $response = $api->invoice()->create($data); $response = $api->invoice()->create($data, true); // finalized $response = $api->invoice()->pursue($precedingSalesVoucherId, $data); $response = $api->invoice()->pursue($precedingSalesVoucherId, $data, true); // finalized +$response = $api->invoice()->file($entityId); // get file content +$response = $api->invoice()->file($entityId, 'application/xml'); // as XRechnung + +// deprecated methods: $response = $api->invoice()->document($entityId); // get document ID $response = $api->invoice()->document($entityId, true); // get file content -$response = $api->invoice()->document($entityId, true, 'image/*'); // accept only images -$response = $api->invoice()->document($entityId, true, 'application/xml'); // get XRechung XML File (if possible) +$response = $api->invoice()->document($entityId, true, 'application/xml'); // as XRechung XML File ``` ### Order Confirmation Endpoint @@ -189,9 +204,11 @@ $voucherList = $api->orderConfirmation()->getVoucherListClient(); // see Voucher $response = $api->orderConfirmation()->get($entityId); $response = $api->orderConfirmation()->create($data); $response = $api->orderConfirmation()->pursue($precedingSalesVoucherId, $data); +$response = $api->orderConfirmation()->file($entityId); // get file content + +// deprecated methods: $response = $api->orderConfirmation()->document($entityId); // get document ID $response = $api->orderConfirmation()->document($entityId, true); // get file content -$response = $api->orderConfirmation()->document($entityId, true, 'image/*'); // accept only images ``` ### Payment Endpoint @@ -225,9 +242,11 @@ $voucherList = $api->quotation()->getVoucherListClient(); // see VoucherlistClie $response = $api->quotation()->get($entityId); $response = $api->quotation()->create($data); $response = $api->quotation()->create($data, true); // finalized +$response = $api->quotation()->file($entityId); // get file content + +// deprecated methods: $response = $api->quotation()->document($entityId); // get document ID $response = $api->quotation()->document($entityId, true); // get file content -$response = $api->quotation()->document($entityId, true, 'image/*'); // accept only images ``` ### Recurring Templates Endpoint @@ -252,10 +271,6 @@ $response = $api->recurringTemplate()->get($entityId); $response = $api->voucher()->get($entityId); $response = $api->voucher()->create($data); $response = $api->voucher()->update($entityId, $data); -$response = $api->voucher()->document($entityId); // get document ID -$response = $api->voucher()->document($entityId, true); // get file content -$response = $api->voucher()->document($entityId, true, 'image/*'); // accept only images -$response = $api->voucher()->document($entityId, true, 'application/xml'); // get XRechung XML File (if possible) $response = $api->voucher()->upload($entitiyId, $filepath); ``` @@ -304,7 +319,7 @@ $client->updatedDateTo = new \DateTime('2023-12-01'); $response = $client->getPage(0); ``` -## Utils +## Utils ### get JSON from Success and Error Response