ProSonata API
Folgende HTTP-Methoden stehen für Angebote zur Verfügung:
Zugriff ab Benutzergruppe Teamleiter.
GET /api/v1/invoices
Antwort:
{
"meta": {
"status": 200,
"perPage": 100,
"page": 1,
"totalCount": 287,
"requestUserID": 1,
"requestUsername": "Admin1",
"usergroupName": "Administrator",
"apiLimitRemaining": 458,
"apiLimitReset": 751
},
"data": [
{
"invoiceID": 61,
"invoiceNo": "22-00001",
"invoiceNoAddition": "",
"invoiceName": "",
"invoiceHeadline": "",
"invoiceType": "Rechnung",
"invoiceDate": "2022-07-15",
"dateStart": "2022-11-22",
"dateEnd": "2022-12-21",
"freeServicePeriod": "",
"netValue": "3550.00",
"grossValue": "4224.50",
"currency": 0,
"tax": "19.0",
...
},
...
]
}
Über Parameter kann gefiltert werden:
GET /api/v1/invoices?projectName=Testprojekt
| Parameter | Beschreibung |
|---|---|
| addressID | ID der Kundenadresse |
| name1 | Firmierung des Kunden (Zeile 1 der Adresse) |
| invoiceType | Dokumenttyp 0 = Rechnung/Storno/Rechnungskorrektur 1 = Anzahlungsrechnung 2 = Abschlagsrechnung 3 = Endrechnung |
| projectID | ID des Projekts |
| projectNo | Projektnummer |
| projectName | Bezeichnung des Projekts |
| projectTags | Tag(s) des Projekts |
| customerID | ID des Kunden (Firma/Gruppe) |
| customerName | Bezeichnung des Kunden (Firma/Gruppe) |
| invoiceNo | Nummer der Rechnung |
| invoiceDate | Datum des Dokuments durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen |
| createdByUserID | Dokument angelegt von Benutzer ID |
| currency | Währung: 0 = Euro 1 = CHF 2 = USD 3 = GBP 4 = CAD |
| reverseCharge | Reverse Charge (Rechnungsempfänger ist steuerpflichtig): 0 = nein 1 = ja |
| paymentDate | Bezahldatum des Dokuments durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen |
| sepaExport | in SEPA Export exportiert: 0 = nein 1 = ja |
| datevExport | FiBu Export ist erfolgt: 0 = nein 1 = ja |
| isDraft | Rechnungsentwürfe: 0 = nein 1 = ja |
Nach folgenden Parametern kann sortiert werden (Sortierrichtung ggf. mit ASC bzw. DESC ergänzen):
invoiceID, projectID, addressID, invoiceNo, invoiceDate, grossValue
GET /api/v1/invoices/{id}
Antwort:
{
"meta": {
"status": 200,
"requestUserID": 1,
"requestUsername": "Admin1",
"usergroupName": "Administrator",
"apiLimitRemaining": 484,
"apiLimitReset": 412
},
"data": {
"invoiceID": 304,
"invoiceNo": "22-0007",
"invoiceNoAddition": "",
"invoiceName": "",
"invoiceHeadline": "",
"invoiceType": "Rechnung",
"invoiceDate": "2022-07-15",
"dateStart": "2022-11-22",
"dateEnd": "2022-12-21",
"freeServicePeriod": "",
"netValue": "5281.00",
"grossValue": "6284.39",
"currency": 0,
"tax": "19.0",
"multipleTaxes": 0,
"invoiceDunningStatus": 0,
"paymentTargetDate": "2022-07-22",
"paymentDate": null,
"cashDiscountRate": "2.0",
"paidCashDiscount": 0,
"cancelInvoiceID": null,
"isSent": 0,
"sepaExport": 0,
"datevExport": 0,
"invoiceComments": "",
"projectID": 311,
"projectNo": "22-10-001",
"projectNoAddition": "",
"projectName": "Microsite Unfallversicherung",
"projectTags": "",
"projectGroupID": null,
"customerID": 10,
"customerName": "ABC Versicherung Hamburg",
"addressID": 36,
"name1": "ABC Versicherung AG",
"name2": "",
"name3": "",
"street": "Teststraße",
"streetNo": "12",
"postalCode": "12345",
"city": "Teststadt",
"country": "",
"countryID": "",
"invoiceEmail": "",
"standardSalutation": 0,
"firstName": "Max",
"lastName": "Mustermann",
"email": "mm@test.de",
"username": "Admin2",
"positions": [
{
"detailID": 1040,
"position": 1,
"categoryName": "Gestaltung",
"detail": "<p>Gestaltung der Website.</p>\r\n<p>Zeitbedarf: ca. 1,5 Personentage</p>",
"quantity": "12.00",
"unit": "",
"netValue": "104.50",
"taxSwitch": 0,
"tax": "7.0",
"additionalChargeSwitch": 1,
"initialNetValue": "95.00",
"additionalCharge1": "10.00",
"additionalCharge2": "0.00",
"discountPosition": 0,
"discountSource": null,
"discountPercent": "0.00",
"detailComments": "eine Info zur Position!"
},
{
"detailID": 1041,
"position": 2,
"categoryName": "Programmierung",
"detail": "<p>Programmierung der abgestimmten Seitenvorlagen für das Content Management System.</p>\r\n<p>Zeitbedarf: ca. 5 Personentage</p>",
"quantity": "5.00",
"unit": "",
"netValue": "600.00",
"taxSwitch": 0,
"tax": "0.0",
"additionalChargeSwitch": 0,
"initialNetValue": "0.00",
"additionalCharge1": "0.00",
"additionalCharge2": "0.00",
"discountPosition": 0,
"discountSource": null,
"discountPercent": "0.00",
"detailComments": ""
},
{
"detailID": 1042,
"position": 3,
"categoryName": "Content",
"detail": "<p>Anlegen von 12 Seiten gemäß der Website Struktur und Einfügen der vom Kunden gelieferten Inhalte.</p>\r\n<p>Zeitbedarf: ca. 8 Std.</p>",
"quantity": "8.00",
"unit": "",
"netValue": "114.00",
"taxSwitch": 0,
"tax": "0.0",
"additionalChargeSwitch": 1,
"initialNetValue": "95.00",
"additionalCharge1": "20.00",
"additionalCharge2": "0.00",
"discountPosition": 0,
"discountSource": null,
"discountPercent": "0.00",
"detailComments": ""
},
{
"detailID": 1044,
"position": 4,
"categoryName": "Hosting",
"detail": "<p>Hosting der Microsite für 1 Jahr</p>",
"quantity": "1.00",
"unit": "",
"netValue": "115.00",
"taxSwitch": 0,
"tax": "0.0",
"additionalChargeSwitch": 1,
"initialNetValue": "100.00",
"additionalCharge1": "15.00",
"additionalCharge2": "0.00",
"discountPosition": 0,
"discountSource": null,
"discountPercent": "0.00",
"detailComments": ""
}
]
}
}
POST /api/v1/invoices
Über die API können nur Rechnungsentwürfe erzeugt und bearbeitet werden. Die Dokumente werden für die PDF-Generierung und den Versand immer danach in der ProSonata Hauptanwendung geprüft und finalisiert. Auf diesem Weg ist sichergestellt, dass keine fehlerhaften Dokumente erstellt werden.
Übergebene Werte (z.B. netValue, grossValue = Gesamtpreis des Dokuments) werden bei der Speicherung über die API nicht auf korrekte Berechnung überprüft! Eine Validierung muss vorab erfolgen. Beim Aufruf der Rechnung in der ProSonata Anwendung wird der Gesamtpreis auf Basis der vorhandenen Positionsdaten berechnet.
Notwendige und mögliche Parameter im Body:
| Parameter | Beschreibung | Typ | Default-Wert | Pflichtfeld |
|---|---|---|---|---|
| projectID | ID des Projekts | Int | ja | |
| addressID | ID der Kundenadresse | Int | ja | |
| invoiceContactID | ID des Ansprechpartners (auch bei neutraler Anrede notwendig) | Int | ja | |
| shipToAddressID | ID einer abweichenden Waren-/Leistungsempfängeradresse | Int | ||
| invoiceDate | Datum der Rechnung | Date | aktueller Tag | |
| invoiceName | optionale Bezeichnung, ersetzt die Projektbezeichnung | String | ||
| dateStart | Leistungszeitraum Beginn | Date | aktueller Tag | |
| dateEnd | Leistungszeitraum Ende | Date | aktueller Tag | |
| projectNoAddition | Ergänzung/Zusatz zur Projektnummer | String | ||
| purchaseOrderNo | Bestellnummer | String | ||
| contractNo | Auftragsnummer | String | ||
| tradeAccountingAccount | Buchungsreferenz (keine Leitweg-ID, o.ä.!) | String | ||
| paymentTarget | Zahlungsziel in Tagen | Int | 14 | |
| netValue | Gesamtpreis netto | Dec | 0.00 | |
| grossValue | Gesamtpreis brutto | Dec | 0.00 | |
| currency | Währung: 0 = Euro 1 = CHF (SFr) 2 = US$ 3 = GBP 4 = CAD |
Int | 0 | |
| tax | Steuersatz | Dec | 0.0 | ja |
| reverseCharge | Rechnung in das EU-Ausland 0 = nein 1 = ja |
Int | 0 | |
| thirdCountry | Rechnung in ein Drittland 0 = nein 1 = ja |
Int | 1 | |
| customerTaxID | Steuernummer des Rechnungsempfängers (standardmäßig die vorhandene Nummer der Kundenadresse) |
String | ||
| cashDiscountRate | Skontosatz | Dec | 0.0 | |
| cashDiscountPaymentTarget | Zahlungsziel Skonto in Tagen | Int | 0 | |
| showProjectNumber | die Projektnummer in der Rechnung ausgeben | Int | 1 | |
| showPositionNumber | Spalte Positionsnummer anzeigen 0 = nein 1 = ja |
Int | 1 | |
| showCategory | Spalte Kategorie anzeigen 0 = nein 1 = ja |
Int | 1 | |
| showQuantity | Spalte Menge/Einzelpreis anzeigen 0 = nein 1 = ja |
Int | 0 | |
| standardSalutation | neutrale Anrede ausgeben (Sehr geehrte Damen und Herren) 0 = nein 1 = ja |
Int | 0 | |
| templateLanguage | Sprache der Rechnung 0 = deutsch 1 = englisch |
Int | 0 | |
| textTemplate | Auswahl des Abbildertextes (0 bis 5) | Int | 0 | |
| fibuAccountNoAddressID | abweichende Adresse für FiBu Debitorenkonto (Standardmäßig wird die addressID gesetzt) |
Int | ||
| fibuIncomeAccount | ein abweichendes FiBu Ertragskonto der Rechnung | String | ||
| pdfStandard | Standard des später in der Hauptanwendung generierten PDFs 0 = PDF (keine E-Rechnung) 1 = PDF/A (keine E-Rechnung) 4 = ZUGFeRD 5 = XRechnung |
Int | 4 | |
| invoiceComments | Anmerkungen zur Rechnung | String | ||
| positions | Positionen der Rechnung speichern; ein Array der Positionen kann übergeben werden Aufbau des Arrays siehe unten |
Array | null |
Angabe von Dezimalwerten mit Punkt als Trennzeichen.
Beispiel:
{
"addressID": 41,
"projectID": 403,
"addressID": 187,
"invoiceContactID": 189,
"invoiceName": "Rechnung via API",
"invoiceDate": "2026-08-20",
"dateStart": "2026-06-16",
"dateEnd": "2026-08-03",
"showCategory": 0,
"showQuantity": 1,
"textTemplate": 1,
"invoiceComments": "ein Test über die API",
"standardSalutation": 1,
"positions": [
{
"position": "1",
"category": 25,
"detail": "<p>Planung, Abstimmung, Kundenbetreuung</p>",
"sellerAssignedID": "1234",
"buyerAssignedID": "Kd5132",
"quantity": 4.50,
"netValue": 110.00,
"additionalChargeSwitch": 1,
"additionalCharge1": "0.00",
"additionalCharge2": "10.00",
"detailComments": "Test Pos 1"
},
{
"position": "2",
"category": 14,
"detail": "<p>Beratung bei Konzeption und Struktur des Product Package. Kommunikation und Handling.</p>\r\n<p><strong>Zeitbedarf</strong>: 8 Std.</p>",
"quantity": "8.00",
"unit": "h",
"netValue": "95.00",
"detailComments": "Pos 2 zum Testen",
"insertSubTotal": 1
}
]
}
Notwendige und mögliche Parameter im Array der Positionen:
| Parameter | Beschreibung | Typ | Default-Wert | Pflichtfeld |
|---|---|---|---|---|
| category | ID des Leistungskategorie | Int | ja | |
| headline | Überschrift zur Position | String | ||
| detail | Freitext zur Position (Basis html Tags möglich) | String | ||
| sellerAssignedID | Artikelnummer des Verkäufers | String | ||
| buyerAssignedID | Artikelnummer des Käufers (Rechnungsempfängers) | String | ||
| position | Position (Hauptposition, muss korrekt gesetzt werden und wird durch die Anwendung nicht geprüft) | String | ||
| subPosition | optionale Unterposition (bei isSubPosition = 1, siehe unten) | String | ||
| quantity | Menge | Dec | 0.00 | |
| unit | Einheit (z.B. Std., Stück) | String | ||
| netValue | Einzelpreis (netto) | Dec | 0.00 | |
| taxSwitch | eigener Steuersatz für die Position 0 = nein 1 = ja |
Int | 0 | |
| tax | Steuersatz | Dec | 0.0 | |
| additionalChargeSwitch | Preisaufschlag verwenden 0 = nein 1 = ja |
Int | 0 | |
| additionalCharge1 | Aufschlag prozentual | Dec | 0.0 | |
| additionalCharge2 | Aufschlag fester Betrag pro Stück | Dec | 0.00 | |
| discountPosition | Rabattposition (mit automatischer Berechnung des Rabattbetrags) 0 = nein 1 = ja |
Int | 1 | |
| discountSource | bei Angabe 0 wird der Rabatt über alle Positionen bis zur Rabattposition berechnet Rabatt auf eine Position = Angabe der detailID keine Rabattposition = null |
Int | null | |
| discountPercent | Rabatt in Prozent | Dec | 0.0 | |
| insertSubTotal | eine Zwischensumme nach der Position ausgeben 0 = nein 1 = ja |
Int | 0 | |
| subTotalSinceHeadline | Zwischensumme nur bis zur letzten vorherigen Überschrift berechnen | Int | 0 | |
| isSubPosition | Position ist eine Unterposition 0 = nein 1 = ja |
Int | 0 | |
| allPositionsOrder | Reihenfolge der Position, falls Unterpositionen Positionen vorhanden sind | Int | null | |
| detailComments | Anmerkungen zur Position (erscheinen nicht in der Ausgabe) | String |
Angabe von Dezimalwerten mit Punkt als Trennzeichen.
PUT /api/v1/invoices/{id}
Über die API können nur Rechnungsentwürfe bearbeitet werden. Die Dokumente werden für die PDF-Generierung und den Versand immer in der ProSonata Hauptanwendung geprüft und finalisiert.
Es müssen nicht alle Parameter für eine Bearbeitung übergeben werden.
Es stehen die Parameter zum Erstellen der Ressource zur Verfügung (s.o.).
Für das Bearbeiten der Positionen gilt: