Embedded Signing

Los ejemplos usan $ALLSIGN_API_KEY. Defínela una vez con tu key de sandbox: export ALLSIGN_API_KEY="allsign_test_sk_…" (en PowerShell: $env:ALLSIGN_API_KEY="allsign_test_sk_…").

Descargar OpenAPI Colección de Postman

El objeto SigningSession

Atributos

livemode boolean requerido

true en entorno live, false en test/dev (marca de agua, sin validez legal).
id string requerido

ID de la sesión (ses_…).
object string, siempre "signing_session"

Siempre "signing_session".
status enum requerido

Estado de la sesión: pending, active, completed, expired o cancelled.

Valores: pending active completed expired cancelled
clientSecret string puede ser null

El secreto que tu frontend pasa al iframe. Devuelto una sola vez — en el GET viene null.
document objeto requerido

Documento que firma la sesión.
Ver 2 atributos hijos
- document.id string requerido
  
  ID del documento (doc_…).
- document.title string requerido
  
  Nombre del documento.
signer objeto requerido

Firmante ligado a la sesión.
Ver 2 atributos hijos
- signer.email string requerido
  
  Correo del participante que firma en el iframe.
- signer.name string requerido
  
  Nombre del firmante.
expiresAt string (fecha-hora ISO 8601) puede ser null

Cuándo expira la sesión (ISO 8601).
createdAt string (fecha-hora ISO 8601) puede ser null

Cuándo se creó (ISO 8601).
mountedAt string (fecha-hora ISO 8601) puede ser null

Cuándo se montó el iframe por primera vez.
completedAt string (fecha-hora ISO 8601) puede ser null

Cuándo se completó la firma.
signature objeto puede ser null

Estado autoritativo de la firma.
Ver 3 atributos hijos
- signature.id string requerido
  
  ID de la firma (sgr_…).
- signature.status enum requerido
  
  Estado autoritativo de la firma: pending, sent, signed, cancelled.
  
  Valores: pending sent signed cancelled waiting_turn
- signature.signedAt string (fecha-hora ISO 8601) puede ser null
  
  Momento de la firma (ISO 8601).
evidence objeto puede ser null

Paquete de evidencia sellada. Solo con ?expand=evidence.
Ver 3 atributos hijos
- evidence.available boolean requerido
  
  Si el paquete de evidencia ya está listo.
- evidence.evidencePdf objeto puede ser null
  
  Puntero al PDF de evidencia sellado.
  Ver 3 atributos hijos
  - evidence.evidencePdf.s3Key string puede ser null
    
    Ruta S3 del PDF de evidencia.
  - evidence.evidencePdf.presignedUrl string puede ser null
    
    URL prefirmada del PDF de evidencia (válida ~24 h).
  - evidence.evidencePdf.hash string puede ser null
    
    Hash del PDF de evidencia.
- evidence.nom151 objeto puede ser null
  
  Puntero a la constancia NOM-151.
  Ver 3 atributos hijos
  - evidence.nom151.s3Key string puede ser null
    
    Ruta S3 de la constancia NOM-151.
  - evidence.nom151.presignedUrl string puede ser null
    
    URL prefirmada de la constancia NOM-151.
  - evidence.nom151.data objeto (llave → valor) puede ser null
    
    Metadatos de la constancia NOM-151.

El objeto SigningSession

{
  "livemode": false,
  "id": "ses_76fc6e4f1aff48f3a8da1c2d9e21a149",
  "object": "signing_session",
  "status": "pending",
  "clientSecret": null,
  "document": {
    "id": "doc_51208ae8826c409999876c8f7e18e372",
    "title": "v3audit-ejemplos firma embebida"
  },
  "signer": {
    "email": "ana@ejemplo.com",
    "name": "ana@ejemplo.com"
  },
  "expiresAt": "2026-07-11T18:00:00.000000Z",
  "createdAt": "2026-07-11T17:44:59.981000Z",
  "mountedAt": null,
  "completedAt": null,
  "signature": {
    "id": "sgr_7f491e1b1be14ee2a192effe1bdb50dc",
    "status": "sent",
    "signedAt": null
  },
  "evidence": null
}

