Lexware-php-api

2020-10-20T19:04:44Z

Fcu: added create_creditnote

= Übersicht & Informationen =

PHP Client für [https://www.awin1.com/awclick.php?gid=368497&mid=13787&awinaffid=635216&linkid=2440770&clickref= Lexoffice] REST API

Wir lieben Automatisierung und die nahtlose Verzahnung von Systemen!

[https://www.awin1.com/awclick.php?gid=368497&mid=13787&awinaffid=635216&linkid=2440770&clickref= Lexoffice] stellt seinen Kunden eine öffentliche API-Schnittstelle zur Verfügung über die bestehende Systeme integriert oder Prozesse automatisiert werden können.<br>
Für diesen Ansatz haben wir einen PHP-Client entwickelt und stellen diesen kostenfrei zur Verfügung.

Alle weiteren Informationen finden Sie auf unserer [https://www.baebeca.de/softwareentwicklung/projekte/lexoffice-php-client/ Projektseite].

== Baebeca Solutions bei lexoffice.de ==
* lexoffice [https://www.lexoffice.de/partner/public-api/integrationspartner/ Integrationspartner]
* lexoffice [https://www.lexoffice.de/partner/ Softwarepartner]
* Offizielle Lexoffice [https://developers.lexoffice.io/docs/ API-Dokumentation]

[[Datei:Lexoffice logo.png||link=https://www.awin1.com/cread.php?s=2440752&v=13787&q=368492&r=635216]]

== Download ==
Die aktuelle Version können Sie jeweils in unserem Github Repository herunterladen: https://github.com/Baebeca-Solutions/lexoffice-php-api

== Lizenz ==
Unsere Software wurde unter der "GNU Affero General Public License v3.0" Lizenz veröffentlicht.
Dies bedeutet, dass Sie unsere Software gerne in Ihren Projekten und Produkten nutzen dürfen,
solange Sie Ihr Projekt dann ebenso Quelloffen unter den in der Lizenz genannten Rahmenbedingungen
zur Verfügung stellen.

Wenn Sie Ihre Lösung nicht veröffentlichen möchten, Support benötigen, individuelle
Erweiterungen benötigen oder dieses Projekt einfach Unterstützen möchten, können Sie für 99,- EUR/Netto eine lifetime Nutzungslizenz erhalten. Setzten Sie sich diesbezüglich bitte kurz mit uns in [https://www.baebeca.de/softwareentwicklung/projekte/lexoffice-php-client/ Verbindung].

== Support ==
An wen kann ich mich wenden, wenn ich Probleme oder Fragen habe?<br>
Für diese Frage ist entscheidend, ob Sie eine Nutzungslizenz für unsere lexoffice-php-api erworben haben oder die kostenlose Variante nutzen.

* Sofern eine Nutzungslizenz vorhanden ist, können sich jederzeit per Mail an [mailto:support@baebeca.de support@baebeca.de] wenden und erhalten vorrangigen Support.
* Wenn Sie die kostenlose Version nutzen bitten wir Sie auf Github einen [https://github.com/Baebeca-Solutions/lexoffice-php-api/issues issue] zu erstellen.

== Lexoffice API Account erstellen ==
Erstellen Sie in Ihrem [https://www.awin1.com/awclick.php?gid=368497&mid=13787&awinaffid=635216&linkid=2440770&clickref= Lexoffice Account] einen API Key.

Einstellungen :: Erweiterungen :: lexoffice Public API :: "Schlüssel neu erstellen"

== Mehrwertsteuersenkung - Konjunkturpaket 01.07.2020 - 31.12.2020 ==
* https://www.lexoffice.de/mehrwertsteuer-rest-api/
* https://developers.lexoffice.io/docs/#faq-valid-tax-rates

= Klasse einbinden =
<syntaxhighlight lang="php">
// include the class file, check the correct folder
require_once (__DIR__.'/lexoffice-php-api.php');

// initiate client with your settings
$lexoffice = new lexoffice_client(array(
'api_key' => 'xyz',
));
</syntaxhighlight>
== Start Parameter ==
;api_key [string]
:API Schlüssel
;callback [string]
:Ihre Standard Callback URL für Webhooks von Lexoffice
;ssl_verify [bool] (default true)
:Soll die SSL verbindung zu Lexoffice validiert werden

= Methoden =

== Account ==

=== Account abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_profile() : object</syntaxhighlight>

Beispiel Rückgabe:
<syntaxhighlight lang="json">
{
"organizationId": "42b1fbdd-c4e0-4bb4-8c20-1d3d0b9432e8",
"companyName": "Testfirma GmbH",
"created": {
"userName": "Frau Erika Musterfrau",
"userEmail": "erika.musterfrau@testfirma.de",
"date": "2017-01-03T13:15:45+0100"
},
"connectionId": "3dea098a-fae5-4458-a85c-f97965966c25",
"features": [
"cashbox"
],
"subscriptionStatus": "active",
"taxType": "net",
"isSmallBusiness": false
}
</syntaxhighlight>

== Rechnungen ==

=== Rechnung abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_invoice( string $uuid ) : object</syntaxhighlight>
;uuid
:Die eindeutige uuid des Eintrages der abgefragt werden soll

=== Alle Rechnungen abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_invoices_all() : object</syntaxhighlight>

=== Die letzten n Rechnungen abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_last_invoices(int $count) : object</syntaxhighlight>

=== Rechnung PDF herunterladen ===

'''legacy function - will be removed in futere releases, use ''get_pdf($type, $uuid, $filename)'' instead'''

<syntaxhighlight lang="php">$lexoffice->get_invoice_pdf( string $uuid, string $filename) : bool</syntaxhighlight>
;uuid
:Die eindeutige uuid des Eintrages der abgefragt werden soll
;filename
:Der lokale Dateiname an dem das PDF abgelegt werden soll

=== Rechnung anlegen ===
<syntaxhighlight lang="php">$lexoffice->create_invoice( array $data [, bool $finalized = false ] ) : object</syntaxhighlight>
;data
:Ein Array der Rechnungsdaten nach der nötigen [https://developers.lexoffice.io/docs/#invoices-properties Lexoffice Formatierung]
:Beispiel
<syntaxhighlight lang="php">
array(
'voucherDate' => substr(date('c'), 0, 19).'.000'.substr(date('c'), 19),
'introduction' => 'Einleitungstext',
'remark' => "Fußzeile\r\nMehrzeilig",
'address' => array(
#'contactId' => '<id>',
'name' => 'Frau Jane Doe',
'street' => 'Str. 1',
'zip' => '12345',
'city' => 'Stadt',
'countryCode' => 'DE',
),
'lineItems' => array(
array(
'type' => 'custom',
'name' => 'Produktname',
'description' => 'Beschreibung',
'quantity' => 1,
'unitName' => 'Stück',
'unitPrice' => array(
'currency' => 'EUR',
'netAmount' => 10.99,
'taxRatePercentage' => 19,
),
#'discountPercentage' => 0,
),
),
'totalPrice' => array(
'currency' => 'EUR',
#'totalDiscountAbsolute' => 0,
#'totalDiscountPercentage' => 0,
),
'taxConditions' => array(
'taxType' => 'net',
),
'shippingConditions' => array(
'shippingDate' => date('Y-m-d').'T00:00:01.000+02:00',
'shippingType' => 'delivery',
),
'paymentConditions' => array(
'paymentTermLabel' => 'Vorkasse',
'paymentTermDuration' => 1,
),
)
</syntaxhighlight>
; finalized
: Entscheidet ob die Rechnung fertiggestellt werden soll.

== Gutschriften ==

=== Gutschrift abfragen ===

<syntaxhighlight lang="php">$lexoffice->get_creditnote( string $uuid ) : object</syntaxhighlight>
;uuid
:Die eindeutige uuid der Gutschrift die abgefragt werden soll

=== Gutschrift Anlegen ===

<syntaxhighlight lang="php">$lexoffice->create_creditnote( array $data [, bool $finalized = false ] ) : object</syntaxhighlight>
;data
:Ein Array der Gutschriftsdaten nach der nötigen [https://developers.lexoffice.io/docs/#credit-notes-endpoint-credit-notes-properties Lexoffice Formatierung]
:Beispiel
<syntaxhighlight lang="php">
array(
'voucherDate' => substr(date('c'), 0, 19).'.000'.substr(date('c'), 19),
'introduction' => 'Rechnungskorrektur',
'remark' => "Fußzeile\r\nMehrzeilig",
'address' => array(
#'contactId' => '<id>',
'name' => 'Frau Jane Doe',
'street' => 'Str. 1',
'zip' => '12345',
'city' => 'Stadt',
'countryCode' => 'DE',
),
'lineItems' => array(
array(
'type' => 'custom',
'name' => 'Produktname',
'description' => 'Beschreibung',
'quantity' => 1,
'unitName' => 'Stück',
'unitPrice' => array(
'currency' => 'EUR',
'netAmount' => 10.99,
'taxRatePercentage' => 19,
),
#'discountPercentage' => 0,
),
),
'totalPrice' => array(
'currency' => 'EUR',
#'totalDiscountAbsolute' => 0,
#'totalDiscountPercentage' => 0,
),
'taxConditions' => array(
'taxType' => 'net',
)
)
</syntaxhighlight>
; finalized
: Entscheidet ob die Gutschrift fertiggestellt werden soll.

== Angebote ==

=== Angebot abfragen ===

<syntaxhighlight lang="php">$lexoffice->get_quotation( string $uuid ) : object</syntaxhighlight>
;uuid
:Die eindeutige uuid des Angebotes das abgefragt werden soll

== Auftragsbestätigungen ==

=== Auftragsbestätigung abfragen ===

<syntaxhighlight lang="php">$lexoffice->get_orderconfirmation( string $uuid ) : object</syntaxhighlight>
;uuid
:Die eindeutige uuid der Auftragsbestätigung die abgefragt werden soll

=== Auftragsbestätigung anlegen ===
<syntaxhighlight lang="php">$lexoffice->create_orderconfirmation( array $data ) : object</syntaxhighlight>
;data
:Ein Array der Auftragsbestätigungsdaten nach der nötigen [https://developers.lexoffice.io/docs/#invoices-properties Lexoffice Formatierung]
:Beispiel
<syntaxhighlight lang="php">
array(
'voucherDate' => substr(date('c'), 0, 19).'.000'.substr(date('c'), 19),
'introduction' => 'Einleitungstext',
'remark' => "Fußzeile\r\nMehrzeilig",
'address' => array(
#'contactId' => '<id>',
'name' => 'Frau Jane Doe',
'street' => 'Str. 1',
'zip' => '12345',
'city' => 'Stadt',
'countryCode' => 'DE',
),
'lineItems' => array(
array(
'type' => 'custom',
'name' => 'Produktname',
'description' => 'Beschreibung',
'quantity' => 1,
'unitName' => 'Stück',
'unitPrice' => array(
'currency' => 'EUR',
'netAmount' => 10.99,
'taxRatePercentage' => 19,
),
#'discountPercentage' => 0,
),
),
'totalPrice' => array(
'currency' => 'EUR',
#'totalDiscountAbsolute' => 0,
#'totalDiscountPercentage' => 0,
),
'taxConditions' => array(
'taxType' => 'net',
),
'shippingConditions' => array(
'shippingDate' => date('Y-m-d').'T00:00:01.000+02:00',
'shippingType' => 'delivery',
),
'paymentConditions' => array(
'paymentTermLabel' => 'Vorkasse',
'paymentTermDuration' => 1,
),
)
</syntaxhighlight>

== Belege ==

=== Beleg anlegen ===
<syntaxhighlight lang="php">$lexoffice->create_voucher( array $data ) : object</syntaxhighlight>
;Paramater
;data
:Ein Array der Belegdaten nach der nötigen [https://developers.lexoffice.io/docs/#vouchers-endpoint-create-a-voucher Lexoffice Formatierung]

=== Beleg abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_voucher( string $uuid ) : object</syntaxhighlight>
;Paramater
*uuid
**Die eindeutige uuid des Beleges der abgefragt werden soll

=== Belege abfragen ===

<syntaxhighlight lang="php">$lexoffice->get_vouchers( string $type = 'invoice,creditnote,orderconfirmation', string $state = 'draft,open,paid,paidoff,voided,transferred', string $archived = 'both') : object</syntaxhighlight>
;type
:Einen oder mehrere Typen von Belegen (komma getrennt) die abgefragt werden sollen
;state
:Status der Belege die abgefragt werden sollen
;archived
:"both", "true" oder "false" als String ob archivierte/nicht archivierte Belege ausgegeben werden sollen

=== Belegbild hochladen (nicht zugeordnet) ===
<syntaxhighlight lang="php">$lexoffice->upload_file($file) : object</syntaxhighlight>
;Parameter
*file
**Der Pfad zur Datei die hochgeladen werden soll
; Rückgabe
* id
** Die eindeutige Datei-ID von lexoffice

;Beispiel Anfrage
<syntaxhighlight lang="php">
$lexoffice->upload_file(__DIR__.'/invoice.pdf');
</syntaxhighlight>

;Beispiel Rückgabe
<syntaxhighlight lang="php">
stdClass Object (
[id] => 221fd5ed-5547-4bd3-b7c2-9796c1a0e4a6
)
</syntaxhighlight>

=== Beleg hochladen (zugeordnet) ===
<syntaxhighlight lang="php">$lexoffice->upload_voucher($uuid, $file) : object</syntaxhighlight>
;Parameter
*uuid
**Die ID des Beleges dem der Upload zugeordnet werden soll
*file
**Der Pfad zur Datei die hochgeladen werden soll
; Rückgabe
* id
** Die eindeutige Datei-ID von lexoffice

=== Beleg Dateien herunterladen ===
<syntaxhighlight lang="php">$lexoffice->get_voucher_files(string $uuid, string $filename_prefix) : array</syntaxhighlight>
;Parameter
*uiui
**Die ID des Beleges dessen Dateien heruntergeladen werden sollen
*filename_prefix
** Der Dateipfad inkl. eines Dateiprefixes.
; Rückgabe
Ein Array der Dateinamen

;Beispiel Anfrage
<syntaxhighlight lang="php">
$lexoffice->get_voucher_files($uuid, '/files/IN_1234');
</syntaxhighlight>

;Beispiel Rückgabe
<syntaxhighlight lang="php">
array (
[0] => /files/IN_1234_1.jpg
[1] => /files/IN_1234_2.png
[2] => /files/IN_1234_3.pdf
)
</syntaxhighlight>

== Kontakte ==

=== Kontakt abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_contact( string $uuid ) : object</syntaxhighlight>
;Paramater
*uuid
**Die eindeutige uuid des Eintrages der abgefragt werden soll

=== Kontakt suchen ===
<syntaxhighlight lang="php">$lexoffice->search_contact( array $filter ) : object</syntaxhighlight>
;Paramater
*filter
**Array bestehend aus den möglichen Filtern. Mehere Filter werden mit einem ''UND'' verknüpft.
*** email (mindestens 3 Zeichen)
*** name (mindestens 3 Zeichen)
*** number
*** customer (true/false)
*** vendor (true/false)
;Beispiel Anfrage
<syntaxhighlight lang="php">
$lexoffice->search_contact(array(
'email' => '',
'name' => 'John Doe',
'number' => '',
'customer' => '',
'venodr' => '',
));
</syntaxhighlight>

=== Alle Kontakte abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_contacts_all() : object</syntaxhighlight>

=== Kontakt anlegen ===
<syntaxhighlight lang="php">$lexoffice->create_contact( array $data) : object</syntaxhighlight>
;Parameter
*data
**Ein Array der Kontaktdaten nach der nötigen [https://developers.lexoffice.io/docs/#contact-properties Lexoffice Formatierung]

;Beispiel Anfrage
<syntaxhighlight lang="php">
$lexoffice->create_contact(array(
'version' => 0,
'roles' => array(
'customer' => array(
'number' => '',
),
),
'company' => array(
'name' => 'Baebeca Solutions GmbH',
'street' => 'Genklerhardt 6',
'zip' => '51647',
'city' => 'Gummersbach',
'countryCode' => 'DE',
'contactPersons' => array(
array(
'salutation' => 'Herr',
'firstName' => 'Jon',
'lastName' => 'Doe',
'emailAddress' =>'support@baebeca.de',
'phoneNumber' => '022619202930',
)
),
),
'addresses' => array(
'billing' => array(
array(
'street' => 'Genklerhardt 6',
'zip' => '51647',
'city' => 'Gummersbach',
'countryCode' => 'DE',
),
),
'shipping' => array(
array(
'street' => 'Genklerhardt 6',
'zip' => '51647',
'city' => 'Gummersbach',
'countryCode' => 'DE',
),
),
),
'emailAddresses' => array(
'business' => array(
'support@baebeca.de'
),
),
'phoneNumbers' => array(
'business' => array(
'022619202930'
),
),
'note' => '',
));
</syntaxhighlight>

=== Kontakt aktualisieren ===
<syntaxhighlight lang="php">$lexoffice->update_contact( string $uuid, array $data) : object</syntaxhighlight>
;Parameter
*uuid
**Die eindeutige uuid des Eintrages der abgefragt werden soll
*data
**Ein Array der Kontaktdaten nach der nötigen [https://developers.lexoffice.io/docs/#contact-properties Lexoffice Formatierung]

== Events / Webhooks ==

=== Event anlegen ===
<syntaxhighlight lang="php">$lexoffice->create_event( string $event [, bool $callback = false ] ) : array|bool</syntaxhighlight>
;event
:Mögliche sind alle von Lexoffice [https://developers.lexoffice.io/docs/#event-subscriptions-endpoint-event-types angebotenen Events].
;callback
:Die Callback URL für diesen Aufruf. Wenn keine angegeben wird, wird die Standard URL aus der initialisierung genutzt.

=== Aktives Event abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_event( string $uuid ) : array</syntaxhighlight>
;uuid
:Die eindeutige uuid des Eintrages der abgefragt werden soll

=== Alle aktiven Events abfragen ===
<syntaxhighlight lang="php">$lexoffice->get_events_all() : object</syntaxhighlight>

=== Event löschen ===
<syntaxhighlight lang="php">$lexoffice->delete_event( string $iiud ) : object</syntaxhighlight>
;uuid
:Die ID eines zuvor erstellten Events.

== Sonstiges ==

=== PDFs herunterladen ===

<syntaxhighlight lang="php">$lexoffice->get_pdf( string $type, string $uuid, string $filename) : bool</syntaxhighlight>
;type
:Die Art des Beleges. Möglich Varianten sind: "invoices", "credit-notes"
;uuid
:Die eindeutige uuid des Eintrages der abgefragt werden soll
;filename
:Der lokale Dateiname an dem das PDF abgelegt werden soll

= Webhook Anfragen =

Wir liefern eine ''callback.php'' mit, die als callback URL angegeben werden kann.
Bei allen Aufrufen wird die ''X-Lxo-Signature'' überprüft und sichergestellt, dass der Aufruf wirklich von einem lexoffice Server erstellt wurde.

= Error Handling =
Alle Methoden sollten stets in einem try/catch Block verwendet werden.<br>
Unser Client bietet eine erweiterte Execption Klasse, die via "$e->get_error()" sofern vorhanden weitere Details zur Anfrage und dem API Response zurück gibt.

Beispiel: Versuch eines PDF Downloads von einer nicht fertig gestellten Rechnung

<syntaxhighlight lang="php" highlight="3,7">
try {
$lexoffice->get_invoice_pdf('7f0f0f7f-dd61-4bf7-a9f7-a67b0530c7e9', 'test.pdf');
} catch (lexoffice_exception $e) {
echo $e->getMessage();
// lexoffice-php-api: error in api request - check details via $e->get_error()

print_r($e->get_error());
/*
Array (
[HTTP Status] => 500
[Requested URI] => https://api.lexoffice.io/v1/invoices/7f0f0f7f-dd61-4bf7-a9f7-a67b0530c7e9/document
[Requested Payload] =>
[Response] => stdClass Object
(
[timestamp] => 2019-11-20T17:34:53.360+01:00
[status] => 500
[error] => Internal Server Error
[path] => /v1/invoices/7f0f0f7f-dd61-4bf7-a9f7-a67b0530c7e9/document
[traceId] => f9f241666675
[message] => A technical error has occurred that is not specified in more detail.
)
)
*/
}
</syntaxhighlight>

Baebeca Solutions GmbH - Wiki - Benutzerbeiträge [de]

Lexware-php-api