Evidencia y NOM-151

Cuando todos los participantes firman, AllSign genera dos archivos: el PDF sellado (con las firmas y la bitácora de auditoría) y, si el documento se configuró con NOM-151, la constancia de conservación. Este endpoint te da ambos.

Ninguno de los dos viaja dentro del webhook. El webhook document.completed te avisa que el documento está listo y te da su id; la constancia se obtiene con esta segunda llamada. Es el paso que más se pasa por alto al integrar NOM-151.

GET/v2/documents/{document_id}/evidence

Obtener la evidencia

Devuelve URLs de descarga pre-firmadas (vigentes 24 horas) para el PDF de evidencia y la constancia NOM-151.

Requiere el scope document:read (o document:*).

Path parameters

Name
document_id
Type
string
Description
ID del documento (UUID).

Request

GET

/v2/documents/{id}/evidence

curl "https://api.allsign.io/v2/documents/DOC_UUID/evidence" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK"

Response (200)

{
  "documentId": "8f14e45f-ceea-4e2a-9b3d-1c7f0a2b5d61",
  "available": true,
  "reason": null,
  "signedCount": 2,
  "totalSigners": 2,
  "evidencePdf": {
    "s3Key": "documentos/8f14e45f.../pdf/evidence_Contrato.pdf",
    "presignedUrl": "https://s3.amazonaws.com/...",
    "hash": "9f2c1b7e..."
  },
  "nom151": {
    "s3Key": "documentos/8f14e45f.../pdf/nom151_Contrato.bin",
    "presignedUrl": "https://s3.amazonaws.com/...",
    "serialNumber": "0b2437",
    "algorithm": "Sha256",
    "issuer": "SeguriData Privada S.A. de C.V.",
    "data": {
      "number": "0b2437",
      "hashAlg": "Sha256",
      "hash": "9f2c1b7e...",
      "caName": "O=SeguriData Privada S.A. de C.V., OU=JLG-AM, CN=AC_TESTS, C=MX",
      "expeditionDate": "2026-07-31T18:47:00Z"
    }
  }
}

Campos de la respuesta

Name
available
Type
boolean
Description
true cuando el PDF de evidencia ya existe y su enlace de descarga se generó. Cuando es false, mira reason para saber qué hacer.
Name
reason
Type
string | null
Description
null si available es true. Si no, explica por qué falta la evidencia — ver Cuándo reintentar.
Name
signedCount
Type
integer
Description
Cuántos firmantes han firmado.
Name
totalSigners
Type
integer
Description
Total de firmantes del documento.
Name
evidencePdf
Type
object | null
Description
PDF sellado con todas las firmas y la bitácora de auditoría. presignedUrl para descargar, hash es el SHA-256 del archivo.
Name
nom151
Type
object | null
Description
Constancia de conservación NOM-151. presignedUrl descarga el archivo .bin; serialNumber/algorithm/issuer son los metadatos del sello, normalizados y estables. Es null si el documento no se configuró con NOM-151. Detalle completo en La constancia NOM-151.

Cuándo reintentar

Un available: false no siempre significa "espera". El campo reason te dice qué hacer, y reintentar solo sirve en uno de los tres casos:

Name
evidence_generating
Description
Todos firmaron y el PDF se está construyendo. Este es el único caso donde vale la pena reintentar — tarda segundos, no minutos.
Name
document_not_signed
Description
Todavía faltan firmantes (signedCount de totalSigners). Reintentar nunca va a ayudar: el documento tiene que firmarse primero. Espera el webhook document.completed en lugar de hacer polling.
Name
presigned_url_failed
Description
La evidencia existe pero no se pudo generar el enlace de descarga. Es un problema nuestro, no tuyo. Reintenta y, si persiste, escríbenos.

Response (200) — documento a medio firmar

{
  "documentId": "8f14e45f-ceea-4e2a-9b3d-1c7f0a2b5d61",
  "available": false,
  "reason": "document_not_signed",
  "signedCount": 1,
  "totalSigners": 2,
  "evidencePdf": null,
  "nom151": null
}

Flujo completo tras la firma

Este es el recorrido de punta a punta desde que el último firmante termina:

Recibes el webhook document.completed. Trae document.id y el PDF firmado (base64 + URL pre-firmada). No trae la constancia NOM-151.
Llamas a GET /v2/documents/{document.id}/evidence con tu API key.
Si available es false con reason: "evidence_generating", el sellado sigue corriendo — reintenta en unos segundos. Con cualquier otro reason, reintentar no ayuda.
Descargas nom151.presignedUrl (la constancia) y, si lo necesitas, evidencePdf.presignedUrl.

Las URLs pre-firmadas caducan a las 24 horas. Descarga y guarda los archivos en tu propio almacenamiento; no guardes la URL. Si expiró, vuelve a llamar al endpoint y obtienes una nueva.

Manejador de webhook completo

app.post('/webhooks/allsign', async (req, res) => {
  res.sendStatus(200) // responde primero, procesa después

  const { event, document } = req.body
  if (event !== 'document.completed') return

  // La constancia NOM-151 requiere esta segunda llamada.
  const evidence = await fetch(
    `https://api.allsign.io/v2/documents/${document.id}/evidence`,
    { headers: { Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}` } },
  ).then((r) => r.json())

  if (!evidence.available) {
    // Reintentar solo tiene sentido mientras se construye el PDF.
    if (evidence.reason === 'evidence_generating') return scheduleRetry(document.id)
    return console.warn('Evidencia no disponible:', evidence.reason)
  }

  if (evidence.nom151) {
    await archivar({
      folio: evidence.nom151.serialNumber,
      emitidaEl: evidence.nom151.data?.expeditionDate,
      archivo: await fetch(evidence.nom151.presignedUrl).then((r) => r.arrayBuffer()),
    })
  }
})

La constancia NOM-151

La constancia de conservación es el artefacto que da validez legal al documento bajo la NOM-151-SCFI-2016. La emite SeguriData, un Prestador de Servicios de Certificación (PSC) acreditado — AllSign es su cliente. Solo viaja el hash SHA-256 del documento: el archivo nunca sale de tu control.

Name
serialNumber
Type
string
Description
Folio del sello emitido por el PSC. Es tu identificador para auditorías.
Name
algorithm
Type
string
Description
Algoritmo de hash usado — tal cual lo reporta el PSC (p.ej. Sha256, no siempre en minúsculas con guion).
Name
issuer
Type
string
Description
Nombre de la organización emisora del sello (p.ej. SeguriData Privada S.A. de C.V.).

serialNumber, algorithm e issuer viven en nom151 directamente (no dentro de data) y son estables: no importa qué forma histórica tenga la fila internamente, siempre traen el valor correcto. nom151.data sigue disponible con el payload crudo del PSC (incluye también hash y expeditionDate), pero sus llaves exactas no están garantizadas — úsalo sólo si necesitas un campo que no esté en los tres de arriba.

nom151 es siempre null para documentos creados con una API key test o dev — la NOM-151 tiene costo y validez legal, así que se omite fuera de live, y el PDF de evidencia lleva una marca de agua "SIN VALIDEZ LEGAL". Prueba ahí la mecánica de tu integración, pero valida el flujo legal con una key live.

Errores

Name
404 — E1300_NOT_FOUND
Description
El documento no existe, o pertenece a otra cuenta. Por seguridad, ambos casos responden igual.
Name
403 — INSUFFICIENT_SCOPE
Description
Tu API key no tiene el scope document:read ni document:*.
Name
422
Description
El document_id no es un UUID válido.

Un documento que todavía no completa su firma no es un error: responde 200 con available: false, ambos archivos en null y el reason que explica el estado.