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

Wenn Sie e-Signaturen bisher über handgeschriebene fetch-Aufrufe mit Ihrem Produkt verdrahtet haben, ist diese Arbeit ab 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 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 statt nackten HTTP-Verbindungen erhalten. Der Client deckt alle 66 Endpunkte ab: Vorlagen, Signaturanfragen, Webhooks, Arbeitsbereiche, benutzerdefinierte Felder, E-Mail-Domains, E-Mail-Vorlagen, Bedingungen für Unterzeichner, JWT-Verwaltung und Einstellungen.

Es läuft serverseitig auf Node 18 oder neuer, nutzt das integrierte fetch, kommt ohne Runtime-Abhä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 400er-Fehler, den Sie mühsam in der Produktionsumgebung debuggen müssen.

Für ein SaaS-Team, das Signaturen in das eigene Produkt einbindet, entfällt damit eine ganze Kategorie an Hilfscode. Kein eigener HTTP-Layer mehr, der gewartet werden muss, kein Rätselraten mehr bei den Payload-Strukturen und kein erneutes Nachschlagen in der Referenz bei jedem Zugriff auf einen Endpunkt. Agenturen, die die Signatur-Workflows ihrer Kunden automatisieren, profitieren gleichermaßen: Die Integration wird einmalig gegen typisierte Methoden aufgebaut, und der Compiler fängt Abweichungen automatisch ab.

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 parst die Antworten automatisch 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 geparsten Antwort-Body zurück. Wenn Sie den HTTP-Status oder die Header benötigen, rufen Sie einfach .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 ausschließlich für die serverseitige Nutzung konzipiert.

Lesen Sie die vollständige Anleitung. Installation, Authentifizierung, Schnellstart, allgemeine Operationen, Fehlerbehandlung und Paginierung werden in den Docs abgedeckt: docs.firma.dev/guides/typescript-sdk. Jeder Endpunkt in der API-Referenz enthält nun ein fertiges @firma-dev/sdk Code-Beispiel zum Kopieren und Einfügen, sodass Sie direkt einen funktionierenden Aufruf für Ihre exakten Parameter parat haben. Details finden Sie im Changelog-Eintrag v1.28.0 für die komplette v01.28.00 Übersicht.

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 absolut flexibel mit einer Abrechnung nach Nutzung (Pay-as-you-go) für €0,049 pro Umschlag (ca. 5¢ USD) – ganz ohne Verträge oder monatliche Mindestumsätze.

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