Para desarrolladores

Cómo agregar firmas electrónicas a su aplicación

Agregar firmas electrónicas a una aplicación toma una llamada HTTPS para enviar el PDF, un webhook para saber que se firmó y una llamada para descargar la copia certificada. Este tutorial hace las tres con la API de Signathing, en curl, Node y Python. Los primeros 100 documentos de cada mes son gratis y sin tarjeta, así que puede construir y probar todo el flujo sin pagar.

Antes de empezar: obtenga una clave

Inicie sesión en signathing.com con su correo o su número de celular, abra API en el panel y cree una clave. Para crear una clave se le pide verificar un número de celular de Estados Unidos por mensaje de texto, una sola vez. No se pide tarjeta. La clave empieza con sk_live_ y se muestra una sola vez, así que cópiela en ese momento y guárdela donde su aplicación guarda sus secretos, por ejemplo en una variable de entorno.

Cada solicitud envía la clave como token bearer a https://signathing.com/api/v1. No hay un modo de prueba aparte: los 100 documentos gratis al mes son el lugar para probar, y un documento anulado dentro de los diez minutos siguientes al envío no se cuenta.

export SIGNATHING_API_KEY="sk_live_..."

Paso 1: envíe un PDF para firma

El envío es un POST multipart a /api/v1/documents con tres partes: el PDF como file, un title y signers como un arreglo JSON. Cada firmante necesita un nombre y un correo o un número de celular de Estados Unidos. Signathing le envía a cada firmante un enlace privado por correo o mensaje de texto; firman en un navegador y no necesitan cuenta.

curl https://signathing.com/api/v1/documents \
  -H "Authorization: Bearer $SIGNATHING_API_KEY" \
  -F "file=@contract.pdf" \
  -F "title=Service agreement" \
  -F 'signers=[{"name":"Pat Lee","email":"pat@example.com"}]'

Qué vuelve

La respuesta es el documento en JSON, con estado HTTP 201. Guarde el id. Cada entrada de signers trae su propio signing_url, el mismo enlace privado que Signathing ya entregó, así que también puede enlazarlo desde su propia aplicación. El bloque billing dice cuánto costó el envío; charged_tenths es 0 mientras esté dentro de los 100 gratis. El ejemplo de abajo está recortado a las partes que usa la mayoría de las aplicaciones.

{
  "id": 71,
  "object": "document",
  "status": "sent",
  "title": "Service agreement",
  "signers": [
    {
      "id": 118,
      "name": "Pat Lee",
      "email": "pat@example.com",
      "status": "pending",
      "signing_url": "https://signathing.com/sign/..."
    }
  ],
  "downloads": {
    "original": "https://signathing.com/api/v1/documents/71/download?which=original",
    "signed": null
  },
  "billing": { "charged_tenths": 0, "unit_this_month": 1, "balance_tenths": 0 }
}

La misma llamada desde Node

Node 18 y posteriores traen fetch, FormData y Blob, así que no hay nada que instalar. Guarde esto como send.mjs y ejecútelo con node send.mjs.

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("contract.pdf")], { type: "application/pdf" }), "contract.pdf");
form.append("title", "Service agreement");
form.append("signers", JSON.stringify([{ name: "Pat Lee", email: "pat@example.com" }]));

const res = await fetch("https://signathing.com/api/v1/documents", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.SIGNATHING_API_KEY },
  body: form,
});
const doc = await res.json();
if (!res.ok) throw new Error(doc.error.code + ": " + doc.error.message);
console.log(doc.id, doc.status, doc.signers[0].signing_url);

La misma llamada desde Python

Con la biblioteca requests, el PDF va en files y las demás partes van en data.

import json
import os

import requests

with open("contract.pdf", "rb") as pdf:
    res = requests.post(
        "https://signathing.com/api/v1/documents",
        headers={"Authorization": "Bearer " + os.environ["SIGNATHING_API_KEY"]},
        files={"file": ("contract.pdf", pdf, "application/pdf")},
        data={
            "title": "Service agreement",
            "signers": json.dumps([{"name": "Pat Lee", "email": "pat@example.com"}]),
        },
    )

doc = res.json()
if not res.ok:
    raise SystemExit(doc["error"]["code"] + ": " + doc["error"]["message"])
print(doc["id"], doc["status"], doc["signers"][0]["signing_url"])

Paso 2: sepa cuándo se firmó

Configure una URL de webhook HTTPS en la sección API de su panel. Signathing le envía JSON por cada evento; el que espera la mayoría de las aplicaciones es document.completed, enviado cuando todos los firmantes han firmado. El cuerpo es un objeto con id, event, created_at y data, donde data tiene la misma forma de documento que devolvió el envío.

Compruebe el encabezado Signathing-Signature antes de confiar en un webhook. Dice t=<segundos unix>,v1=<hex>, donde v1 es el HMAC-SHA256 de t, un punto y el cuerpo de la solicitud tal como llegó, con su secreto de webhook como clave. Responda con cualquier estado 2xx en menos de diez segundos; cualquier otra respuesta se reintenta. Si su aplicación no puede recibir webhooks, consulte GET /api/v1/documents/:id y lea status.

import crypto from "node:crypto";