Grabado en el entorno interno de AllSign con una key de sandbox · backend 24c0469 · 8 oct 2026, 06:14 (hora CDMX) · test docs-checks-v3/tests/ejemplos/firma-embebida.ejemplos.spec.ts

Create signing session

POST /signing-sessions

Acuña un clientSecret que autoriza al iframe a firmar como un firmante (identificado por su correo) de un documento existente. El clientSecret se devuelve una sola vez, aquí. Requiere el scope embedded:write y honra la cabecera Idempotency-Key. livemode sale de la key, no del body: una key live exige allowedOrigins.

Parámetros

Idempotency-Key string header requerido

Clave única (UUID v4) que vuelve idempotente el POST: un reintento con la misma clave repite la respuesta original en lugar de volver a crear, cobrar o notificar.
AllSign-Version enum header

Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

Valores: 2026-07-11

Cuerpo de la petición

application/json

documentId string requerido

ID del documento a firmar (doc_…). Debe existir y tener al firmante como participante.
signerEmail string puede ser null

Correo del participante que firmará. Manda éste o signerPhone; uno de los dos es obligatorio.
signerPhone string puede ser null

WhatsApp del participante que firmará, en E.164 (+5255…). Alternativa a signerEmail para el firmante que no dio correo.
successUrl string puede ser null

A dónde redirigir cuando la firma se completa.
cancelUrl string puede ser null

A dónde redirigir si el firmante cancela.
brandProfileId string puede ser null

UUID de un perfil de marca de tu cuenta; el iframe usa sus colores. Si no existe o es de otra cuenta responde 404 RESOURCE_NOT_FOUND.
allowedOrigins array de string puede ser null

Orígenes donde puede montarse el iframe. Obligatorio para keys live.
otpMode enum

Verificación de identidad al crear: none (default), required o integrator_verified. Solo none está implementado.

Valores: none required integrator_verified

Devuelve

201 La sesión creada, con clientSecret en claro (única vez). — el objeto SigningSession

Errores posibles (problem+json): 400 401 403 404 409 422 429

cURL

curl -X POST 'https://api.allsign.io/v3/signing-sessions' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "documentId": "doc_e6d57f83692e4ff5ad07f57f6bd6a117",
  "signerEmail": "ana@ejemplo.com",
  "allowedOrigins": [
    "https://app.ejemplo.com"
  ],
  "successUrl": "https://app.ejemplo.com/firmado",
  "cancelUrl": "https://app.ejemplo.com/cancelado"
}'

Node

import { randomUUID } from 'node:crypto';

const respuesta = await fetch('https://api.allsign.io/v3/signing-sessions', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
        'Idempotency-Key': randomUUID(),
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        documentId: 'doc_e6d57f83692e4ff5ad07f57f6bd6a117',
        signerEmail: 'ana@ejemplo.com',
        allowedOrigins: [
            'https://app.ejemplo.com',
        ],
        successUrl: 'https://app.ejemplo.com/firmado',
        cancelUrl: 'https://app.ejemplo.com/cancelado',
    }),
});
console.log(respuesta.status, await respuesta.json());

Python

import os
import uuid

import requests

respuesta = requests.post(
    "https://api.allsign.io/v3/signing-sessions",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "documentId": "doc_e6d57f83692e4ff5ad07f57f6bd6a117",
        "signerEmail": "ana@ejemplo.com",
        "allowedOrigins": [
            "https://app.ejemplo.com",
        ],
        "successUrl": "https://app.ejemplo.com/firmado",
        "cancelUrl": "https://app.ejemplo.com/cancelado",
    },
)
print(respuesta.status_code, respuesta.json())

Respuesta

Respuesta · 201

{
  "livemode": false,
  "id": "ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a",
  "object": "signing_session",
  "status": "pending",
  "clientSecret": "<client-secret>",
  "document": {
    "id": "doc_e6d57f83692e4ff5ad07f57f6bd6a117",
    "title": "Contrato de servicios — Ana Torres"
  },
  "signer": {
    "email": "ana@ejemplo.com",
    "name": "ana@ejemplo.com"
  },
  "expiresAt": "2026-07-11T18:15:01.869000Z",
  "createdAt": null,
  "mountedAt": null,
  "completedAt": null,
  "signature": null,
  "evidence": null
}

