Zoho.ts - eine Open-Source Typescript-Library für die Zoho Finance Suite

Bei der Integration von Zoho Inventory und Zoho Books in einen Kundenstack haben wir festgestellt, dass wir eine Typescript-Bibliothek für die API-Endpunkte benötigen. Nachdem wir über ein Jahr lang mit der Bibliothek in der Produktion gearbeitet hatten, haben wir beschlossen, sie als Open-Source Projekt zu veröffentlichen, in der Hoffnung, Entwicklern viele Kopfschmerzen zu ersparen. Klick hier, um direkt zum Github Repo der Bibliothek zu gelangen

Die Zoho Finance Suite

Die Zoho Corporation betreibt die Zoho Finance Suite, die aus einer Sammlung verschiedener SaaS-Geschäftsanwendungen besteht. Die Zoho Corporation selbst hat ihren Sitz in Indien und ihre Softwarelösungen werden rund um den Globus eingesetzt. Es ist erwähnenswert, dass sie ein sehr reichhaltiges Portfolio an spezialisierten Geschäftsanwendungen zu einem wettbewerbsfähigen Preis anbieten.

Die am häufigsten verwendeten Anwendungen der Zoho Finance Suite sind Zoho Books, Zoho Inventory und Zoho Invoice. Diese Anwendungen umfassen gut dokumentierte APIs, so dass sie in den bestehenden Technologie-Stack eines Unternehmens integriert werden können. Sie scheinen auf der gleichen Technologie zu laufen, da ihre REST-API-Endpunkte einander sehr ähnlich sind. Diese Tatsache hat uns veranlasst, eine generische Bibliothek für diese drei Dienste zu erstellen.

Installation und Konfiguration der Bibliothek

Die Typescript-Bibliothek ist bei NPM veröffentlicht: https://www.npmjs.com/package/@trieb.work/zoho-ts

Abhängig vom benutzen Paketmanager kann die Lib einfach installiert werden:

npm i @trieb.work/zoho-ts

Oder mit Yarn:

yarn i @trieb.work/zoho-ts

Um die Bibliothek auf dem Server zu verwenden, muss eine neue Instanz der Bibliothek erstellt werden:

import { Zoho, ZohoApiClient } from "@trieb.work/zoho-ts";

const zoho = new Zoho(
    await ZohoApiClient.fromOAuth({
      orgId: "243546",
      dc: ".com", # Ihr Rechenzentrum - z.B. .com, .eu
      apiFlavour: "invoice", # Wählen sie hier, ob sie Books, Invoice oder Inventory verwenden möchten
      scope: "ZohoInvoice.fullaccess.all" # Optional
      client: {
        id: "",
        secret: "",
      },
    }),
  );

Hier sind mehrere Konfigurationsoptionen möglich. Zoho-Tenants können sich in verschiedenen Rechenzentren befinden. Es muss das richtige ausgewählt werden, in dem sich dein Tenant befindet.

Authentifizierung mit der Zoho API

Zoho verwendet die OAuth2-Technologie zur Authentifizierung von Anfragen an die API und die Daten des Tenants. Da die Bibliothek für den Einsatz auf einem Server konzipiert ist, haben wir einen OAuth-Client integriert, der die Token-Erstellung übernimmt. Im Moment muss die "Self-Client"-Methode verwendet werden, bei der eine Client-ID und ein Client-Secret erstellt werden, die die Bibliothek verwendet, um ein kurzlebiges Token zu erstellen, mit dem alle folgenden Anfragen an die Zoho-API authentifiziert werden. Möglicherweise fügen wir hier neue Funktionen hinzu, um andere OAuth-Flows zu unterstützen, die mehr Benutzerinteraktion und Aktualisierungs-Tokens erfordern.

Unterstützung und Github-Repository

Der Quellcode, die Dokumentation und die geschriebenen Tests können im öffentlichen Github-Repository der Bibliothek gefunden werden. Das Plugin kann geforked werden, um weitere Funktionen hinzuzufügen oder um Probleme direkt selbst zu lösen. Solltet ihr interessante Änderungen gemacht haben die ihr der Community zurückspielen wollt akzeptieren wir sehr gerne eure Pull-Requests.