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_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXCada 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).
| Ruta | Para qué |
|---|---|
POST /v1/documents | Crear (y opcionalmente enviar) |
GET /v1/documents | Listar, con filtros por estado, referencia y fecha |
GET /v1/documents/{id} | Estado del documento y de cada firmante |
POST /v1/documents/{id}/send | Enviar un borrador |
POST /v1/documents/{id}/remind | Recordar a quien no ha firmado |
POST /v1/documents/{id}/cancel | Cancelar |
GET /v1/documents/{id}/files | Ligas temporales al PDF firmado, al certificado y a la constancia NOM-151 |
GET /v1/templates | Tus plantillas |
GET /v1/account | Plan, documentos disponibles y equipo |
POST /v1/exports | ZIP 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.
| Evento | Cuándo llega |
|---|---|
document.sent | El documento salió a firma |
signer.viewed | Un firmante abrió su liga por primera vez |
signer.signed | Un firmante firmó |
signer.declined | Un firmante rechazó firmar |
document.completed | Firmaron todos y el PDF firmado está listo |
document.cancelled | El documento se canceló |
document.expired | Venció la liga sin que firmaran todos |
nom151.issued | Se emitió la constancia NOM-151 |
nom151.failed | No 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
2xxen 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
idpara no repetir ycreadopara ordenar. La cabeceraSignSolu-Entregaidentifica cada entrega. - En
GET /v1/webhooks/{id}/deliveriesves cada entrega con sus intentos, yPOST …/deliveries/{entrega}/retryla reenvía al momento. - ¿Se filtró el secreto?
POST /v1/webhooks/{id}/rotate-secrette 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_…" } }| HTTP | Qué pasó |
|---|---|
| 400 | Algo en la petición no es válido; mensaje dice qué |
| 401 | Falta la llave, no existe o está revocada |
| 403 | La llave no tiene el permiso, o tu plan no tiene saldo |
| 404 | No existe, o no es de tu equipo |
| 409 | Conflicto: el estado del documento no lo permite, o la referencia ya existe |
| 422 | El PDF no se pudo leer |
| 429 | Pasaste el tope; espera lo que dice la cabecera Retry-After |
| 500 | Error 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
POSTaceptaIdempotency-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.