Respuesta · 404 · RESOURCE_NOT_FOUND

{
  "type": "https://allsign.io/developers/docs/errors#RESOURCE_NOT_FOUND",
  "title": "Not Found",
  "status": 404,
  "detail": "No participant with email nadie@ejemplo.com on document c2af0193-88b8-4767-be86-e9bc40106542",
  "instance": "/v3/signing-sessions",
  "code": "RESOURCE_NOT_FOUND",
  "requestId": "req_243a82a23c1a45aba4757d8ed3758d31"
}

Grabado en el entorno interno de AllSign con una key de sandbox · backend 24c0469 · 8 oct 2026, 06:17 (hora CDMX) · test docs-checks-v3/tests/recetas/firma-embebida-en-tu-app.receta.spec.ts

Retrieve signing session

GET /signing-sessions/{session_id}

Lee el estado autoritativo del lado del servidor de una sesión — la verdad sobre si la firma se completó, no lo que reporte el iframe. Un ?expand=evidence adjunta el paquete de evidencia (PDF sellado + NOM-151 + URLs prefirmadas) cuando ya existe. Requiere embedded:write. El clientSecret no se devuelve aquí (viene null).

Parámetros

session_id string ruta requerido

ID de la sesión (ses_…).
expand string query

Pasa evidence para adjuntar el paquete de evidencia sellada. Otro valor es un 400 INVALID_EXPAND.
AllSign-Version enum header

Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

Valores: 2026-07-11

Devuelve

200 El objeto sesión, con evidencia si se pidió ?expand=evidence. — el objeto SigningSession

Errores posibles (problem+json): 400 401 403 404 422 429

cURL

curl 'https://api.allsign.io/v3/signing-sessions/ses_76fc6e4f1aff48f3a8da1c2d9e21a149' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11"

Node

const respuesta = await fetch('https://api.allsign.io/v3/signing-sessions/ses_76fc6e4f1aff48f3a8da1c2d9e21a149', {
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
    },
});
console.log(respuesta.status, await respuesta.json());

Python

import os

import requests

respuesta = requests.get(
    "https://api.allsign.io/v3/signing-sessions/ses_76fc6e4f1aff48f3a8da1c2d9e21a149",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())

Respuesta · 200

{
  "livemode": false,
  "id": "ses_76fc6e4f1aff48f3a8da1c2d9e21a149",
  "object": "signing_session",
  "status": "pending",
  "clientSecret": null,
  "document": {
    "id": "doc_51208ae8826c409999876c8f7e18e372",
    "title": "v3audit-ejemplos firma embebida"
  },
  "signer": {
    "email": "ana@ejemplo.com",
    "name": "ana@ejemplo.com"
  },
  "expiresAt": "2026-07-11T18:00:00.000000Z",
  "createdAt": "2026-07-11T17:44:59.981000Z",
  "mountedAt": null,
  "completedAt": null,
  "signature": {
    "id": "sgr_7f491e1b1be14ee2a192effe1bdb50dc",
    "status": "sent",
    "signedAt": null
  },
  "evidence": null
}

Grabado en el entorno interno de AllSign con una key de sandbox · backend 24c0469 · 8 oct 2026, 06:14 (hora CDMX) · test docs-checks-v3/tests/ejemplos/firma-embebida.ejemplos.spec.ts

Init signing session

POST /signing-sessions/{session_id}/init

