New API url

Written by Marcel Lenz 2015-09-22

easySYS has changed the name to bexio. This rename causes changes to all URLs of the api. Please change the configuration of your api connectors to the following parameters:

New API URLs

You should replace easysys.ch with bexio.com for all API URLs.

API Endpoint: https://office.bexio.com/api2.php (old https://office.easysys.ch/api2.php)

OAuth Authorize Endpoint: https://office.bexio.com/oauth/authorize (old https://office.easysys.ch/oauth/authorize) OAuth Access Token Endpoint: https://office.bexio.com/oauth/access_token (old https://office.easysys.ch/oauth/access_token) OAuth Refresh Token Endpoint: https://office.bexio.com/oauth/refresh_token (old https://office.easysys.ch/oauth/refresh_token)

Backward compatibility

The old API endpoints will work until end of april in 2016. We will disable access to the old endpoints from the 1st of May 2016. Please contact our support (support@bexio.com) if you have any questions about the api change.


New resources and english api documentation

Written by Marcel Lenz 2014-10-21

With the release of the latest version, a lot of new resources and actions have been added to the bexio API.

Documentation

The API documentation is now written in english for wider understanding.

New resources

The following resources have been added:

New API-calls for estimates, orders and invoices

We have added a lot of new methods for estimates, orders and invoices. You can fetch pdf files, send estimates/invoices by email, or create an invoice directly from the estimate.

New Timesheets API

We have added a new timesheet API. This API offers a better way to create / edit timesheets. Please note that the old timesheet API has been flagged as deprecated and will be removed in one of the upcomming updates.


Kontaktgruppen und Titel bearbeiten

Written by Marcel Lenz 2014-02-07

Mit dem Update vom 06.02.2014 wurde das bexio-API um einige Funktionen erweitert.

Titel

Titel können neu nicht nur gelesen sondern auch erstellt, bearbeitet und gelöscht werden. Nähere Details sind der Dokumentation zu den Titeln zu entnehmen.

Kontaktgruppen

Kontaktgruppen können nun ebenfalls erstellt und bearbeitet werden. Nähere Details sind der Dokumentation zu den Kontaktgruppen zu entnehmen.

Weitere Anpassungen an dem API

Zusätzlich wurden einige kleinere Änderungen an dem API vorgenommen.

  • Bei den Kontakten kann neu das Feld remarks (Bemerkungen) gelesen und bearbeitet werden.
  • Ebenso kann bei den Kontakten das Kontaktbild gelesen werden. Dies ist nur beim Aufruf einer einzelnen Ressource möglich. Als Resultat wird ein base64-encodierter String beim Wert profile_image zurückgegeben.
  • Angebote, Aufträge und Rechnungen lassen sich nun nach dem letzten Änderungsdatum (updated_at) suchen und sortieren.
  • Genau gleich lassen sich nun Kontaktverknüpfungen nach dem letzten Änderungsdatum (updated_at) suchen und sortieren.


Projekte, Zusatzadressen und neue Funktionen in der Auftragsverwaltung

Written by Marcel Lenz 2013-09-30

Mit dem Update vom 26.09.2013 wurde das bexio-API mit einem umfangreichen Update erweitert.

Projekte

Neu können Projekte über das API abgefragt und geändert werden. Nähere Details sind der Dokumentation zu den Projekten zu entnehmen. Ebenso sind die Ressourcen Projektstatus und Projekttypen dokumentiert.

Zusatzadressen

Ebenso können neu Zusatzadressen aufgelistet und erstellt werden. Diese Zusatzadressen können zudem bei Angeboten, Aufträgen und Rechnungen verwendet werden (z.B. mit dem Feld contact_address_id).

Erweiterung der Auftragsverwaltung

Mit dem neusten Update können Angebote via API akzeptiert oder abgelehnt werden. Dabei ist es wichtig, dass sich das Angebot im Status “Offen” befindet. Weiter wurde ein Referenzfeld api_reference hinzugefügt. Dieses kann ausschliesslich über das API ausgelesen und geändert werden und kann für Speicherung einer Referenz zu einem anderen System verwendet werden.


