Firmar documentos desde otro sistema

Tu aplicación genera un documento, lo envía aquí para que se firme electrónicamente, y recibe un aviso cuando está listo junto con un enlace comprobable. El documento queda en el libro legal de la sociedad; tu sistema guarda la referencia.

1. Consigue una clave

Un administrador la crea en Integraciones. Se muestra una sola vez: de la clave solo queda su huella, así que si se pierde hay que crear otra. Junto a ella se entrega un secreto para comprobar los avisos.

X-API-Key: ntm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

También se admite Authorization: Bearer ntm_…. Las claves no caducan solas; se revocan, y el corte es inmediato.

2. Comprueba la conexión

GET /api/v1/ext/ping

{ "ok": true, "empresa": "novvox", "clave": "ERP de facturación" }

3. Envía el documento

POST /api/v1/ext/documents
Content-Type: application/json

{
  "bookType": "contratos",
  "title": "Contrato de arrendamiento 2026-14",
  "pdfBase64": "JVBERi0xLjcK…",
  "referenciaExterna": "ERP-CONTRATO-99821",
  "signers": [
    { "signerRef": "tesoreria@novvox.ai",
      "displayName": "Gustavo Adolfo Vargas Campos",
      "role": "Tesorero" }
  ]
}

bookType debe ser uno de los tipos que la empresa tenga definidos; si no existe, la respuesta dice cuáles hay. referenciaExterna es tu propio identificador: se guarda y viaja en cada aviso, para que no tengas que llevar una tabla de equivalencias.

Notarium añade al final del PDF una hoja de firmas con un recuadro por cada participante, y cada firma estampa el suyo con un código de verificación.

201 Created

{
  "id": "7c9e…",
  "referencia": "09f3688da03b47b58388382868fdf96f",
  "urlVerificacion": "https://notarium.tuempresa.com/verificar.html?r=09f36…",
  "estado": "pendiente_de_firmas",
  "referenciaExterna": "ERP-CONTRATO-99821"
}

Guarda referencia y urlVerificacion junto a tu documento: es el enlace que cualquiera puede abrir para comprobar la firma, sin cuenta y sin instalar nada.

4. Espera el aviso

Si configuraste una dirección de aviso, Notarium la llama cuando algo pasa. No hace falta preguntar en bucle.

POST https://tu-sistema.com/notarium/avisos
X-Notarium-Event: documento.sellado
X-Notarium-Delivery: 3f1c…
X-Notarium-Timestamp: 2026-10-02T01:40:12.004Z
X-Notarium-Signature: 9ab3…

{
  "id": "3f1c…",
  "evento": "documento.sellado",
  "momento": "2026-10-02T01:40:12.004Z",
  "datos": {
    "documentoId": "7c9e…",
    "referencia": "09f36…",
    "urlVerificacion": "https://…",
    "folio": "CTR-2026-0014",
    "referenciaExterna": "ERP-CONTRATO-99821"
  }
}

Eventos: documento.firmado (cada firma) y documento.sellado (han firmado todos y recibe folio).

Comprueba que el aviso es nuestro

Sin esta comprobación, cualquiera que averigüe tu dirección podría enviarte avisos falsos. La firma es SHA-256(momento + "." + cuerpo + "." + secreto) en hexadecimal, sobre el cuerpo tal como llegó, sin volver a serializarlo.

const esperada = createHash('sha256')
  .update(`${req.headers['x-notarium-timestamp']}.${cuerpoCrudo}.${SECRETO}`)
  .digest('hex');

if (esperada !== req.headers['x-notarium-signature']) return res.status(401).end();

Responde 2xx, y descarta repetidos

Si no respondes 2xx, se reintenta con espera creciente hasta ocho veces (más de un día). Eso significa que la entrega es al menos una vez, no exactamente una: si la red se corta después de que proceses el aviso pero antes de que llegue tu respuesta, lo recibirás de nuevo. Guarda el X-Notarium-Delivery e ignora los que ya hayas visto, o acabarás con documentos duplicados.

5. Consulta y descarga

GET /api/v1/ext/documents/{id}
GET /api/v1/ext/documents/{id}/pdf

La descarga indica en version si lo que devuelve es el firmado o todavía el original. Compruébalo: un sistema que archiva el original creyendo que es el firmado guarda un documento sin valor.

Errores

Códigos HTTP normales, con un cuerpo que explica qué pasó: { "title": "…", "detail": "…" }. 401 clave ausente, inexistente o revocada · 400 petición mal formada o tipo de documento inválido · 404 el documento no existe o no es de tu empresa · 503 el servicio no tiene base de datos.

Lo que esta API no hace

No firma por ti. La firma la hace una persona con su certificado, desde su propio equipo, y su clave privada no sale de él nunca. Lo que esta API hace es poner el documento en la cola de firma y avisarte cuando esté. Si pudiera firmar sola, la firma no valdría nada.