SignSolú
Operación

Tu SaaS crece diez veces: qué revisar en la API de firma antes de integrarla

10 min de lectura

Ocho cosas, y ninguna se nota con diez clientes. Que puedas probar con tu propio volumen sin pagar; que un reintento no cree un documento duplicado; que los avisos lleguen firmados, se reintenten y toleren llegar repetidos o en desorden; que cada llave tenga sólo los permisos de su sistema y se revoque al momento; que cada documento firmado traiga su propia evidencia; que el reporte se pueda partir por sede o por cliente; que puedas exportar todo y comprobarlo sin depender del proveedor; y que los topes y el nivel de servicio queden por escrito en tu contrato. Las cinco primeras se verifican tú mismo en una tarde con una llave de prueba.

Integrar una firma electrónica en un producto propio es un trabajo de días. Mantenerla cuando los clientes se multiplican por diez es otro, y los problemas no son los que se anticipan. Casi nunca es el volumen: son los reintentos, los avisos que llegan dos veces, la llave que alguien pegó en un repositorio y la pregunta incómoda de qué pasa con los contratos de tus clientes si un día decides cambiar de proveedor.

Esta lista es lo que conviene revisar antes de escribir la integración, no después. Está ordenada por lo que más duele cuando falla. Si lo que estás decidiendo es más atrás —si firmar dentro de tu producto o mandar a la gente a otra plataforma—, eso está en firmar dentro de tu sistema o en una plataforma aparte.

Las ocho revisiones antes de integrar una API de firma: modo de prueba con volumen propio, reintento sin duplicar, webhooks firmados, permisos por llave, evidencia por documento, reporte por sede o cliente, exportación y comprobación fuera de la plataforma, y topes y nivel de servicio por escrito
Las cinco primeras se comprueban solas, con una llave de prueba.

1 · Que puedas probar con tu propio volumen, sin pagar

Una demostración guiada no prueba nada de lo que te va a doler. Lo que sirve es un modo de prueba que se comporte igual que producción y donde puedas correr tu caso raro: el cliente con dos firmantes, el documento de cuarenta páginas, la fila con el correo mal escrito.

En SignSolú cualquier cuenta, también la gratis, crea llaves de prueba. Con ellas todo funciona igual, pero los documentos llevan la marca de agua «PRUEBA», no descuentan documentos de tu plan, no mandan correos a nadie y se borran solos a los 30 días. Una llave de prueba sólo ve documentos de prueba, así que no hay forma de mezclar los dos mundos. El tope de prueba es de 30 peticiones por minuto, más bajo a propósito.

2 · Que un reintento no te deje dos contratos

Es el defecto más caro y el más silencioso. Tu sistema manda la petición, la red se cae antes de la respuesta, tu código reintenta y el cliente recibe dos ligas. Firma la que abrió primero y te quedas con un documento firmado y otro vivo, los dos con el mismo contenido. Nadie se entera hasta que alguien concilia.

Lo que hay que preguntar es concreto: ¿cómo se identifica una petición repetida? En SignSolú, un reintento con la misma Idempotency-Key no crea un documento nuevo, y lo mismo con la referencia propia que le pongas a cada documento. Eso convierte el reintento en una operación segura y deja de ser un tema de nervios. Los detalles están en la guía para desarrolladores.

3 · Que los avisos lleguen firmados y toleren repetirse

El aviso de que alguien firmó —el webhook— es lo que te evita preguntar cada rato, y preguntar es lo que se come el presupuesto de peticiones: la cuenta completa está en cuántos documentos caben en los topes de una API de firma. Pero un webhook trae tres preguntas propias.

Firmado, para que no te lo inventen

Si tu endpoint acepta cualquier cosa que llegue con la forma correcta, cualquiera que adivine la dirección puede decirte que un contrato se firmó. Los avisos de SignSolú van firmados: tu sistema comprueba la firma antes de hacerle caso. Es una línea de código y es la diferencia entre un aviso y un rumor.

Repetido y en desorden, porque va a pasar

Un aviso se puede entregar dos veces —tu servidor tardó en contestar y el emisor reintentó— y dos avisos del mismo documento pueden llegar en orden distinto al que ocurrieron. Tu lado tiene que ser idempotente también: procesar el mismo aviso dos veces no debe cobrar dos veces ni mandar dos correos. La regla simple es guardar el identificador del evento y no volver a procesarlo.