ETags und Änderungen an der Auftragsverwaltung

Written by Marcel Lenz 2013-08-30

Mit dem letzten Update wurden einige Verbesserungen an dem API vorgenommen.

ETag-Header

Viele Anfragen geben neu einen ETag-Header zurück. Anhand dieses Headers können Sie Änderungen an der Ressource nachvollziehen. Verändert sich die Ressource wird automatisch ein neuer ETag generiert. Bei Anfragen können Sie den Header If-None-Match verwenden. Hat sich die Ressource nicht verändert, erhalten Sie den Statuscode 304 Not Modified. Durch die Verwendung des Etag kann der Request deutlich beschleunigt werden.

Feld parent_id bei Positionen in der Auftragsverwaltung

Die Positionen der Ressourcen in der Auftragsverwaltung geben neu das Feld parent_id zurück. Dadurch können Unterpositionen besser erkannt werden.


Neue API-Dokumentation

Written by Marcel Lenz 2013-03-21

Im Rahmen des bexio-Updates vom 21. März 2013 wurde das API grundlegend erweitert. Nachfolgend werden die wichtigsten Änderungen in Kürze hervorgehoben. Bestehende API-Implementationen sind von den Änderungen nicht betroffen, das heisst die Applikationen müssen nicht angepasst werden.

Neue API-Dokumentation

Die API-Dokumentation wurde komplett überarbeitet. Neu werden die einzelnen Ressourcen und deren Parameter detaillierter beschrieben und mit Beispielen ergänzt. Bitte benutzen Sie für die Ansicht einer einzelnen Ressource die Navigation auf der linken Seite.

OAuth2

Die bexio-Schnittstelle unterstützt neu das Autorisations-Framework OAuth 2.0. Mit diesem Protokoll kann eine externe Applikation eine Autorisation für Accountdaten beantragen, ohne dabei das Passwort des Benutzers zu erhalten.

Die Implementation dieser OAuth2-Autentifikation ist aufgrund des umfangreicheren Standards nicht einfach. Für die Starthilfe empfehlen wir ein Studium der OAuth-Dokumentation und des Anwendungsbeispiels.

Der komplette Autorisationsprozess wurde auch für mobile Geräte wie Smartphones und Tablets optimiert.

Bisherige API (Mit Public und Signature Key)

Neben der OAuth-Autorisation wird auch nach wie vor die bisherige Autorisation mittels Public und Signature Key unterstützt. Ebenso werden auch zukünftige Änderungen an dem API für beide Autorisations-Methoden implementiert.

Für bisherige API-Nutzer ist keine Anpassung der Scripts notwendig.

 ”JSON-P”-Callbacks

Neue werden Callbacks mit JSON-P unterstützt. Diese Callbacks können für jede Ressource verwendet werden. Nähere Details zur Anwendung sind unter URL-Parameter zu finden.

HTTP-Status 422 - Unprocessable Entity

Neu wird der HTTP-Status “422 - Unprocessable Entity” für fehlerhafte Anfragen zurückgegeben. Dieser Status wird bei Validierungsfehlern innerhalb von Speicheraktionen (Erstellen, Bearbeiten, Überschreiben) verwendet.

Neu kann somit einfacher zwischen einem syntaktisch falschen Aufruf (z.B. fehlerhafter JSON-Body => HTTP-Status 400) und einem inhaltlich falschen Aufruf (z.B. fehlerhaftes Formularfeld => HTTP-Status 422) unterschieden werden.

Implementationsbeispiel

Als Starthilfe mit dem bexio-API und der OAuth-Autorisation stellen wir ein Implementationsbeispiel (realisiert mit PHP) zur Verfügung. Dieses Beispiel ist eine kleine Applikation, die sämtliche Länder eines bexio-Accounts mit der API ausliest.

Zu finden ist dieses Beispiel beim Menüpunkt Beispiele.