Das heutige Update für SpikeTime betrifft die Rechnungserstellung über die API. Auf Kundenwunsch haben wir neue Endpunkte implementiert, mit denen es möglich ist über die API Rechnungen zu erstellen und die PDF Dokumente (Rechnung und Leistungsnachweis) zu erhalten.
Die API Dokumentation
Die grundsätzliche Benutzung der API ist in unserer API Dokumentation auf der Homepage beschrieben. SpikeTime API Dokumenation
Eine Übersicht aller API Endpunkte mit Beispielaufrufen haben wir als Postman Collection unter folgender URL abgelegt. https://www.spiketime.de/api/Spiketime.json
Dieser Post beschreibt die neuen Endpunkte zur Rechnungsverwaltung im Detail.
Rechnungen lesen
Über die beiden folgenden Endpunkte können die Daten bestehender Rechnungen geladen werden:
Die Parameter des ersten Aufrufs sind das Jahr und der Monat. Zurückgegeben wird ein Array aller Rechnungen für den entsprechenden Monat. Eine einzelne Rechnung kann über die zugehörige ID gelesen werden.
Rechnung per API erstellen
Etwas komplexer ist die Erstellung einer Rechnung über die API. Die Struktur des Request-Bodies für POST an /api/invoice sieht folgendermaßen aus:
{
CustomerId:1,
Invoice:{
InvoiceNo: 1,
InvoiceDate: "2018-08-06",
AddressFrom: "MyAddressFrom",
AddressTo: "MyAddressTo",
Title: "MyTitle",
Description: "MyDescription",
Notes: "MyNotes",
Footer: "MyFooter",
VatRate: 19,
Currency: "€",
Cleared: false
},
Filter:{
DateFrom: "2018-01-01",
DateTo: "2018-08-03",
ClearedStatus: "uncleared",
UserIds: [],
ProjectIds: [],
RateIds: [],
IncludeUnbillableEntries: true
}
}
Als Pflichtfeld auf oberster Ebene muss die CustomerId übergeben werden. Alle Kunden des SpikeTime Accounts können über den Customer Endpunkt geholt werden.
Das Invoice Objekt
Das Invoice Objekt enthält alle Informationen zur Rechnung. Die folgende Tabelle beschreibt alle Felder im Detail:
| API Feld | Datentyp | Beschreibung |
|---|---|---|
| InvoiceNo | string (Pflichtfeld) | Eindeutige Rechnungsnummer |
| InvoiceDate | date (Format: YYYY-MM-DD) | Rechnungsdatum |
| AddressFrom | string | Absender - wenn nicht übergeben oder null wird der Wert der letzten Rechnung an diesen Kunden verwendet |
| AddressTo | string | Rechnungsempfänger - wenn nicht übergeben oder null wird der Wert der letzten Rechnung an diesen Kunden verwendet |
| Title | string | Rechnungstitel (Text unterhalb der Rechnungsnummer) - wenn nicht übergeben oder null wird der Wert der letzten Rechnung an diesen Kunden verwendet |
| Description | string | Beschreibung / Anrede (Text unterhalb des Titels) - wenn nicht übergeben oder null wird der Wert der letzten Rechnung an diesen Kunden verwendet |
| Notes | string | Bemerkungen (Text unterhalb der Tabelle der Rechnungspositionen) - wenn nicht übergeben oder null wird der Wert der letzten Rechnung an diesen Kunden verwendet |
| Footer | string | Footer (Text unten rechts) - wenn nicht übergeben oder null wird der Wert der letzten Rechnung an diesen Kunden verwendet |
| VatRate | number | Umsatzsteuer (z.B. 19%) - wenn 0 wird die Rechnung ohne Umsatzsteuer gestellt, zum Beispiel für Drittländer - wenn nicht übergeben oder null wird der Wert der letzten Rechnung an diesen Kunden verwendet |
| Currency | string | Währung - wenn nicht übergeben oder null wird der Wert der letzten Rechnung an diesen Kunden verwendet |
| Cleared | bool | Flag ob die Rechnung bereits abgerechnet ist, dient aktuell nur als Infofeld. Sperrfunktion ist noch nicht implementiert |
Das Filter Objekt
Mit Hilfe des Filter Objekts werden die Zeiteinträge gefiltert, welche in die Rechnung übernommen werden sollen. Die folgende Tabelle beschreibt alle Felder im Detail:
| API Feld | Datentype | Beschreibung |
|---|---|---|
| DateFrom | date (Format: YYYY-MM-DD) | Untere Grenze für die Auswahl der Zeiteinträge - wenn DateFrom und DateTo nicht übergeben werden, werden die Einträge des letzten abgeschlossenen Monats geladen |
| DateTo | date (Format: YYYY-MM-DD) | Obere Grenze für die Auswahl der Zeiteinträge - wenn DateFrom und DateTo nicht übergeben werden, werden die Einträge des letzten abgeschlossenen Monats geladen |
| ClearedStatus | string | Kann die Werte "cleared" (abgeschlossene Zeiteinträge), "uncleared" (nicht abgeschlossene Zeiteinträge) oder NULL enthalten. Wenn Cleared nicht gesetzt wird oder NULL übergeben wird, werden alle Zeiteinträge, unabhängig davon ob sie bereits abgeschlossen wurden oder nicht, in die Rechnung übernommen. |
| ProjectIds | Array(number) z.B. [1,2] | Filter für Projekte - Die Ids können über den Project Endpunkt geholt werden - wenn nicht übergeben oder null werden alle Projekte ausgewählt |
| RateIds | Array(number) z.B. [1,2] | Filter für Stundensätze - Die Ids können über den Rate Endpunkt geholt werden - wenn nicht übergeben oder null werden alle Stundensätze ausgewählt |
| IncludeUnbillableEntries | bool, Default=false | Nicht verrechenbare Einträge in die Leistungsübersicht übernehmen |
Gruppierung der Zeiteinträge in der Rechnung
Die Gruppierung der Zeiteinträge in der Rechnung erfolgt anhand des Stundensatzes. Entweder wird der Name des Stundensatzes verwendet oder, falls hinterlegt, der Text aus den Einstellungen:
Sendet man diese Daten via POST an den Invoice Endpunkt, wird die entsprechende Rechnung in SpikeTime erzeugt. Der API Endpunkt gibt die erzeuge Rechnung als JSON zurück. Über die technische ID der Rechnung kann anschließend beispielsweise das PDF Dokument der Rechnung geholt werden.
PDF Dokumente laden
Über die folgenden beiden Endpunkte, können für bereits erstellte Rechnungen die PDF Dokumente für die Rechnung und den zugehörigen Leistungsnachweis geladen werden.
Der Paramter ist jeweils die technische ID der Rechnung.
Feedback
Wir freuen uns über jegliches Feedback zu der neuen Funktion - Lob und natürlich auch Kritik. Dazu schreibt eine E-Mail an mail@spiketime.de oder verwendet das Supportformular in SpikeTime.
Wenn auch Sie automatisiert Rechnungen erstellen und Arbeitszeiten online erfassen möchten, dann testen Sie unsere Anwendung für 14 Tage komplett kostenlos unter Zeiterfassung für KMU und Freiberufler