API de firma electrónica para desarrolladores

Integra la firma electrónica de SignSolú a tu sistema: llaves, primer documento, webhooks firmados, constancia NOM-151 a solicitud, modo prueba y topes.

Llaves

Las llaves se crean en tu panel, en Desarrolladores. Hay dos clases: ssk_live_… para documentos reales y ssk_test_… para probar. La llave completa se muestra una sola vez; guárdala en tu gestor de secretos, nunca en el código del navegador ni en una app móvil.

Cada petición la lleva en la cabecera Authorization:

Authorization: Bearer ssk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Cada llave tiene permisos: documents:read, documents:write, templates:read, account:read, webhooks:read, webhooks:write y exports:write (escribir incluye leer). Dale a cada sistema sólo los que necesita. Si una llave se filtra, revócala en el panel: deja de valer en ese momento.

Tu primer documento

Manda el PDF en Base64, los firmantes y enviar: true. La referencia es tu número interno (pedido, expediente, crédito): no se repite dentro de tu equipo, así que repetir la petición no crea dos documentos.

curl https://signsolu.com/api/v1/documents \
  -H "Authorization: Bearer $SIGNSOLU_LLAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{
    "titulo": "Contrato de arrendamiento - Depto 3B",
    "referencia": "pedido-1042",
    "pdf_base64": "JVBERi0xLjcK...",
    "firmantes": [
      { "nombre": "Ana López", "correo": "ana@ejemplo.mx", "canal": "email", "orden": 1,
        "campos": [{ "pagina": 3, "x": 0.12, "y": 0.8, "w": 0.3, "h": 0.06 }] },
      { "nombre": "Luis Pérez", "telefono": "+525512345678", "canal": "whatsapp", "orden": 2,
        "campos": [{ "ancla": "Firma del arrendatario" }] }
    ],
    "orden_estricto": true,
    "vence_en_dias": 30,
    "enviar": true
  }'

La respuesta trae el id del documento, su estado y la liga de cada firmante. Las cajas de firma van en fracciones de la hoja (de 0 a 1, desde la esquina de arriba a la izquierda) o por un texto ancla del PDF: la caja nace donde empieza ese texto. También puedes crear desde una de tus plantillas con template_id y datos, o subir el archivo como multipart/form-data (file y datos).

RutaPara qué
POST /v1/documentsCrear (y opcionalmente enviar)
GET /v1/documentsListar, con filtros por estado, referencia y fecha
GET /v1/documents/{id}Estado del documento y de cada firmante
POST /v1/documents/{id}/sendEnviar un borrador
POST /v1/documents/{id}/remindRecordar a quien no ha firmado
POST /v1/documents/{id}/cancelCancelar
GET /v1/documents/{id}/filesLigas temporales al PDF firmado, al certificado y a la constancia NOM-151
GET /v1/templatesTus plantillas
GET /v1/accountPlan, documentos disponibles y equipo
POST /v1/exportsZIP con los firmados de un periodo, sus certificados y un índice con huellas

Webhooks

En vez de preguntar cada minuto, registra una dirección https y te avisamos de cada cambio. Sólo se aceptan direcciones públicas con https.

curl https://signsolu.com/api/v1/webhooks \
  -H "Authorization: Bearer $SIGNSOLU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tu-sistema.mx/signsolu/eventos",
        "eventos": ["document.completed", "signer.declined", "nom151.issued"] }'

La respuesta trae el secreto (whsec_…) una sola vez. Sin eventos recibes todos. Con POST /v1/webhooks/{id}/test te mandamos un evento de prueba al momento.

EventoCuándo llega
document.sentEl documento salió a firma
signer.viewedUn firmante abrió su liga por primera vez
signer.signedUn firmante firmó
signer.declinedUn firmante rechazó firmar
document.completedFirmaron todos y el PDF firmado está listo
document.cancelledEl documento se canceló
document.expiredVenció la liga sin que firmaran todos
nom151.issuedSe emitió la constancia NOM-151
nom151.failedNo se pudo emitir la constancia (trae el motivo)

Cada aviso es un POST con este cuerpo. Trae lo mínimo: para el detalle, consulta el documento con su id. No incluye correos, teléfonos ni datos de identificación de los firmantes.

{
  "id": "evt_8f2c1a0e5b6d4c3a9e7f1b2d3c4a5e6f",
  "tipo": "document.completed",
  "creado": "2026-11-14T18:22:05.000Z",
  "modo": "live",
  "datos": {
    "documento": { "id": "0b1c…", "estado": "completed", "referencia": "pedido-1042" },
    "completado_at": "2026-11-14T18:22:04.913Z"
  }
}

Verifica SIEMPRE la firma antes de creerle. La cabecera SignSolu-Firma trae t (segundos Unix) y v1, el HMAC-SHA256 en hexadecimal de t + "." + cuerpo con tu secreto. Usa el cuerpo tal como llegó, sin volver a serializarlo, y rechaza lo que tenga más de 5 minutos.

// Node.js (Express): el cuerpo crudo, sin JSON.parse antes de verificar
import crypto from "node:crypto";

