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

Wenn Sie bisher elektronische Signaturen mit selbst geschriebenen fetch-Aufrufen in Ihr Produkt integriert haben, ist diese Arbeit ab sofort optional. Das offizielle Firma.dev TypeScript SDK ist jetzt auf npm verfügbar. Ein typisierter Client, alle 66 Partner-API-Endpunkte, keine Laufzeitabhängigkeiten. Installieren Sie es und beginnen Sie mit dem Signieren.

npm install @firma-dev/sdk

npm install @firma-dev/sdk

npm install @firma-dev/sdk

Was das TypeScript-E-Signatur-SDK bietet

@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 die automatische Vervollständigung im Editor und Typsicherheit zur Kompilierzeit anstelle von rohem HTTP-Code erhalten. Der Client deckt alle 66 Endpunkte ab: Vorlagen, Signaturanforderungen, Webhooks, Arbeitsbereiche, benutzerdefinierte Felder, E-Mail-Domains, E-Mail-Vorlagen, Unterzeichnerbedingungen, JWT-Verwaltung und Einstellungen.

Es läuft serverseitig auf Node 18 oder neuer, nutzt das integrierte fetch, kommt ohne Laufzeitabhängigkeiten aus und ist unter der MIT-Lizenz 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 speist. 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. Ein nicht übereinstimmendes Feld ist also ein Kompilierungsfehler in Ihrem Editor und kein 400-Fehler, den Sie mühsam in der Produktionsumgebung debuggen müssen.

Für ein SaaS-Team, das Signaturen in das eigene Produkt einbettet, entfällt damit eine ganze Kategorie von Hilfscode. Kein mühsames Pflegen einer eigenen HTTP-Ebene mehr, kein Rätselraten über die Datenstruktur und kein erneutes Nachschlagen in der Referenz bei jeder Änderung an einem Endpunkt. Agenturen, die Signatur-Workflows für Kunden automatisieren, profitieren gleichermaßen: Einmal die Integration gegen typisierte Methoden aufbauen und den Compiler eventuelle Abweichungen abfangen lassen.

Ein kurzer Blick auf @firma-dev/sdk

Authentifizieren Sie sich mit einem einzigen API-Schlüssel. Der Client sendet diesen bei jeder Anfrage mit und analysiert 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 Erwarten einer Methode gibt direkt den analysierten Antwortkörper zurück. Wenn Sie den HTTP-Status oder die 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 analysierten Fehlerkörper 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); // z.B. 404
    console.error(err.body);       // analysierte Fehlerdaten
  } 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); // z.B. 404
    console.error(err.body);       // analysierte Fehlerdaten
  } 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); // z.B. 404
    console.error(err.body);       // analysierte Fehlerdaten
  } 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 den serverseitigen Einsatz konzipiert.

Lesen Sie die vollständige Anleitung. Installation, Authentifizierung, Schnellstart, allgemeine Operationen, Fehlerbehandlung und Paginierung werden in der Dokumentation behandelt: docs.firma.dev/guides/typescript-sdk. Jeder Endpunkt in der API-Referenz enthält jetzt ein Copy-and-Paste-Beispiel für das @firma-dev/sdk, sodass Sie direkt einen funktionierenden Aufruf für Ihre exakten Parameter parat haben. Siehe den Changelog-Eintrag v1.28.0 für die vollständige Übersicht zu v01.28.00.

Erste Schritte mit dem Firma.dev SDK

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

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