Qué pasa si tu servidor estaba caído

Pregunta si los avisos se reintentan y por cuánto tiempo, y ten un camino de rescate: una consulta de estado para los documentos que se quedaron en el aire. Un sistema que depende sólo del webhook y no sabe reconciliar es un sistema que pierde documentos en cada caída.

4 · Que cada llave traiga sólo lo que ese sistema necesita

Con diez clientes hay una llave y la sabe todo el equipo. Con cien hay cuatro sistemas distintos usándola y nadie se acuerda de dónde está pegada. Lo que hay que poder hacer es dar permisos distintos a llaves distintas y revocar una sin tumbar las demás.

  • Una llave por sistema, no una para todo. El que sólo lee no debe poder crear documentos.
  • La llave se muestra una sola vez y se guarda donde guardas los demás secretos, nunca en el repositorio.
  • Revocación inmediata desde el panel, sin escribirle a nadie.
  • Las llaves de prueba y las reales no se mezclan: una de prueba sólo ve documentos de prueba.

5 · Que cada documento se defienda solo

Cuando el contrato se discute, lo que importa no es tu base de datos: es qué trae el documento. Un documento creado por la interfaz de programación tiene que salir con exactamente la misma evidencia que uno creado a mano, y eso se verifica en la prueba, no se asume.

En SignSolú cada documento firmado sale con su certificado de auditoría —hora, dirección IP, dispositivo y la huella SHA-256 del archivo— y cualquiera puede comprobarlo en /verificar sin abrir una cuenta. Encima, 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; los planes de paga incluyen 20 al mes. Qué trae el acuse está en qué es un acuse de auditoría y qué debe traer y qué acredita la constancia, en qué es la constancia de conservación NOM-151.

6 · Que el reporte se pueda partir como está partida tu operación

Si tu producto le sirve a cien empresas, el documento de cada una es de esa empresa y el reporte tiene que poder separarse. En SignSolú cada documento puede ir a nombre de una sede, la dirección ve el reporte por sede y se exportan los firmados de un periodo. Si tú eres quien vende el producto, esa misma columna es la que te deja darle a cada cliente su corte sin armarlo a mano.

7 · Que te puedas llevar todo, y que siga valiendo afuera

Es la pregunta que no se hace al integrar y es la que más caro sale después. Dos cosas distintas: poder exportar los documentos firmados con sus certificados, y que esos documentos se puedan comprobar sin depender del proveedor que los emitió. Lo segundo es lo que de verdad te suelta las manos.

En SignSolú lo ya firmado se comprueba sin SignSolú: la verificación pública está abierta a cualquiera en /verificar, el expediente de un documento se descarga completo y la constancia NOM-151 vive del lado del prestador acreditado. Qué hay que llevarse al mudarse, renglón por renglón, está en cambiar de plataforma de firma: qué te tienes que llevar, y el respaldo legal de todo esto en el Código de Comercio, explicado en Código de Comercio para no abogados.

8 · Que los topes y el nivel de servicio queden en tu contrato

Lo que está publicado en una página de ayuda se puede cambiar sin avisarte. Lo que está en tu contrato, no. Por eso esta última revisión no es técnica: es qué pides por escrito antes de firmar con el proveedor.

Qué pedir por escritoPor quéQué hace SignSolú
Los topes de uso por minuto y por díaSon el supuesto sobre el que diseñaste la integraciónPublicados: 120 por minuto y 10,000 al día por llave real
El nivel de servicioSin esto no hay a qué apelar cuando algo fallaSe pacta por escrito dentro del plan a la medida
La forma de exportar documentos y certificadosEs tu salida y la de tus clientesExportación de los firmados de un periodo y expediente por documento
Que cada documento se compruebe fuera de la plataformaTe deja de atar al proveedorVerificación pública abierta, sin cuenta
Cómo cuenta un documentoDecide tu costo real, no el precio de listaCuenta una vez, firmen cuantos firmen