function firmaValida(cabecera, cuerpo, secreto, toleranciaSeg = 300) {
  let t = null;
  const firmas = [];
  for (const parte of String(cabecera ?? "").split(",")) {
    const [k, v = ""] = parte.trim().split("=", 2);
    if (k === "t" && /^\d{1,12}$/.test(v)) t = Number(v);
    if (k === "v1" && /^[0-9a-f]{64}$/.test(v)) firmas.push(Buffer.from(v, "hex"));
  }
  // Fuera de la ventana = repetición de un aviso viejo: se rechaza.
  if (t === null || firmas.length === 0 || Math.abs(Date.now() / 1000 - t) > toleranciaSeg) return false;
  const esperada = crypto.createHmac("sha256", secreto)
    .update(Buffer.concat([Buffer.from(`${t}.`), Buffer.from(cuerpo)])).digest();
  // Mismo largo (32 bytes) siempre: timingSafeEqual nunca truena.
  return firmas.some((f) => crypto.timingSafeEqual(f, esperada));
}

app.post("/signsolu/eventos", express.raw({ type: "application/json" }), (req, res) => {
  if (!firmaValida(req.get("SignSolu-Firma"), req.body, process.env.SIGNSOLU_WHSEC)) {
    return res.status(400).send("firma inválida");
  }
  const evento = JSON.parse(req.body);
  // Guarda evento.id: si ya lo procesaste, contesta 200 y no hagas nada
  // (dentro de los 5 minutos alguien podría repetir el mismo aviso).
  res.sendStatus(200);
});
# Python (Flask)
import hashlib, hmac, os, re, time
from flask import Flask, request, abort

app = Flask(__name__)

def firma_valida(cabecera, cuerpo, secreto, tolerancia=300):
    t, firmas = None, []
    for parte in (cabecera or "").split(","):
        k, _, v = parte.strip().partition("=")
        if k == "t" and re.fullmatch(r"\d{1,12}", v):
            t = int(v)
        if k == "v1" and re.fullmatch(r"[0-9a-f]{64}", v):
            firmas.append(v)
    # Fuera de la ventana = repetición de un aviso viejo: se rechaza.
    if t is None or not firmas or abs(time.time() - t) > tolerancia:
        return False
    esperada = hmac.new(secreto.encode(), f"{t}.".encode() + cuerpo, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(esperada, f) for f in firmas)

@app.post("/signsolu/eventos")
def eventos():
    cuerpo = request.get_data()  # bytes, tal como llegaron
    if not firma_valida(request.headers.get("SignSolu-Firma"), cuerpo, os.environ["SIGNSOLU_WHSEC"]):
        abort(400)
    evento = request.get_json()
    # Guarda evento["id"]: si ya lo procesaste, contesta 200 y no hagas nada.
    return "", 200
  • Contesta con un 2xx en menos de 10 segundos y procesa después. Una redirección cuenta como fallo.
  • Si fallas, reintentamos con espera creciente (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h y cada 24 h) durante 72 horas.
  • Si en 72 horas no aceptas ni una entrega, el webhook se apaga. Lo reactivas con POST /v1/webhooks/{id}/enable.
  • Puede llegarte el mismo evento dos veces y no siempre en orden: usa id para no repetir y creado para ordenar. La cabecera SignSolu-Entrega identifica cada entrega.
  • En GET /v1/webhooks/{id}/deliveries ves cada entrega con sus intentos, y POST …/deliveries/{entrega}/retry la reenvía al momento.
  • ¿Se filtró el secreto? POST /v1/webhooks/{id}/rotate-secret te da uno nuevo y el anterior deja de valer.

Constancia NOM-151

SignSolú emite la constancia de conservación NOM-151 del documento firmado a través de un Prestador de Servicios de Certificación acreditado por la Secretaría de Economía. Se activa a solicitud para tu equipo.

Cuando se emite la constancia de un documento te avisamos con nom151.issued y la descargas desde GET /v1/documents/{id}/files. Si no se pudo emitir, llega nom151.failed con el motivo. Los documentos de prueba nunca la piden.

Modo prueba

Con una llave ssk_test_… todo funciona igual, pero los documentos quedan marcados como de prueba: no piden constancia NOM-151 y sus eventos sólo llegan a los webhooks que diste de alta con una llave de prueba. Úsala para tu ambiente de desarrollo y tus pruebas automáticas.

Errores

Todos los errores tienen la misma forma. Guarda el request_id si nos escribes a soporte.

{ "error": { "codigo": "documento_no_encontrado", "mensaje": "No existe ese documento", "request_id": "req_…" } }
HTTPQué pasó
400Algo en la petición no es válido; mensaje dice qué
401Falta la llave, no existe o está revocada
403La llave no tiene el permiso, o tu plan no tiene saldo
404No existe, o no es de tu equipo
409Conflicto: el estado del documento no lo permite, o la referencia ya existe
422El PDF no se pudo leer
429Pasaste el tope; espera lo que dice la cabecera Retry-After
500Error nuestro; reintenta con la misma Idempotency-Key

Topes

  • Llave live: 120 peticiones por minuto y 10,000 por día.
  • Llave test: 30 peticiones por minuto.
  • Todo POST acepta Idempotency-Key: si repites la petición con la misma clave en 24 horas, te devolvemos la misma respuesta sin hacer nada dos veces.
  • Máximo 10 webhooks por cuenta y modo.

¿Necesitas más, o quieres que te ayudemos con la integración? Escríbenos desde contacto.

Precio y términos

Las llaves de prueba no cuestan nada. Las de producción vienen incluidas en los planes de paga, sin costo aparte: cada documento que creas por la API se descuenta de tu plan o de la bolsa de tu equipo, igual que en el panel. Si firmas miles de documentos al mes, escríbenos y te armamos un plan a la medida.

Para quién es y qué resuelve, en corto: API de firma electrónica para empresas. El uso de la API se rige por sus términos de uso.