El SDK de firma electrónica de Firma.dev para TypeScript ya está aquí: tipado, sin dependencias y con cobertura para todos los endpoints

Si ha estado integrando firmas electrónicas en su producto mediante llamadas fetch escritas a mano, ese trabajo ahora es opcional. El SDK oficial de TypeScript para Firma.dev ya está disponible en npm. Un único cliente tipado, los 66 endpoints de la API de socios, sin dependencias en tiempo de ejecución. Instálelo y empiece a firmar.

npm install @firma-dev/sdk

npm install @firma-dev/sdk

npm install @firma-dev/sdk

Qué incluye el SDK de firma electrónica para TypeScript

@firma-dev/sdk es el cliente oficial de TypeScript, totalmente tipado, para la API de Firma.dev. Cada endpoint se expone como un método tipado, agrupado por recursos, lo que proporciona autocompletado en el editor y seguridad en tiempo de compilación en lugar de conexiones HTTP sin procesar. El cliente cubre los 66 endpoints: plantillas, solicitudes de firma, webhooks, espacios de trabajo, campos personalizados, dominios de correo electrónico, plantillas de correo electrónico, condiciones del firmante, gestión de JWT y configuración.

Se ejecuta en el lado del servidor en Node 18 o posterior, utiliza el comando integrado fetch, se distribuye sin dependencias en tiempo de ejecución y tiene licencia MIT. La versión actual es la 0.2.0.

Por qué es importante un cliente de API de firma electrónica tipado

El SDK se genera directamente a partir de la misma especificación OpenAPI que alimenta la referencia de la API. Esto significa que las estructuras de solicitud y respuesta siempre coinciden con la API activa. Cuando un endpoint cambia, los tipos cambian con él, por lo que un campo no coincidente es un error de compilación en su editor en lugar de un error 400 que deba depurar en producción.

Para un equipo de SaaS que integra la firma en su propio producto, esto elimina toda una categoría de código de acoplamiento. Se acabó el mantenimiento de una capa HTTP a medida, el tener que adivinar las estructuras de carga útil o tener que volver a leer la referencia cada vez que se toca un endpoint. Las agencias que automatizan los flujos de trabajo de firma de los clientes obtienen la misma ventaja: desarrollar la integración una sola vez con métodos tipados y dejar que el compilador detecte los desfases.

Un vistazo rápido a @firma-dev/sdk

Autentíquese con una sola clave de API. El cliente la envía en cada solicitud y analiza las respuestas por usted.

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);

Al esperar un método, se devuelve directamente el cuerpo de la respuesta analizado. Cuando necesite el estado o los encabezados HTTP, llame a .withRawResponse():

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"));

Las solicitudes fallidas lanzan un error tipado FirmaError que contiene el código de estado y el cuerpo del error analizado, por lo que la gestión de errores sigue siendo legible:

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;
  }
}

Mantenga su clave de API en una variable de entorno o en un gestor de secretos, nunca en el código del lado del cliente. El SDK está diseñado para uso en el lado del servidor.

Lea la guía completa. La instalación, la autenticación, la guía de inicio rápido, las operaciones habituales, la gestión de errores y la paginación se detallan en la documentación: docs.firma.dev/guides/typescript-sdk. Cada endpoint de la referencia de la API incluye ahora una muestra de @firma-dev/sdk lista para copiar y pegar, de modo que pueda obtener una llamada funcional para sus parámetros exactos. Consulte la entrada del registro de cambios v1.28.0 para ver el resumen completo de v01.28.00.

Primeros pasos con el SDK de Firma.dev

Instale el SDK, introduzca su clave de API y envíe su primera solicitud. Firma.dev es de pago por uso a 0,049 € por sobre (unos 5 centavos de dólar), sin contratos ni mínimos mensuales.

Comience a utilizar Firma.dev gratis, sin necesidad de tarjeta de crédito.