Intercambia el clientSecret por un guest token nuevo de la sesión. Ruta pública — no lleva Authorization: la autenticación es el clientSecret en el body. Si la sesión se creó con allowedOrigins, parentOrigin es obligatorio y tiene que ser uno de ellos: sin él, o con otro origen, la respuesta es 403 PERMISSION_DENIED y no se entrega token. La única excepción es de desarrollo: un origen http://localhost:<puerto> se acepta con cualquier lista. Llamarla otra vez rota el guest token y entrega uno nuevo. No la necesitas para embeber la firma: ni el SDK ni el iframe de AllSign la llaman; AllSign hace el equivalente por ti al abrir la firma. Por eso una página tuya que no está en allowedOrigins no recibe este 403: lo normal es que el navegador ni siquiera cargue el iframe, porque AllSign lo sirve con Content-Security-Policy: frame-ancestors limitado a esa lista. Si aun así llega a cargar, la llamada con la que el iframe inicia la sesión responde 403 con el código ORIGIN_NOT_ALLOWED.

Parámetros

session_id string ruta requerido

ID de la sesión (ses_…).
AllSign-Version enum header

Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

Valores: 2026-07-11

Cuerpo de la petición

application/json

clientSecret string requerido

El secreto acuñado en el create (forma as_sess_{id}_secret_{rnd}). Es la credencial de esta ruta.
parentOrigin string puede ser null

El origen (https://…) de la página que embebe el iframe, para validar contra allowedOrigins. Obligatorio si la sesión se creó con allowedOrigins: si falta o no está en la lista, la respuesta es 403 PERMISSION_DENIED. http://localhost, con o sin puerto, se acepta siempre.

Devuelve

200 El guest token nuevo y el contexto de la sesión para montar el iframe.

Ver los 12 atributos de la respuesta

livemode boolean requerido

true en entorno live, false en test/dev (marca de agua, sin validez legal).
sessionId string requerido

ID de la sesión (ses_…).
signatureId string requerido

Firma que el guest token autoriza (sgr_…).
signerId string puede ser null

ID del firmante, si aplica.
guestToken string requerido

Credencial de un solo uso para el iframe (rotada en cada init).
signer objeto requerido

Firmante ligado a la sesión.
Ver 2 atributos hijos
- signer.email string requerido
  
  Correo del participante que firma en el iframe.
- signer.name string requerido
  
  Nombre del firmante.
document objeto requerido

Documento que firma la sesión.
Ver 2 atributos hijos
- document.id string requerido
  
  ID del documento (doc_…).
- document.title string requerido
  
  Nombre del documento.
brandProfileId string puede ser null

Perfil de marca, si se configuró.
appearance objeto puede ser null

Marca del workspace para el iframe. null = el aspecto por defecto de AllSign (marca no habilitada, sin plan de pago, sin perfil o valor guardado inválido).
Ver 5 atributos hijos
- appearance.primaryColor string requerido
  
  Color de marca, #rrggbb en minúsculas.
- appearance.primaryTextColor string requerido
  
  Color del texto sobre primaryColor (#ffffff o #000000), el de mayor contraste WCAG.
- appearance.borderRadius integer puede ser null
  
  Radio de las esquinas en px (0–24).
- appearance.fontFamily string puede ser null
  
  system, geist, manrope o inter. Clientes deben tolerar valores nuevos.
- appearance.poweredByAllSign boolean
  
  El pie «Powered by AllSign» siempre se muestra.
  
  default true
locale string requerido

Idioma del iframe (ej. es).
successUrl string puede ser null

Redirección de éxito.
cancelUrl string puede ser null

Redirección de cancelación.

Errores posibles (problem+json): 400 403 404 409 422 429

cURL

curl -X POST 'https://api.allsign.io/v3/signing-sessions/ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a/init' \
  -H "AllSign-Version: 2026-07-11" \
  -H "Content-Type: application/json" \
  -d '{
  "clientSecret": "<client-secret>",
  "parentOrigin": "https://app.ejemplo.com"
}'

Node

const respuesta = await fetch('https://api.allsign.io/v3/signing-sessions/ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a/init', {
    method: 'POST',
    headers: {
        'AllSign-Version': '2026-07-11',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        clientSecret: '<client-secret>',
        parentOrigin: 'https://app.ejemplo.com',
    }),
});
console.log(respuesta.status, await respuesta.json());

Python

import requests

respuesta = requests.post(
    "https://api.allsign.io/v3/signing-sessions/ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a/init",
    headers={
        "AllSign-Version": "2026-07-11",
    },
    json={
        "clientSecret": "<client-secret>",
        "parentOrigin": "https://app.ejemplo.com",
    },
)
print(respuesta.status_code, respuesta.json())