// rawBody is the request body exactly as received, before any JSON parsing.
export function isFromSignathing(rawBody, header, secret) {
  const [t, v1] = header.split(",").map((part) => part.split("=")[1]);
  const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Paso 3: descargue el PDF certificado

Cuando status es completed, la copia firmada está a un GET de distancia. Es el original con las firmas estampadas, más una página de certificado que lista a cada firmante, la hora en que firmó y un código de verificación que cualquiera puede comprobar en signathing.com/verify.

curl "https://signathing.com/api/v1/documents/71/download?which=signed" \
  -H "Authorization: Bearer $SIGNATHING_API_KEY" \
  -o signed.pdf

Ponga la firma donde usted quiera

Sin campos, los firmantes firman en una página de certificado agregada al final del PDF, lo cual basta para muchos documentos. Para poner la firma sobre una línea de su propio diseño, agregue una parte fields al envío: un arreglo JSON de cajas medidas en porcentaje de la página desde la esquina superior izquierda. signerIndex es la posición del firmante en su arreglo signers, empezando en 0.

Los tipos de campo son signature, initials, date, name, email, text, number, checkbox, radio, dropdown y attachment. La página para desarrolladores lista las opciones de cada uno.

  -F 'fields=[{"id":"sig1","type":"signature","signerIndex":0,"page":1,"x":10,"y":70,"w":28,"h":5.5},
              {"id":"date1","type":"date","signerIndex":0,"page":1,"x":45,"y":70,"w":16,"h":3.2}]'

Límites que conviene conocer mientras construye

Los primeros 100 documentos de cada mes son gratis. Después un documento cuesta $0.06, y baja con el volumen, pagado desde un saldo prepagado; no hay suscripción. Una cuenta nueva puede enviar 10 documentos por la API al día durante sus primeros 7 días, y ese límite se levanta solo. Un documento admite hasta 25 firmantes y un PDF de hasta 50 MB, y la API acepta 120 solicitudes por minuto.

Los errores vuelven como un objeto con error.code y error.message y un estado HTTP acorde: 401 por una clave incorrecta, 400 por una solicitud incorrecta, 402 cuando se usaron los documentos gratis y el saldo está vacío, y 429 cuando envía demasiado rápido.

Preguntas frecuentes

¿Hay un entorno de pruebas o modo de prueba?
No hay uno aparte. Los 100 documentos gratis al mes sirven tanto para probar como para el uso real, y un documento anulado dentro de los diez minutos siguientes al envío no se cuenta.
¿Quienes firman necesitan una cuenta de Signathing?
No. Cada firmante abre un enlace privado desde un correo o un mensaje de texto y firma en un navegador. Solo su aplicación tiene una clave.
¿Puedo mostrar la página de firma dentro de mi propia aplicación?
Enlace el signing_url o ábralo en una pestaña nueva o en un navegador dentro de la aplicación. La página de firma no se puede colocar en un marco dentro de otro sitio.
¿Hay un SDK para mi lenguaje?
No hace falta. La API es HTTPS simple con multipart y JSON, y la descripción OpenAPI en signathing.com/api/v1/openapi.json puede generar un cliente para la mayoría de los lenguajes.
¿Las firmas recogidas así están reconocidas?
Las firmas electrónicas están reconocidas conforme a la ley federal ESIGN y las leyes UETA estatales. Cada firmante acepta firmar electrónicamente antes de firmar, y la página de certificado registra quién firmó y cuándo.

Los precios y límites mostrados son los de Signathing a noviembre de 2026. Signathing presta el servicio de firma y no es parte de ningún acuerdo firmado a través de él.

Más en aprender

¿Son legales las firmas electrónicas?Cómo enviar para firmaCómo verificar una firmaAPI de firma electrónica gratisServidor MCP para firmas electrónicasRegistro de auditoría verificable para agentes¿Se puede firmar un arrendamiento electrónicamente?Órdenes de cambio desde un teléfonoExenciones en un teléfonoAcuerdos de subcontrataciónContratos freelanceAcuerdos entre compañeros de pisoQué todavía necesita papel o notario¿El firmante necesita una cuenta?Firma escrita vs dibujadaEnviar para firma por mensaje de textoPagos al firmar: reembolsos, tarjetas rechazadas y el certificado¿Necesito un contrato para un trabajo pequeño?La disputa por la orden de cambioAcuerdo de subarrendamiento: ¿lo necesito?¿Necesito una autorización de imagen?El subcontratista que empezó antes de acordar el alcanceGuardar el bote, el remolque o las herramientas de otroLa pelea por el depósito que evita una lista de entrada¿Qué es una renuncia de gravamen condicional?Mostrar una idea a un socio sin NDAPrestar dinero a la familiaVender una camioneta o equipo usado tal como estáGarantías personales que luego se nieganSolicitudes de crédito comercialPagos recurrentes y el contracargoAcuses del manual, 100 personas a la vezConstancia de seguridad que resiste una revisión de incidenteAumentos de precio para clientes actualesVentas tal como está y pedidos a medida sin devoluciónAcuses de daños y condiciónAdmisión y consentimiento en gimnasios, salones y estudiosAcuses de contratista independienteCuando un agente de IA acepta términos por ustedPara equipos de software: cambie la casilla por un paso de firma

Gratis, y no del tipo de gratis con truco

Documentos ilimitados, hasta 25 firmantes cada uno, PDF certificados en todos. Sin periodo de prueba y sin tarjeta para empezar.

Empiece a firmar gratis