Rechnungserstellung über die API

  • 16.08.2018

Das heutige Update für SpikeTime betrifft 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:

API Aufruf für alle Rechnungen pro Monat

API Aufruf für einzelne Rechnung

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 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: []
  }
}

Als Pflichtfeld auf oberster Ebene muss die CustomerId übergeben werden. Alle Kunden des SpikeTime Accounts können über den Customer Endpunkt geholt werden.

API Aufruf für alle Kunden

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

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:

Standardtext für Rechnungspositionen


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.

API Aufruf PDF für Rechnung

API Aufruf PDF für Leistungsnachweis

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.