Conceptos
El vocabulario de Firmame.
Antes de escribir código conviene fijar ocho términos.
Documento
El PDF que se firma. Al crearlo, Firmame le asigna un identificador único que vas a usar en todas las llamadas posteriores.
const { document_ticket } = await services.request({ /* … */ });
// más tarde, el mismo valor:
await services.docs({ ticket: document_ticket, action: 'delete' });
// y en el webhook que te llega:
// { "firmamex_id": "04337396-e929-43ca-9b8a-ec958a44079d", … }Sticker
Un recuadro de firma: una persona, en un lugar, en una página. Un documento sin stickers se guarda, pero nadie puede firmarlo.
Cada sticker define quién firma (data), cómo se verifica esa persona (authority), en qué página va
(page) y en qué coordenadas (rect).
Hay dos formas de colocarlos: mandándolos en el arreglo stickers con coordenadas explícitas, o
dibujándolos dentro del PDF para que Firmame los encuentre.
Authority
El método con el que el firmante comprueba que es quien dice ser: su certificado del SAT, una liga que recibe por correo, un PIN por WhatsApp, un SMS.
Es la decisión de más peso de cada sticker: define qué queda comprobado de la persona que firmó, y por lo tanto qué evidencia respalda esa firma después. No comprueban lo mismo un certificado del SAT y una liga enviada por correo.
También determina quién manda la invitación. Con las autoridades por liga, Firmame la envía
automáticamente y solo el firmante tiene la URL que autoriza firmar a su nombre. Con SAT, EMAIL y
SMS, si no configuras un flujo, repartir la URL de firma es responsabilidad tuya.
El catálogo completo está en el esquema Authority de la
referencia.
Verificación de identidad
Una capa adicional sobre la authority: además de verificar el canal, el firmante comprueba con una
identificación oficial y una prueba de vida —una selfie que confirma que es una persona real, no una
foto ni una pantalla— que es quien dice ser.
Se activa por sticker con requireIdentityVerification, y consume créditos adicionales de la cuenta. Ver
Verificación de identidad.
Flujo de firma
La configuración de cómo se recolectan las firmas: en orden o en paralelo, cada cuánto se recuerda a quien falta, cuándo expira, quién recibe copia sin firmar.
Sin flujo, tienes un documento firmable y tú decides cómo hacérselo llegar a cada persona. Con flujo, Firmame manda las invitaciones, los recordatorios y avisa cuando se completa.
Se puede adjuntar al crear el documento o agregarse después. Ver Flujos de firma.
Expediente
Un paquete de varios documentos que se firman juntos: una invitación, un orden de firma, una conclusión.
El ciclo es crear el expediente, agregarle documentos, y cerrarlo para arrancar el flujo. Ver Expedientes.
Original y universal
Dos representaciones firmadas del mismo documento, no dos documentos:
| Qué es | Cuándo la quieres | |
|---|---|---|
| original | El PDF con las firmas tal como se aplicaron | Para mostrarlo o descargarlo en el momento |
| universal | Esas mismas firmas envueltas en un sobre de validación a largo plazo | Para archivar, porque sigue siendo verificable cuando los certificados ya expiraron |
Ambas se descargan con GET /api/document/{type}/{ticket}, y
cada una tiene su propio webhook: original_signed y universal_signed.
NOM-151
La norma mexicana de constancia de conservación. Un sello NOM-151 certifica ante un tercero que un documento existía, con ese contenido exacto, en un momento dado.
Firmame lo aplica automáticamente a los documentos que firma, y también lo expone por separado para sellar archivos o hashes que ni siquiera pasaron por la plataforma. Ver NOM-151.