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 la firma electrónica en su producto mediante llamadas de tipo 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 partners y sin dependencias de 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 de TypeScript oficial y totalmente tipado para la API de Firma.dev. Cada endpoint se expone como un método tipado, agrupado por recurso, de modo que dispondrá de autocompletado en el editor y seguridad en tiempo de compilación en lugar de conexiones HTTP sin formato. 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 de firmantes, gestión de JWT y configuraciones.

Se ejecuta en el lado del servidor en Node 18 o superior, utiliza el método incorporado fetch, se presenta sin dependencias de 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. Eso significa que las estructuras de solicitud y respuesta siempre coinciden con la API real. Cuando un endpoint cambia, los tipos cambian con él, por lo que un campo que no coincida genera 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 tener que mantener una capa HTTP personalizada, adivinar las formas de las cargas útiles o volver a leer la referencia cada vez que se modifica un endpoint. Las agencias que automatizan los flujos de trabajo de firma de los clientes obtienen las mismas ventajas: desarrollan la integración una vez con métodos tipados y dejan que el compilador detecte desviaciones.

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

Autentíquese con una sola clave de API. El cliente la envía con cada solicitud y analiza las respuestas de forma automática.

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 consultar las cabeceras o el estado 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 devuelven un error tipado de tipo FirmaError que incluye el código de estado y el cuerpo del error analizado, por lo que el manejo 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 su 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 comunes, la gestión de errores y la paginación se detallan en la documentación: docs.firma.dev/guides/typescript-sdk. Ahora, cada endpoint de la referencia de la API incluye un ejemplo para copiar y pegar de @firma-dev/sdk, de modo que pueda obtener una llamada de prueba que funcione con sus parámetros exactos. Consulte la entrada del registro de cambios v1.28.0 para ver el resumen completo de la versión v01.28.00.

Empiece a utilizar el SDK de Firma.dev

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

Empiece a utilizar Firma.dev de forma gratuita, sin necesidad de tarjeta de crédito.