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 (welcome@runmyaccounts.com). 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

Wel­che Operta­tio­nen mit den Res­sour­cen durch­ge­führt wer­den, wird mit­tels 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 soll­ten UTF-8-kodiert sein. Die Antworten sind es auch.
  • Bei schrei­ben­den Anfragen muss der ent­spre­chende Content-Type im HTTP-Header gesetzt wer­den “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

Authen­ti­fi­zie­rung

Run my Accounts vergibt API-Schlüssel. Die­se sind quasi das “Pass­wort” für die Benut­zung der API. API-Zugriffe sind zustands­los, d.h. dass keine Sit­zun­gen gespei­chert wer­den und bei jedem Request der API-Schlüssel mit über­mit­telt wer­den 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.

(1) (2)

Tools

Für das Lesen von Daten per GET ist ein nor­ma­ler Brow­ser aus­rei­chend. Mit Fire­fox wer­den die XML-Daten auch über­sicht­lich als Baum­struk­tur dar­ge­stellt. Ein­fach die URL der gewünsch­ten Res­source (inkl. dem API-Schlüssel) in die Adress­zeile des Brow­sers ein­ge­ben. Für das Tes­ten der rest­li­chen Metho­den (POST, PUT, DELETE) emp­feh­len wir ent­we­der das Kommandozeilen-Tool curl oder als gra­fi­sche Alter­na­tive das Firefox-Plugin REST­Cli­ent.

Die Ressourcen

Kunden
Liste der KundenGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/customers
Kunde erstellen, mutierenPOST https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/customers
Artikelstamm
ArtikelGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/parts
Rechnungen und Gutschriften
Liste der RechnungenGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/invoices
Ansicht einer RechnungGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/invoices/{invoice_number}
PDF einer Rechnung GET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/invoices/{invoice_number}/pdf
HTML einer Rechnung GET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/invoices/{invoice_number}/html
Erstellen einer RechnungPOST https://service.runmyaccounts.com/api/{version}/clients/{mandantenname}/invoices
Zahlungen auf Debitorenrechnungen
Liste der ZahlungenGET https://service.runmyaccounts.com/api/{version}/clients/{mandantenname}/invoices/payment_list
Liste der Zahlungen für eine RechnungGET https://service.runmyaccounts.com/api/{version}/clients/{mandantenname}/invoices/{invoice_number}/payments
Zahlung erfassenPOST https://service.runmyaccounts.com/api/{version}/clients/{mandantenname}/invoices/{invoice_number}/payments
Kontenplan
KontenplanGET https://service.runmyaccounts.com/api/{version}/clients/{mandantenname}/charts
Salden
SaldenGET https://service.runmyaccounts.com/api/{version}/clients/{mandantenname}/gl/saldo
Lieferanten
Liste der LieferantenGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/vendors
Lieferant erstellen bzw. mutierenPOST https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/vendors
Kreditorenrechnung
Liste der KreditorenechnungenGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/payables
Ansicht einer KreditorenrechnungGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/payables/{invoice_number}
PDF einer KreditorenrechnungGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/payables/{invoice_number}/pdf
Erstellen einer KreditorenrechnungPOST https://service.runmyaccounts.com/api/{version}/clients/{mandantenname}/payables
Zahungen auf Lieferanten Rechnungen
Liste der Zahlungen einer KreditorenrechnungGET https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/payables/{invoice_number}/payments
Einbuchen einer Zahlung einer KreditorenrechnungPOST https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/payables/{invoice_number}/payments
Upload von Belegen
Upload von BelegenPOST https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/belege
Hauptbuch
Einbuchen von HauptbuchbuchungenPOST https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/gl
Jahresendbuchungen
Liste der Jahresendbuchungen POST https://service.runmyaccounts.com/api/latest/clients/{mandantenname}/gl/yearend

API Use-Cases

Nr. Aktion Beispiele Vorgang Resultat
Rechnung schreiben
Buchungs-Variante
A1 Rechnung einbuchen Bsp. A1.1, Bsp. A1.2x 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.1Auf 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.1Ein 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.1Rechnung 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.1Auf 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.1Ein 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 SchlussabrechnungBsp. 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.1Eine 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.1Eine 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.1Ein 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.1Ein 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.1Eine 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.1Entspricht 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.1Ist 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.1Macht der Rechnungsempfänger einen Skonto-Abzug geltend, wird der Skontobetrag auf das Konto 3900 gebucht. Geschlossene Position
D5 Transferkonto Bsp. D5.1Das 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öffnetNeu eröffneter Kunde
E2 Kunden mutieren Ein bereits erfasster Kunden wird mutiertMutierter 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.

Schnittstellen → REST-API