faktura.work HTTPS API (JSON)
Authentifizierung
Die Authentifizierung erfolgt über einen x-api-key. Diese können im Admin Zugang zu faktura.work für die jeweilige Instanz erstellt werden. Der x-api-key wird im Header übergeben.
x-api-key: xxxIn den Einstellungen der jeweiligen faktura.work Instanz ist es zudem möglich, die API Requests auf bestimmte IP-Adressen (IPv4, IPv6) zu begrenzen.
HTTP Response Status Codes
In der jeweiligen Response wird ein HTTP Response Status Code mitgegeben. Auf Basis von diesem Status Code kann das Ergebnis überprüft werden. Es werden von der API die folgenden Kategorien an Status Codes übermittelt:
2xx Erfolg (z.B. 200 OK)
4xx Fehler durch Client (z.B. 400 BAD REQUEST)
5xx Fehler durch Server (z.B. 5xx INTERNAL SERVER ERROR)
Wichtiger Hinweis: Wir werden die Status Codes in Zukunft exakter spezifizieren, d.h. einige aktuell mit „200 OK“ beantwortete Requests (z.B. bei der Anlage eines Kunden) durch den detailierteren Code aus 2xx ersetzen (z.B. 201 CREATED bei der Anlage eines Kunden). Wir empfehlen Ihnen daher, Prüfungen auf Code 200 OK bereits auf 2xx in Ihren Implementierungen zu prüfen.
Weitere Informationen zu den Status Codes finden Sie unter https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200.
Kunden
Sie können über die API neue Kunden erstellen. In der Response wird Ihnen die ID des entsprechenden Kunden mitgeteilt, um für diesen Folgeaktionen (zum Beispiel die Erstellung einer Rechnung durchführen zu können.
Die ID des entsprechenden Kunden wird auch in der Response übergeben, wenn der zu erstellende Kunde bereits existiert hat. Schlüssel sind hierbei Name des Kunden und die E-Mail Adresse.
Kunden anlegen
POST https://demo.faktura.work/index.php/api/Clients/createx-api-key: xxx{
"client_active":1,
"client_name":"test test",
"client_surname":"",
"client_language":"system",
"client_number":"",
"client_invoices_comment":"Du zahlst per SEPA-Lastschrift. Den Rechnungsbetrag ziehen wir wie vereinbart von deiner Bankverbindung ein.",
"client_invoices_due_after":7,
"client_comment":"Created with API",
"client_address_1":"",
"client_address_2":"",
"client_zip":"",
"client_city":"",
"client_state":"",
"client_country":"DE",
"client_phone":"",
"client_fax":"",
"client_mobile":"",
"client_email":"test@whitedata.de",
"client_web":"",
"client_sepa_mndtId":"",
"client_sepa_dtOfSgntr":"",
"client_sepa_dbtr":"Testkonto Lastschrift",
"client_sepa_iban":"DE68721516500008252405",
"client_sepa_bic":"",
"client_sepa_sequence":1,
"client_vat_id":"",
"client_tax_code":1,
"client_gender":0,
"client_birthdate":""
}Response (Kunde wurde angelegt):
200 OK{
"data":{
"id":"5142",
"name":"test test",
"message":"Client has been created"
}
}Response (Kunde existiert bereits):
500 Internal Server Error{
"error":{
"code":500,
"message":"Client already exists.",
"data":{
"id":"5141"
}
},
"data":{
"id":"5141"
}
}Rechnungen
Die API unterstützt die Erstellung von Rechnungen und die Abfrage von existierenden Rechnungen anhand der ID der entsprechenden Rechnung.
Beispiel-Request zur Anlage einer Rechnung
POST https://demo.faktura.work/index.php/api/invoices/createx-api-key: xxx{
"client_id":"5143",
"number_range_id":2,
"user_id":1,
"invoice_date_created":"2023-01-04",
"invoice_password":"",
"invoice_date_due":"2023-01-11",
"invoice_status_id":1,
"items":[
{
"item_id":"",
"item_product_id":"",
"item_task_id":"",
"item_name":"Musterartikel",
"item_quantity":1,
"item_price":21,
"item_discount_amount":"",
"item_description":"Musterartikel Beschreibung",
"item_product_unit_id":"",
"item_order":1
}
],
"invoice_discount_amount":"",
"invoice_discount_percent":"",
"invoice_terms":"Du hast dich für die Zahlung per PayPal entschieden.",
"payment_method":4,
"invoice_account":"",
"invoice_tax_rate_id":"",
"invoice_year_estg":"",
"invoice_intro":"Lieber Kunde, wir bedanken uns für deinen Kauf. Hier findest du deinen Beleg."
}Response
200 OK{
"data":{
"status":200,
"id":"5548",
"message":"Invoice has been created"
}
}Rechnung abfragen
GET https://demo.faktura.work/index.php/api/invoices/get/5548x-api-key: xxxResponse
200 OK{
"quote_id":null,
"invoice_id":"5548",
"user_id":"1",
"client_id":"5142",
"number_range_id":"2",
"invoice_group_id":null,
"quote_status_id":null,
"quote_date_created":null,
"quote_date_modified":null,
"quote_date_expires":null,
"quote_number":null,
"quote_discount_amount":null,
"quote_discount_percent":null,
"quote_url_key":null,
"quote_password":null,
"notes":null,
"quote_intro":null,
"user_gln":null,
"user_rcc":null,
"client_date_created":"2023-01-04 22:34:53",
"client_date_modified":"2023-01-04 22:34:53",
"client_name":"test test",
"client_address_1":"",
"client_address_2":"",
"client_city":"",
"client_state":"",
"client_zip":"",
"client_country":"DE",
"client_phone":"",
"client_fax":"",
"client_mobile":"",
"client_email":"test@whitedata.de",
"client_web":"",
"client_vat_id":"",
"client_tax_code":"1",
"client_language":"system",
"client_active":"1",
"client_surname":"",
"client_avs":null,
"client_insurednumber":null,
"client_veka":null,
"client_birthdate":"0000-00-00",
"client_gender":"0",
"client_number":"60142",
"client_comment":"API created",
"client_sepa_mndtId":"",
"client_sepa_dtOfSgntr":"0000-00-00",
"client_sepa_bic":"",
"client_sepa_dbtr":"Testkonto Lastschrift",
"client_sepa_iban":"DE68721516500008252405",
"client_sepa_sequence":"1",
"client_invoices_due_after":"7",
"client_invoices_comment":"Du zahlst per SEPA-Lastschrift. Den Rechnungsbetrag ziehen wir wie vereinbart in 7 Tagen zum oben genannten F\u00e4lligkeitsdatum von deiner Bankverbindung ein.",
"sumex_id":null,
"sumex_invoice":null,
"sumex_reason":null,
"sumex_diagnosis":null,
"sumex_observations":null,
"sumex_treatmentstart":null,
"sumex_treatmentend":null,
"sumex_casedate":null,
"sumex_casenumber":null,
"invoice_amount_id":"5548",
"invoice_item_subtotal":"21.0000",
"invoice_item_tax_total":"0.0000",
"invoice_tax_total":"3.9900",
"invoice_total":"24.99",
"invoice_paid":"0.00",
"invoice_balance":"24.99",
"invoice_sign":"1",
"is_overdue":"0",
"days_overdue":"-7",
"invoice_is_recurring":"0",
"invoice_status_id":"1",
"is_read_only":null,
"invoice_password":"",
"invoice_date_created":"2023-01-04",
"invoice_time_created":"00:00:00",
"invoice_date_modified":"2023-01-04 22:55:48",
"invoice_date_due":"2023-01-11",
"invoice_number":"KP215548",
"invoice_discount_amount":"0.00",
"invoice_discount_percent":"0.00",
"invoice_terms":"Du zahlst per SEPA-Lastschrift. Den Rechnungsbetrag ziehen wir wie vereinbart von deiner Bankverbindung ein.",
"invoice_url_key":"nEoLjWGwDd5bNQ1",
"payment_method":"2",
"creditinvoice_parent_id":null,
"invoice_account":"4000",
"invoice_account_tax":"",
"invoice_posting_key":"",
"invoice_dunning_level":"0",
"invoice_dun_date":"0000-00-00",
"invoice_year_estg":"0",
"invoice_intro":"Lieber Kunde, wir bedanken uns für deinen Kauf. Hier findest du deinen Beleg.",
"invoice_sepa_debit_sent":"0",
"invoice_tax_rates":[
{
"invoice_tax_rate_name":"Umsatzsteuer normal (19%)",
"invoice_tax_rate_percent":"19.00",
"invoice_tax_rate_id":"5774",
"invoice_id":"5548",
"tax_rate_id":"1",
"include_item_tax":"0",
"invoice_tax_rate_amount":"3.99"
}
]
}