Produktaktualisierungen

Das Firma.dev TypeScript E-Signatur-SDK ist da: typisiert, abhängigkeitsfrei, jeder Endpunkt abgedeckt

Geschrieben von

Wenn Sie E-Signaturen bisher mit handgeschriebenen fetch-Aufrufen in Ihr Produkt integriert haben, ist diese Arbeit jetzt optional. Das offizielle Firma.dev TypeScript-SDK ist live auf npm. Ein typisierter Client, alle 66 Partner-API-Endpunkte, keine Runtime-Abhängigkeiten. Installieren Sie es und legen Sie mit dem Signieren los.

npm install @firma-dev/sdk
npm install @firma-dev/sdk
npm install @firma-dev/sdk

Was im TypeScript-E-Signatur-SDK enthalten ist

@firma-dev/sdk ist der offizielle, vollständig typisierte TypeScript-Client für die Firma.dev-API. Jeder Endpunkt wird als typisierte Methode bereitgestellt, gruppiert nach Ressourcen, sodass Sie Editor-Autovervollständigung und Sicherheit zur Kompilierzeit anstelle von manuellem HTTP-Aufwand erhalten. Der Client deckt alle 66 Endpunkte ab: Vorlagen, Signaturanfragen, Webhooks, Workspaces, benutzerdefinierte Felder, E-Mail-Domains, E-Mail-Vorlagen, Unterzeichner-Bedingungen, JWT-Verwaltung und Einstellungen.

Es läuft serverseitig auf Node 18 oder höher, nutzt das integrierte fetch, kommt ohne Runtime-Abhängigkeiten aus und ist unter MIT lizenziert. Die aktuelle Version ist 0.2.0.

Warum ein typisierter E-Signatur-API-Client wichtig ist

Das SDK wird direkt aus derselben OpenAPI-Spezifikation generiert, die auch die API-Referenz antreibt. Das bedeutet, dass die Struktur von Anfragen und Antworten immer mit der Live-API übereinstimmt. Wenn sich ein Endpunkt ändert, ändern sich die Typen mit ihm. So ist ein nicht übereinstimmendes Feld ein Kompilierungsfehler in Ihrem Editor und kein 400-Fehler, den Sie in der Produktion debuggen müssen.

Für ein SaaS-Team, das Signaturfunktionen in das eigene Produkt einbettet, entfällt dadurch eine ganze Kategorie an Glue-Code. Kein Pflegen einer maßgeschneiderten HTTP-Schicht mehr, kein Raten von Payload-Formaten mehr, kein erneutes Nachschlagen in der Referenz jedes Mal, wenn Sie einen Endpunkt anpassen. Agenturen, die Signatur-Workflows für Kunden automatisieren, profitieren vom selben Vorteil: Erstellen Sie die Integration einmalig anhand typisierter Methoden und lassen Sie den Compiler Abweichungen abfangen.

Ein kurzer Blick auf @firma-dev/sdk

Authentifizieren Sie sich mit einem einzigen API-Schlüssel. Der Client sendet ihn bei jeder Anfrage mit und parst die Antworten für Sie.

import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);

Das Warten auf eine Methode (await) gibt direkt den geparsten Antwort-Body zurück. Wenn Sie den HTTP-Status oder Header benötigen, rufen Sie .withRawResponse() auf:

const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));

Fehlgeschlagene Anfragen werfen einen typisierten FirmaError, der den Statuscode und den geparsten Fehler-Body enthält, sodass die Fehlerbehandlung lesbar bleibt:

import { FirmaClient, FirmaError } from "@firma-dev/sdk";

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body);       // parsed error payload
  } else {
    throw err;
  }
}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body);       // parsed error payload
  } else {
    throw err;
  }
}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body);       // parsed error payload
  } else {
    throw err;
  }
}

Bewahren Sie Ihren API-Schlüssel in einer Umgebungsvariable oder einem Secrets-Manager auf, niemals im clientseitigen Code. Das SDK ist für die serverseitige Nutzung konzipiert.

Lesen Sie die vollständige Anleitung. Installation, Authentifizierung, Schnellstart, gängige Operationen, Fehlerbehandlung und Paginierung werden alle in der Dokumentation behandelt: docs.firma.dev/guides/typescript-sdk. Jeder Endpunkt in der API-Referenz enthält jetzt ein Copy-Paste-Codebeispiel für @firma-dev/sdk, sodass Sie direkt einen funktionierenden Aufruf für Ihre exakten Parameter übernehmen können. Im Changelog-Eintrag v1.28.0 finden Sie die vollständige Übersicht zu v01.28.00.

Erste Schritte mit dem Firma.dev-SDK

Installieren Sie das SDK, fügen Sie Ihren API-Schlüssel ein und senden Sie Ihre erste Anfrage. Firma.dev ist nutzungsbasiert für 0,049 € pro Umschlag (ca. 5¢ USD) erhältlich – ganz ohne Verträge und ohne monatliche Mindestbeträge.

Starten Sie kostenlos mit Firma.dev, keine Kreditkarte erforderlich.

  1. Überschrift

Verwandte Artikel

Unsere Plattform wurde entwickelt, um Unternehmen jeder Größe zu befähigen, intelligenter zu arbeiten und ihre Ziele mit Zuversicht zu erreichen.

Hintergrundbild

Bereit, elektronischen Unterschriften zu Ihrer Anwendung hinzuzufügen?

Kostenlos starten. Keine Kreditkarte erforderlich. Zahlen Sie nur 0,049 € pro Umschlag, wenn Sie bereit sind, live zu gehen.

Hintergrundbild

Bereit, elektronischen Unterschriften zu Ihrer Anwendung hinzuzufügen?

Kostenlos starten. Keine Kreditkarte erforderlich. Zahlen Sie nur 0,049 € pro Umschlag, wenn Sie bereit sind, live zu gehen.

Hintergrundbild

Bereit, elektronischen Unterschriften zu Ihrer Anwendung hinzuzufügen?

Kostenlos starten. Keine Kreditkarte erforderlich. Zahlen Sie nur 0,049 € pro Umschlag, wenn Sie bereit sind, live zu gehen.