Document ID: /fineweb-2-swissfilter-quality_10-filterrobots/filtered/03571.jsonl.gz/2850

Einführung zum RESTful Run my Accounts API (Application Protocol Interface)
Bevor Sie mit dem Bau einer Schnittstelle beginnen wenden Sie sich Bitte an Ihren Online-Buchhalter bzw. unseren Sales (<email-pii>). Diese werden mit Ihnen die nötigen Informationen abklären und anhand dieser wird eine Testumgebung für Sie bereit gestellt.
Run my Accounts bietet eine einfache und offene Schnittstelle, um Rechnungsdaten direkt von Branchenlösungen, Web-Shops, Zeiterfassungstools usw. ins Buchhaltungssystem einzulesen. Daten können sowohl importiert als auch exportiert werden.
Diese Dokumentation ist für Software-Entwickler ausgelegt, welche ihre Applikationen an das Run my Accounts System anbinden wollen.
Das API sind RESTful Ressourcen
Das API versucht den Designvorgaben von „Representational State Transfer“ zu folgen. Beschrieben in http://de.wikipedia.org/wiki/Representational_State_Transfer.
Das API ist ganz HTTP basiert
Welche Opertationen mit den Ressourcen durchgeführt werden, wird mittels der HTTP-Verben angegeben:
- GET Funktion zum Erhalten von Inhalt.
- POST Erstellen oder Ändern von Inhalt.
- DELETE Löschen von Inhalten.
Allgemeine Service URL
https://service.runmyaccounts.com/api/{version}/{resource}
Datenformate
Das Run my Accounts API versteht XML und JSON. Zu beachten ist folgendes:
- Alle Requests sollten UTF-8-kodiert sein. Die Antworten sind es auch.
- Bei schreibenden Anfragen muss der entsprechende Content-Type im HTTP-Header gesetzt werden “application/xml” (oder “application/json”)
- Werte des Feldtyps BOOLEAN können die Werte true (wahr) oder false (falsch) haben.
- Das Datumsformat ist yyyy-MM-dd (Bsp: 2011-10-24). Zusätzlich werden folgende Schlüsselwörter verstanden: today, yesterday, tomorrow.
- Zeitstempel haben das Format yyyy-MM-dd'T'HH:mm:ss.SSSZ (Bsp: 2011-10-24T10:39:18.333+02:00)
- Felder des Typs TEXT können in der Länge beschränkt sein. Bsp. TEXT(32) erlaubt 32 Zeichen.
Antworten sind generell in XML-oder JSON-Format. Das Format wird über den HTTP-Header 'Accept' festgelegt:
Accept: application/xml oder Accept: application/json
Die Ressourcen bzw. das API ist versioniert. Der erste Parameter im Pfad ist die Versionsnummer. Mit dem Wert „latest“ erhält man immer die aktuelle Version. Falls spezielle Versionen zur Verfügung stehen, sind diese in den Ressourcen spezifiziert.
Fehler/Antwort Codes
Das API verwendet die Http Antwort Codes. Fehler werden damit angezeigt.
|Code||Beschreibung|
|200||Alles OK!|
|204||Ein OK, falls nur eine Resource erstellt wird ohne Antwort (POST)|
|400||Die benutzten Anfrageparameter sind ungültig.|
|403||Der Zugriff mit entsprechendem api_key wurde verweigert.|
|404||Die angefragte Resource ist unbekannt|
|500||Fehler auf Serverseite|
Authentifizierung
Run my Accounts vergibt API-Schlüssel. Diese sind quasi das “Passwort” für die Benutzung der API. API-Zugriffe sind zustandslos, d.h. dass keine Sitzungen gespeichert werden und bei jedem Request der API-Schlüssel mit übermittelt werden muss. Der API-Schlüssel wird als Parameter api_key der URL mitgegeben.
Wo finde ich den API Key?
Nachdem Sie sich in unsere Webapplikation eingeloggt haben können Sie unter 'Einstellungen' > 'Firmen Einstellungen' (1) den Tab API User anwählen (2). Hier sehen Sie die genauen Angaben zu Ihrem API Key.
Tools
Für das Lesen von Daten per GET ist ein normaler Browser ausreichend. Mit Firefox werden die XML-Daten auch übersichtlich als Baumstruktur dargestellt. Einfach die URL der gewünschten Ressource (inkl. dem API-Schlüssel) in die Adresszeile des Browsers eingeben. Für das Testen der restlichen Methoden (POST, PUT, DELETE) empfehlen wir entweder das Kommandozeilen-Tool curl oder als grafische Alternative das Firefox-Plugin RESTClient.
Die Ressourcen
API Use-Cases
|Nr.||Aktion||Beispiele||Vorgang||Resultat|
|Rechnung schreiben|
|Buchungs-Variante|
|A1||Rechnung einbuchen||Bsp. A1.1, Bsp. A1.2||x Beträge werden auf x Buchhaltungskonten (Ertragskonten) kontiert. Falls Relevant wird werden auch MWST Beträge auf MWST Konten gebucht.||Eingebuchte Rechnung, Umsatz, passivierte MWST, offene Position|
|A2||Rabatt||Bsp. A2.1||Auf einer Rechnung soll transparent ein Rabatt ausgewiesen und dieser soll als negativer Umsatz (wahlweise auf ein spezielles Rabatt-Konto oder auf ein Umsatzkonto) gebucht werden. Die Rabattbuchung ist MWST-relevant analog A1.||Negativer Umsatz|
|A3||Akonto Buchung||Bsp. A3.1||Ein Betrag wird auf ein Passiven-Konto (z.B. 2030 - Anzahlungen von Kunden) gebucht. Falls Relevant werden auch MWST Beträge auf MWST Konten gebucht.||Position in der Bilanz (Verbindlichkeit), passivierte MWST, offene Position|
|A4||Akonto Schlussabrechnung||Bsp. A4.1||Gesamtbetrag wird als x Beträge auf x Buchhaltungskonten gebucht (Ertragskonten). Ein negativer Akonto Betrag in der gesamten Höhe der Akontozahlungen wird vom Passivenkonto abgezogen||Gesamtumsatz wird in Erfolgsrechnung ausgewiesen, die Bilanzposition ist Null.|
|Artikel-Variante|
|A5||Rechnung mit Artikel einbuchen||Bsp. A5.1||Rechnung mit x Artikeln einbuchen. Den Artikeln sind sowohl Buchhaltungskonten als auch MWST Codes zugeordnet. Auf die Kontierung und die MWST kann über die Artikel kein Einfluss ausgeübt werden.||Eingebuchte Rechnung, Umsatz, passivierte MWST, offene Position|
|A6||Rabatt mit Artikel||Bsp. A6.1||Auf einer Rechnung soll transparent ein Rabatt ausgewiesen und dieser soll als negativer Umsatz (wahlweise über einen speziellen Rabatt-Artikel oder auf einen normalen Umsatzartikel) gebucht werden. Die Rabattbuchung ist MWST-relevant analog A5. Die MWST Buchung muss nicht berücksichtigt werden, da dies über den Artikel gesteuert wird.||Negativer Umsatz|
|A7||Akonto||Bsp. A7.1||Ein Betrag wird über ein Akonto-Artikel auf ein Passiven-Konto (z.B. 2030 - Anzahlungen von Kunden) gebucht. Falls Relevant werden auch MWST Beträge über den Artikel auf MWST Konten gebucht.||Position in der Bilanz (Verbindlichkeit), passivierte MWST, offene Position|
|A8||Akonto Schlussabrechnung||Bsp. A8.1||Gesamtbetrag wird mit x Artikeln gebucht. Ein oder mehrere negative Akonto Artikel in der gesamten Höhe der Akontozahlungen werden abgezogen||Gesamtumsatz wird in Erfolgsrechnung ausgewiesen, die Bilanzposition ist Null.|
|Gutschrift buchen|
|Buchungs-Variante|
|B1||Gutschrift buchen||Bsp. B1.1||Eine Gutschrift wird exakt wie eine Rechnung behandelt, nur dass die Beträge auf den Konten negativ eingebucht werden. Die Gutschriftsbeträge auf den einzelnen Konten dürfen sich von den Rechnungsbeträgen unterscheiden.||Eingebuchte Gutschrift, negativer Umsatz, ggfs. tiefere MWST Verbindlichkeit, offene Position|
|Artikel-Variante|
|B2||Gutschrift mit Artikel buchen||Bsp. B2.1||Eine Gutschrift wird exakt wie eine Rechnung behandelt, nur dass die Beträge auf den Artikeln negativ eingebucht werden. Die Gutschriftsbeträge auf den einzelnen Artikeln dürfen sich von den Rechnungsbeträgen unterscheiden.||Eingebuchte Gutschrift, negativer Umsatz, ggfs. tiefere MWST Verbindlichkeit, offene Position|
|Rechnung löschen|
|C1||Rechnung löschen||Das Löschen von Rechnungen ist nicht vorgesehen, da in einer ordentlich geführten Buchhaltung Löschungen nicht vorgesehen sind. Falsch eingebuchte Rechnungen sollen über Gutschriften über die selben Beträge und Artikel neutralisiert werden.|
|Buchungs-Variante|
|C2||Storno buchen||Bsp. C2.1||Ein Storno wird exakt wie eine Rechnung behandelt, nur dass die Beträge auf den Konten negativ eingebucht werden. Der Storno hat das selbe Datum wie die Rechnung. Die Stornobeträge auf den einzelnen Konten dürfen sich nicht von den Rechnungsbeträgen unterscheiden. Ausbuchen des Stornos über das Transferkonto. Ein Storno kann nur gebucht werden, so lange Run my Accounts keine MWST Abrechnung erstellt hat. Alternative: Gutschrift mit aktuellem Datum||Eingebuchter Storno, negativer Umsatz, tiefere MWST Verbindlichkeit, offene Position|
|Artikel-Variante|
|C3||Storno mit Artikel buchen||Bsp. C3.1||Ein Storno wird exakt wie eine Rechnung behandelt, nur dass die Artikel negativ eingebucht werden. Der Storno hat das selbe Datum wie die Rechnung. Die Stornobeträge auf den einzelnen Artikeln dürfen sich nicht von den Rechnungsbeträgen unterscheiden. Ausbuchen des Stornos über das Transferkonto. Ein Storno kann nur gebucht werden, so lange Run my Accounts keine MWST Abrechnung erstellt hat. Alternative: Gutschrift mit aktuellem Datum||Eingebuchter Storno, negativer Umsatz, tiefere MWST Verbindlichkeit, offene Position|
|Zahlungen|
|D1||Zahlung erfassen||Bsp. D1.1||Eine Zahlung wird unter Angabe von Datum, Betrag und Kontonummer eingebucht. Die Zahlung muss dem tatsächlich auf dem Bankkonto oder in der Kasse eingegangenen Betrag entsprechen. Teilzahlungen sind möglich.||Geschlossene resp. Teilgeschlossene Position|
|D2||Rabatt/Preisnachlass||Bsp. D2.1||Entspricht der Zahlung nicht exakt dem offenen Rechnungsbetrag und soll auf eine weitere Zahlungseintreibung resp. Rückvergütung verzichtet werden, kann der noch offene / überschüssige Betrag über das Konto 3901 Rabatte und Preisnachlässe ausgebucht werden.||Geschlossene Position|
|D3||Bank- / PC-Spesen||Bsp. D3.1||Ist der Zahlungseingang tiefer als die offene Position, weil die Banktransaktion für den Empfänger kostenpflichtig war, kann die Differenz auf das Konto 6840 Bank-/PC-Spesen gebucht werden||Geschlossene Position|
|D4||Skonto||Bsp. D4.1||Macht der Rechnungsempfänger einen Skonto-Abzug geltend, wird der Skontobetrag auf das Konto 3900 gebucht.||Geschlossene Position|
|D5||Transferkonto||Bsp. D5.1||Das Transferkonto wird dazu verwendet, Rechnungen / Gutschriften / Stornos miteinander zu verrechnen. Eine Position wird mit einem Betrag geschlossen, eine andere Position wird durch einen negativen Betrag ebenfalls geschlossen, so dass sich der Saldo des Transferkonto nicht verändert. Achtung: Nach Abschluss aller Transaktionen muss das Transferkonto auf 0 stehen.||Geschlossene Positionen, saldiertes Transferkonto|
|Kunden eröffnen|
|E1||Kunden eröffnen||Ein noch nicht erfasster Kunden wird gemäss den Angaben in der Rechnung oder in den Kundenstammdaten eröffnet||Neu eröffneter Kunde|
|E2||Kunden mutieren||Ein bereits erfasster Kunden wird mutiert||Mutierter Kunde|
Weitere Transaktionen auf Anfrage.
Der Umgang mit Bankkonten
Bei Verwendung der Dienstleistungen ESR-Sync oder Bank Sync Pro werden Bankkonten ausschliesslich durch Run my Accounts gebucht. In diesem Fall dürfen Zahlungseingänge über das API nie direkt gegen ein Bankkonto gebucht werden, sondern immer nur über ein Bank-Durchlauf-Konto. Das entsprechende Bank-Durchlaufkonto wird auf Anfrage von Run my Accounts eröffnet. Run my Accounts bucht alle Debitoren-Relevanten Bankkonto-Transaktionen gegen das Durchlaufkonto, so dass bei korrekter Kontenführung das Durchlaufkonto täglich auf 0 saldiert wird.
Zahlungseingänge müssen zwingend mit den korrekten Beträgen im Debitorensystem gebucht werden, ansonsten geht die Buchhaltung nicht auf. Allfällige durch den Kunden falsch gebuchten Positionen müssen bereinigt werden. Falls dies durch Run my Accounts geschieht, sind Bereinigungsarbeiten kostenpflichtig, sollten diese auf ein falsches Handling des Kunden zurückgehen. Werden Zahlungseingänge generell nicht durch den Kunden gebucht, muss Run my Accounts darüber informiert werden und in der Lage sein, die Offenen Positionen selbständig zu schliessen.
Disclaimer
Run my Accounts ist für das Führen der Buchhaltung verantwortlich. Durch Fehlfunktion des API's auf der Kundenseite entstandene Fehler in der Buchhaltung werden durch Run my Accounts kostenpflichtig aufgeräumt.