API

das REST API für jeden

kassomat bietet ein RESTful HTTP API, welches schon ab dem Demo Account genutzt werden kann, um Vorsteueranmeldungen an ELSTER zu senden.

Sind die unter 1. genannten Voraussetzungen erfüllt und die unter 2. beschriebene Initialisierung einmalig vorgenommen, so kann eine Vorsteueranmeldung nachfolgend mit 2 HTTP Requests wie unter Punkt 3. beschrieben erzeugt und an ELSTER versendet werden.

1. Voraussetzungen

kassomat bietet ein RESTful HTTP API nach dem REST Standard. Jede Interaktion mit dem API erfordert lediglich einfache HTTP Requests, wobei über das jeweilige HTTP Verb (POST/PUT/GET/DELETE) das Anlegen, Ändern, Abrufen sowie Löschen von serverseitigen Resourcen vom Client gesteuert wird.

Als Datenübertragungsformat kommt ausschließlich JSON zur Verwendung.

Das verwendete Encoding für ein- sowie ausgehende Daten ist UTF-8.

Das kassomat API ist nur über HTTPS nutzbar.

Zu Testzwecken kann das API auch ohne den vorherigen Kauf eines kassomat Pakets genutzt werden. kassomat versieht in diesem Fall jede zu versendende Vorsteueranmeldung mit einem Testflag. Die Vorsteueranmeldung wird nachfolgend an die Clearingserver von ELSTER gesendet, von diesen auf Gültigkeit geprüft, aber nicht ausgewertet.

Der Schritt der Initialisierung ist nur einmalig notwendig. Da das kassomat API mandantenfähig ist, werden beim Registrieren unabhängig vom Accounttyp automatisch ein erster Mandant sowie ein Kassenbuch angelegt. Die ID's des Mandanten (tenant) sowie des Kassenbuchs (cashbook) sollten dauerhaft gespeichert werden. Somit kann im zweiten Schritt eine Vorsteueranmeldung mit nur zwei HTTP Requests versendet werden. Besteht hingegen keine Möglichkeit, diese ID's zu speichern, so können Mandanten- sowie Kassenbuch-ID's auch nachträglich wie hier beschrieben abgerufen werden, was aber bei jeder Vorsteueranmeldung zwei zusätzliche Requests voraussetzt.

2. Initialisierung

Anlegen eines Benutzeraccounts

Das API kann zu Testzwecken mit einem Demo Account vollständig genutzt werden. Für den realen Versand von Vorsteueranmeldungen ist hingegen ein Account vom Typ Standard, Profi oder Partner notwendig. Diese können hier erworben werden.

Ein Demo Account kann mit einem POST Request wie folgt erzeugt werden:

Request:

POST /v1/user
Host: api.kassomat.net
Accept: application/json
Content-Type: application/json
{
  "user": {
    "demo": true
  }
}

Response:

HTTP/1.1 201 OK
Content-Type: application/json
{
  "root_name": "user",
  "user": {
    "email": "user_6ce01701f0f97f6c48e84b92ef83d909ec6899d3@kassomat.net",
    "id": "508beab375d493265c000001",
    "uri": "/v1/user"
  }
}

Authentifizierung / Login

Jede Interaktion mit dem API setzt einen angemeldeten Nutzer voraus. Das Session Management wird hierbei über ein Authentifizierungstoken geregelt, welches mit jedem nachfolgenden Request als HTTP Header X-Kassomat-Auth-Token mitgesendet werden muss. Um einen Nutzer einzuloggen und das Token abzufragen, werden Emailadresse und Passwort in einem POST Request wie folgt genutzt.

Achtung Im Falle eines Demo Accounts ist die automatisch erzeugte Email Adresse unter dem Schlüssel email aus der Response des Requests zu extrahieren, mit dem der Demo Account angelegt wurde. Diese kann nachfolgend für den Login genutzt werden, indem immer das Passwort password verwendet wird.

Ist ein Account vom Typ Standard, Profi oder Partner vorhanden, so müssen die bei der Registrierung verwendete Email-Adresse sowie das entsprechende Passwort genutzt werden.

Request:

POST /v1/session
Host: api.kassomat.net
Accept: application/json
Content-Type: application/json
{
  "session": {
    "email": "user_6ce01701f0f97f6c48e84b92ef83d909ec6899d3@kassomat.net",
    "password": "password"
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "root_name": "api_session",
  "api_session": {
    "authentication_token": "CiNydtFjpJwGzxMrtxA8"
  }
}

Ermitteln der Mandanten- und Kassenbuch-ID's

Wird ein Mandant und ein Kassenbuch wie hier beschrieben manuell angelegt, so sollten die ID's beider Resourcen dauerhaft gespeichert werden.

Wenn die ID's von Mandant und Kassenbuch nicht dauerhaft gespeichert werden können oder erstmalig ermittelt werden sollen, so können diese mit zwei HTTPs Request abgefragt werden. Voraussetzung ist, dass ein Nutzer angemeldet ist.

Um die Mandanten eines Nutzers zu ermitteln, wird die Resource Mandant (tenants) per GET Request abgefragt:

Request:

GET /v1/tenants
Host: api.kassomat.net
Accept: application/json
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8

Response:

HTTP/1.1 200 Ok
Content-Type: application/json
{
  "root_name": "tenants",
  "page": 1,
  "total_pages": 1,
  "total_records": 3,
  "tenants": [
    {
      "id": "508ea15575d493265c00000c",
      "name": "Beispiel Mandant",
      "uri": "/v1/tenants/508ea21175d493265c00000d",
      "subresource_uris": {
        "cashbooks":"/v1/tenants/508ea21175d493265c00000d/cashbooks"
      }
    }
  ]
}

Die ID des Mandaten kann unter dem Schlüssel id abgelesen werden. Um die Kassenbücher dieses Mandanten zu laden, wird auf die gleiche Weise ein GET Requests auf die Kassenbuch Resource (cashbooks) abgesetzt. Die URI hierfür kann aus der vorher geladenen Tenant Resource unter dem Schlüssel subresource_uris und dem Unterschlüssel cashbooks extrahiert werden:

Request:

GET /v1/tenants/508ea21175d493265c00000d/cashbooks
Host: api.kassomat.net
Accept: application/json
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8

Response:

HTTP/1.1 200 Ok
Content-Type: application/json
{
  "root_name": "cashbooks",
  "page": 1,
  "total_pages": 1,
  "total_records": 4,
  "cashbooks": [
    {
      "id": "508f8fc475d493265c000012",
      "name": "Beispiel Kassenbuch",
      "tax_id": "9212034567893",
      "tax_id_raw": "12/345/67893",
      "tax_first_name": "Max",
      "tax_last_name": "Mustermann",
      "tax_street": "Musterstraße 1",
      "tax_zip": "12345",
      "tax_city": "Musterstadt",
      "tax_phone": "00493012345678",
      "tax_email": "max@mustermann.de"
      "uri": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012",
      "subresource_uris": {
        "bookings": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/bookings",
        "assessments": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/assessments"
      }
    }
  ]
}

Die ID des entsprechenden Kassenbuchs kann nun unter dem Schlüssel id abgelesen werden. Es empfiehlt sich, die ID's für Mandant und Kassenbuch dauerhaft zu speichern, um diese nicht vor jeder Vorsteueranmeldung erneut ermitteln zu müssen.

Konfigurieren der Absenderdaten (Kassenbuch)

Für alle Accounttypen wird während der Registrierung ein initialer Mandant sowie ein Kassenbuch angelegt. Um die Absenderdaten für eine Vorsteueranmeldung festzulegen, müssen diese in das Kassenbuch mit Hilfe des nachfolgenden PUT Requests übertragen werden.

Warnung Für die vollständige Konfiguration der Absenderdaten eines Kassenbuchs ist die 13-stellige ELSTER Steuernummer notwendig. Diese ist NICHT mit der Steuernummer des Nutzers identisch und kann nur wie hier beschrieben ermittelt werden.

Tip Ein Demo Account verfügt schon über ein vollständig konfiguriertes Kassenbuch. Soll das API nur für Testzwecke angesprochen werden, ist der nachfolgende Schritt nicht notwendig.

Request:

PUT /v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012
Host: api.kassomat.net
Accept: application/json
Content-Type: application/json
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8
{
  "cashbook": {
    "name": "Beispiel Kassenbuch",
    "tax_id": "9212034567893",
    "tax_id_raw": "12/345/67893",
    "tax_first_name": "Max",
    "tax_last_name": "Mustermann",
    "tax_street": "Musterstraße 22",
    "tax_zip": "12345",
    "tax_city": "Musterstadt",
    "tax_phone": "00493087654321",
    "tax_email": "max@mustermann.de"
  }
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "root_name": "cashbook",
  "cashbook": {
    "id": "508f8fc475d493265c000012",
    "name": "Beispiel Kassenbuch",
    "tax_id": "9212034567893",
    "tax_id_raw": "12/345/67893",
    "tax_first_name": "Max",
    "tax_last_name": "Mustermann",
    "tax_street": "Musterstraße 22",
    "tax_zip": "12345",
    "tax_city": "Musterstadt",
    "tax_phone": "00493087654321",
    "tax_email": "max@mustermann.de",
    "uri": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012",
    "subresource_uris": {
      "bookings": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/bookings",
      "assessments":"/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/assessments"
    }
  }
}

3. Anmelden der Vorsteuer

Das Erzeugen und Versenden einer Vorsteueranmeldung setzt einen bestehenden Nutzeraccount voraus. Dieser kann wie hier beschrieben angelegt werden.

Ebenso muss ein Mandant sowie ein Kassenbuch bereits angelegt sein. Das Kassenbuch muss im Falle eines Standard, Profi oder Partner Accounts wie hier beschrieben mit Absenderdaten konfiguriert sein. Ein Demo Account verfügt bereits über valide Absenderdaten zu Testzwecken.

Die ID's des Mandanten und des entsprechenden Kassenbuchs müssen bekannt sein oder wie hier beschrieben zunächst ermittelt werden.

Authentifizierung / Login

Das Erzeugen und Versenden einer Vorsteueranmeldung setzt eine vorherige Authentifizierung voraus. Ist noch ein gültiges Authentifizierungstoken vorhanden, so kann fortgefahren werden.

Ist bisher kein Nutzer angemeldet oder zuvor bereits abgemeldet worden, so muss zunächst eine Authentifizierung wie hier beschrieben stattfinden.

Erzeugen einer Umsatzsteuervoranmeldung

Um eine Vorsteueranmeldung erzeugen und versenden zu können, müssen die Brutto Einnahmen sowie Ausgaben zu je 7% und 19% Mehrwertsteuer in Eurocent bekannt sein. Weiterhin muss der Anmeldungszeitraum (Monat oder Quartal) angegeben werden. Mit diesen Daten wird ein POST Request dann wie folgt genutzt:

Request:

POST /v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/assessments
Host: api.kassomat.net
Accept: application/json
Content-Type: application/json
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8
{
  "assessment": {
    "year":2013,
    "month":8,
    "preview": false,
    "test": false,
    "data": {
      "in_7": 1234,
      "out_7": 2345,
      "in_19": 3456,
      "out_19": 4567
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "root_name": "assessment",
  "assessment": {
    "id": "508fb97d75d493265c00001d",
    "year": 2013,
    "month": 8,
    "quarter": null,
    "preview": false,
    "in_7": 1234,
    "in_19": 3456,
    "out_7": 2345,
    "out_19": 4567,
    "sent_at": "2013-08-30T12:27:55+01:00",
    "pdf": null,
    "kz66": null,
    "kz81": null,
    "kz83": null,
    "kz86": null,
    "status": "pending",
    "uri": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/assessments/508fb97d75d493265c00001d",
    "test": false,
    "testmode": false,
    "correction": false
  }
}

Wird hierbei das Flag preview auf true gesetzt, so berechnet der Server lediglich die steuerrelevanten Kennzahlen und gibt eine Assessment Resource zurück. Diese wird NICHT gespeichert, und es wird dabei KEINE Umsatzsteuervoranmeldung an ELSTER versendet.

Ist preview auf false gesetzt, so kann eine Voranmeldung im Testmodus versendet werden. Hierfür muss das zusätzliche Flag test auf true gesetzt werden. In diesem Fall wird eine Vorsteueranmeldung erzeugt und derart mit einem Testflag versehen, dass die Voranmeldung von ELSTER lediglich auf Gültigkeit geprüft, aber nicht weiter verarbeitet wird.

4. Abrufen des ELSTER Sendeberichts (optional)

Der Versand einer Voranmeldung geschieht serverseitig asynchron und kann je nach Verfügbarkeit der ELSTER Server zwischen 3 und 15 Sekunden dauern. Um zu prüfen, ob eine Voranmeldung erfolgreich versendet worden ist, und den ELSTER Sendereport zu laden, kann die Assessment Resource nachfolgend per GET Request abgefragt werden. Der Schlüssel status gibt hierbei an, ob die Vorsteueranmeldung noch in Bearbeitung ist (pending), erfolgreich versendet wurde (completed) oder fehlerhaft war (failed).

Abrufen der Voranmeldung

Eine bereits erzeugte Vorsteueranmeldung kann unabhängig von ihrem aktuellen Status jederzeit abgerufen werden. Hierfür wird ein GET Request auf die Assessment Resource erzeugt. Um die dafür notwendige URI nicht manuell zusammenbauen zu müssen, kann diese URI aus der Response des vorher gesendeten POST Requests aus dem Schlüssel uri übernommen werden:

Request:

GET /v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/assessments/508fb97d75d493265c00001d
Host: api.kassomat.net
Accept: application/json
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8

Response:

HTTP/1.1 200 Ok
Content-Type: application/json
{
  "root_name": "assessment",
  "assessment": {
    "id": "508fb97d75d493265c00001d",
    "year": 2013,
    "month": 8,
    "quarter": null,
    "preview": false,
    "in_7": 1234,
    "in_19": 3456,
    "out_7": 2345,
    "out_19": 4567,
    "sent_at": "2013-08-30T12:27:55+01:00",
    "pdf": "/pdf/ElsterReport_db0a69287a7d67ba8238359a8fd035d2fce77c75.pdf",
    "kz66": "294.14",
    "kz81": "0.0",
    "kz83": "-294.14",
    "kz86": "0.0",
    "status": "completed",
    "uri": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/assessments/508fb97d75d493265c00001d",
    "test": false,
    "testmode": false,
    "correction": false
  }
}

Laden des ELSTER Sendeberichts

Sofern der Status des Assessments completed ist, kann die URL des Sendeberichts aus der Resource unter dem Schlüssel pdf abgelesen werden. Dieses PDF kann dann per GET Request oder direkt in einem Browser heruntergeladen werden:

Request:

GET /pdf/ElsterReport_db0a69287a7d67ba8238359a8fd035d2fce77c75.pdf

5. Weitere Aktionen (optional)

kassomat bietet über die genannten Funktionen hinaus ein weitaus umfangreicheres API. Die vollständige Dokumentation kann in aktueller Form immer auf github gefunden werden.

Ermitteln der 13-stelligen ELSTER Steuernummer

Sollen mit einem Account vom Typ Standard, Profi oder Partner Vorsteueranmeldungen versendet werden, so müssen zunächst Absenderdaten im Kassenbuch hinterlegt werden. Hierfür ist die 13-stellige ELSTER Steuernummer notwendig, welche NICHT mit der dem Nutzer bekannten Steuernummer identisch ist.

Da die einem Nutzer bekannte und auf Bescheiden angegebene Steuernummer übergreifend über alle Bundesländer nicht eindeutig ist, muss aus der Steuernummer des Nutzers zunächst die 13-stellige ELSTER Steuernummer abgeleitet werden. Hierfür wird die Steuernummer des Nutzers sowie dessen zuständiges Finanzamt benötigt. Um die passende ELSTER Steuernummer zu ermitteln, wird ein GET Request wie folgt verwendet:

Request:

GET /v1/fiscal_offices?tax_id=12/345/67893
Host: api.kassomat.net
Accept: application/json
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "root_name": "fiscal_offices",
  "fiscal_offices": [
    {
      "id": "9212",
      "name": "Finanzamt Coburg",
      "fqti": "9212034567893"
    }
  ]
}

Je nach Bundesland und Steuernummer können mehr als nur ein Finanzamt zurückgegeben werden, welche zur angegebenen Steuernummer passen. Die 13-stellige ELSTER Steuernummer kann dann im ensprechenden Record unter dem Schlüssel fqti abgelesen werden.

Manuelles Anlegen eines Mandanten

Da das kassomat API grundlegend mandatenfähig ist, werden für alle Accounttypen schon während der Registrierung automatisch ein Mandant sowie ein Kassenbuch erzeugt. Im Falle eines Standard oder Profi Accounts müssen lediglich die Absenderdaten wie hier beschrieben in das Kassenbuch übertragen werden.

Im Falle eines Partner Accounts (aber durchaus auch mit Standard oder Profi) können dann pro Endkunde Mandanten und Kassenbücher angelegt werden.

Ein Mandant hat lediglich einen eindeutigen Namen und wird mit einem POST Request wie folgt erzeugt:

Request:

POST /v1/tenants
Host: api.kassomat.net
Accept: application/json
Content-Type: application/json
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8
{
  "tenant": {
    "name": "Beispiel Mandant"
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "root_name": "tenant",
  "tenant": {
    "id": "508ea15575d493265c00000c",
    "name": "Beispiel Mandant",
    "uri": "/v1/tenants/508ea15575d493265c00000c",
    "subresource_uris": {
      "cashbooks":"/v1/tenants/508ea15575d493265c00000c/cashbooks"
    }
  }
}

Manuelles Anlegen eines Kassenbuchs

Das Kassenbuch muss mit allen Daten erzeugt werden, welche nachfolgend für den Versand von Vorsteueranmeldungen als Absenderdaten verwendet werden sollen.

Warnung Soll nur ein bereits bestehendes Kassenbuch mit Absenderdaten versehen werden, so ist lediglich wie hier beschrieben vorzugehen.

Ein Kassenbuch kann dann mit Hilfe des folgenden POST Requests erzeugt werden:

Request:

POST /v1/tenants/508ea15575d493265c00000c/cashbooks
Host: api.kassomat.net
Accept: application/json
Content-Type: application/json
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8
{
  "cashbook": {
    "name": "Beispiel Kassenbuch",
    "tax_id": "9212034567893",
    "tax_id_raw": "12/345/67893",
    "tax_first_name": "Max",
    "tax_last_name": "Mustermann",
    "tax_street": "Musterstraße 1",
    "tax_zip": "12345",
    "tax_city": "Musterstadt",
    "tax_phone": "00493012345678",
    "tax_email": "max@mustermann.de"
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "root_name": "cashbook",
  "cashbook": {
    "id": "508f8fc475d493265c000012",
    "name": "Beispiel Kassenbuch",
    "tax_id": "9212034567893",
    "tax_raw_id": "12/345/67893",
    "tax_first_name": "Max",
    "tax_last_name": "Mustermann",
    "tax_street": "Musterstraße 1",
    "tax_zip": "12345",
    "tax_city": "Musterstadt",
    "tax_state": "Musterland",
    "tax_phone": "00493012345678",
    "tax_email": "max@mustermann.de",
    "uri":"/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012",
    "subresource_uris": {
      "bookings": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/bookings",
      "assessments": "/v1/tenants/508ea15575d493265c00000c/cashbooks/508f8fc475d493265c000012/assessments"
    }
  }
}

Ausloggen / Abmelden

Das Ausloggen eines Nutzers und das damit einhergehende Zertören der aktuellen Session sowie die Invalidierung des aktuellen Authentifizierungstokens ist prinzipiell optional. Um Missbrauch der Schnittstelle vorzubeugen, sollte aber nach der erfolgreichen Versendung einer oder mehrerer Vorsteueranmeldungen für einen oder ebenso mehrere Mandanten der Nutzer in jedem Fall ausgelogged werden. Dies ist mit folgendem DELETE Request auf die Session Resource zu erreichen:

Request:

DELETE /v1/session
Host: api.kassomat.net
X-Kassomat-Auth-Token: CiNydtFjpJwGzxMrtxA8

Response:

HTTP/1.1 204 No Content

Für jede nachfolgende Aktion ist zunächst erst wieder ein Nutzer anzumelden.

6. Support und Hilfe

Für Nutzer des Partner Pakets können wir umfangreich Support per Email, telefonisch oder vor Ort zur Verfügung stellen, sofern dies möglich ist. Für die Anbindung des kassomat API in den Sprachen:

  • Ruby
  • Javascript
  • Python
  • PHP
  • node.js
  • C#
können wir Codebeispiele zur Verfügung stellen.

Nutzer des Profi oder Standard Pakets finden die aktuelle sowie vollständige API Dokumentation jederzeit auf github.

Email Anfragen bezüglich der Nutzung des API können von allen Nutzern unter api@kassomat.net gestellt werden, und werden von uns zeitnah beantwortet.