Ese último renglón es el que más mueve la cuenta de un producto que crece. En SignSolú el plan de paga son $399 MXN al mes con 200 documentos, usuarios ilimitados y plantillas ilimitadas, y la interfaz viene incluida: un documento creado desde tu sistema cuenta igual que uno del panel. Arriba de 200 al mes hay plan a la medida y bolsa para el equipo, y ahí se escribe con tu volumen y tus sedes. La vista completa está en la API de firma electrónica y en para empresas; la cuenta, en cuánto cuesta firmar contratos en línea en México.

Cómo se verifica esta lista en una tarde

  1. 1Crea una llave de prueba y manda tres documentos: uno normal, uno con dos firmantes y uno con un correo inválido.
  2. 2Repite a propósito la misma petición de creación y comprueba que no nace un segundo documento.
  3. 3Apunta el webhook a tu servidor, firma un documento y verifica la firma del aviso antes de procesarlo.
  4. 4Manda el mismo aviso dos veces a tu endpoint y comprueba que tu lado no hace el trabajo dos veces.
  5. 5Descarga el documento firmado y su certificado, y compruébalo en la verificación pública sin iniciar sesión.
  6. 6Y lo que no es técnico: pide por escrito los topes, el nivel de servicio y la forma de exportar.

Los cinco primeros pasos no cuestan nada y contestan casi todo. El sexto es el que se olvida y el único que no se puede hacer después. Si tu caso empieza por una hoja de cálculo en vez de un sistema, el camino corto está en contratos masivos desde Excel; las preguntas generales para elegir plataforma, en cómo elegir plataforma de firma: 8 preguntas; y si lo que tu producto manda son contratos laborales o responsivas, las plantillas de sistema ya están armadas: contrato individual de trabajo, acuerdo de confidencialidad y contrato de prestación de servicios.

Una advertencia final, porque es el error de arquitectura más común: no todo documento se puede firmar electrónicamente, y conviene saber cuáles antes de que tu producto los mande solo. La lista está en documentos que no se pueden firmar electrónicamente, y los defectos que sí tumban una firma, en errores que invalidan una firma electrónica. Si además tu caso necesita firma avanzada, la diferencia está en firma simple y firma avanzada en México.

De dónde salen las citas

Preguntas frecuentes

¿Qué es lo primero que se rompe al crecer una integración de firma?

Los reintentos. Con pocos documentos una petición repetida pasa desapercibida; con muchos produce contratos duplicados y conciliaciones a mano. Se previene con una clave de idempotencia o con una referencia propia por documento, de modo que repetir la petición no cree uno nuevo.

¿Por qué importa que los webhooks vayan firmados?

Porque si tu endpoint acepta cualquier cosa con la forma correcta, cualquiera que adivine la dirección puede avisarte que un contrato se firmó. Comprobar la firma del aviso antes de procesarlo es una línea de código y es lo que separa un aviso de un rumor.

¿Qué tiene que dejarme hacer un modo de prueba para servir?

Correr tus casos raros sin pagar: el documento de cuarenta páginas, el contrato con dos firmantes, la fila con el correo mal escrito. En SignSolú cualquier cuenta crea llaves de prueba; esos documentos llevan marca de agua, no descuentan del plan, no mandan correos y se borran a los 30 días, y una llave de prueba sólo ve documentos de prueba.

¿Qué me llevo si decido cambiar de proveedor?

Dos cosas distintas: los documentos firmados con sus certificados, que se exportan por periodo, y la capacidad de comprobarlos sin el proveedor. En SignSolú cualquiera verifica un documento firmado en /verificar sin abrir cuenta, y el expediente completo de cada documento se descarga.

¿Un documento creado por la API trae la misma evidencia que uno del panel?

Sí: certificado de auditoría con hora, dirección IP, dispositivo y huella SHA-256, y la misma verificación pública. Los planes de paga incluyen además 20 constancias de conservación NOM-151 al mes, que se piden con un botón sobre el documento ya firmado.

¿Qué conviene pedir por escrito y no sólo leer en la documentación?

Los topes de uso por minuto y por día, el nivel de servicio, la forma de exportar documentos y certificados, que cada documento se pueda comprobar fuera de la plataforma y cómo cuenta un documento. Una página de ayuda cambia sin avisar; un contrato no.

Sigue leyendo

Prueba SignSolú con 10 documentos gratis