Respuesta

Respuesta · 200

{
  "livemode": false,
  "sessionId": "ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a",
  "signatureId": "sgr_fdcf573b43b24b2484b1a795ffff848f",
  "signerId": "usr_7e3a6c7366b54e50a5f49fbc1f0e8b9c",
  "guestToken": "<guestToken>",
  "signer": {
    "email": "ana@ejemplo.com",
    "name": "ana@ejemplo.com"
  },
  "document": {
    "id": "doc_e6d57f83692e4ff5ad07f57f6bd6a117",
    "title": "Contrato de servicios — Ana Torres"
  },
  "brandProfileId": null,
  "appearance": {
    "primaryColor": "#e54848",
    "primaryTextColor": "#000000",
    "borderRadius": 24,
    "fontFamily": null,
    "poweredByAllSign": true
  },
  "locale": "es",
  "successUrl": "https://app.ejemplo.com/firmado",
  "cancelUrl": "https://app.ejemplo.com/cancelado"
}

Respuesta · 403 · PERMISSION_DENIED

{
  "type": "https://allsign.io/developers/docs/errors#PERMISSION_DENIED",
  "title": "Permission denied",
  "status": 403,
  "detail": "The origin 'https://otro.ejemplo.com' is not authorized to embed this session.",
  "instance": "/v3/signing-sessions/ses_ee38d79b09ad45b9ad094034c1910ecc/init",
  "code": "PERMISSION_DENIED",
  "requestId": "req_beaface9931b45e4a4eb9e51c8b13f9c"
}

Grabado en el entorno interno de AllSign con una key de sandbox · backend 24c0469 · 8 oct 2026, 06:17 (hora CDMX) · test docs-checks-v3/tests/recetas/firma-embebida-en-tu-app.receta.spec.ts

Get session policy

GET /signing-sessions/{session_id}/policy

Consulta pública (por id, no por el secreto) de los orígenes autorizados a embeber la firma de la sesión: devuelve allowedOrigins y la directiva frameAncestors que les corresponde. Ruta pública — no lleva Authorization. No expone el clientSecret ni datos del documento. No la necesitas para embeber la firma: AllSign aplica esa misma lista en la cabecera Content-Security-Policy: frame-ancestors del iframe por su cuenta, sin pasar por esta ruta.

Parámetros

session_id string ruta requerido

ID de la sesión (ses_…).
AllSign-Version enum header

Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

Valores: 2026-07-11

Devuelve

200 La política CSP (allowedOrigins + frameAncestors) de la sesión.

Ver los 3 atributos de la respuesta

sessionId string requerido

ID de la sesión (ses_…).
allowedOrigins array de string requerido

Orígenes autorizados a montar el iframe (los allowedOrigins del create).
frameAncestors string requerido

El valor listo para el header Content-Security-Policy: frame-ancestors. Es * cuando no se configuraron orígenes.

Errores posibles (problem+json): 400 404 422 429

cURL

curl 'https://api.allsign.io/v3/signing-sessions/ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a/policy' \
  -H "AllSign-Version: 2026-07-11"

Node

const respuesta = await fetch('https://api.allsign.io/v3/signing-sessions/ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a/policy', {
    headers: {
        'AllSign-Version': '2026-07-11',
    },
});
console.log(respuesta.status, await respuesta.json());

Python

import requests

respuesta = requests.get(
    "https://api.allsign.io/v3/signing-sessions/ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a/policy",
    headers={
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())

Respuesta · 200

{
  "sessionId": "ses_b702eecc5b8d4dd0a6b58d5a5f2c8f5a",
  "allowedOrigins": [
    "https://app.ejemplo.com"
  ],
  "frameAncestors": "https://app.ejemplo.com http://localhost:*"
}

Grabado en el entorno interno de AllSign con una key de sandbox · backend 24c0469 · 8 oct 2026, 06:17 (hora CDMX) · test docs-checks-v3/tests/recetas/firma-embebida-en-tu-app.receta.spec.ts