Receta

Lleva tu primer documento a firma

Objetivo: Un documento firmado de punta a punta en sandbox, con el aviso de cada firma y el de cierre llegando a tu servidor.

Para: integrador · nivel inicial · 10 min · Necesitas: API key de sandbox (allsign_test_sk_…) · Un PDF: contrato.pdf · Un endpoint HTTPS para webhooks

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

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_…").

1 Registra tu endpoint de webhooks

POST /webhooks ver en la referencia

Qué haces

Primero tu endpoint: así te enteras de cada firma y del cierre sin consultar en bucle. Guarda el secreto whsec_…, que solo se muestra aquí; con él verificas cada entrega.

Qué mirar

id = "whe_faed666bbdc5444693acfac1655160a6"
secret = "whsec_…"

cURL

curl -X POST 'https://api.allsign.io/v3/webhooks' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://ejemplo.com/webhooks/allsign",
  "events": [
    "signer.signed",
    "document.completed"
  ],
  "description": "Mi primer contrato"
}'

Node

import { randomUUID } from 'node:crypto';

const respuesta = await fetch('https://api.allsign.io/v3/webhooks', {
    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({
        url: 'https://ejemplo.com/webhooks/allsign',
        events: [
            'signer.signed',
            'document.completed',
        ],
        description: 'Mi primer contrato',
    }),
});
console.log(respuesta.status, await respuesta.json());

Python

import os
import uuid

import requests

respuesta = requests.post(
    "https://api.allsign.io/v3/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "url": "https://ejemplo.com/webhooks/allsign",
        "events": [
            "signer.signed",
            "document.completed",
        ],
        "description": "Mi primer contrato",
    },
)
print(respuesta.status_code, respuesta.json())

Respuesta · 201

{
  "livemode": false,
  "id": "whe_faed666bbdc5444693acfac1655160a6",
  "object": "webhook_endpoint",
  "url": "https://ejemplo.com/webhooks/allsign",
  "events": [
    "signer.signed",
    "document.completed"
  ],
  "description": "Mi primer contrato",
  "status": "enabled",
  "apiVersion": "2026-07-11",
  "environment": "test",
  "secretLast4": "S5w=",
  "createdAt": "2026-07-11T18:00:00.000000Z",
  "secret": "whsec_…"
}

2 Crea el documento con su firmante

POST /documents ver en la referencia

Qué haces

Crear no envía nada: el documento nace en draft y todavía lo puedes cambiar. signer-pending@sandbox.allsign.io es un firmante de prueba que no recibe correo y nunca firma solo: espera a que tú firmes por él.

Qué mirar en sandbox

id = "doc_fdde14eeff0b4444acec4d6b10736068"
status = "draft"
signerCount = 1

cURL

curl -X POST 'https://api.allsign.io/v3/documents' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "file": {
    "content": "'"$(base64 < contrato.pdf | tr -d '\n')"'",
    "fileType": "pdf",
    "name": "contrato.pdf"
  },
  "name": "Mi primer contrato (sandbox)",
  "signers": [
    {
      "email": "signer-pending@sandbox.allsign.io",
      "name": "Ana Torres"
    }
  ]
}'

Node

import { randomUUID } from 'node:crypto';
import { readFileSync } from 'node:fs';

const respuesta = await fetch('https://api.allsign.io/v3/documents', {
    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({
        file: {
            content: readFileSync('contrato.pdf').toString('base64'),
            fileType: 'pdf',
            name: 'contrato.pdf',
        },
        name: 'Mi primer contrato (sandbox)',
        signers: [
            {
                email: 'signer-pending@sandbox.allsign.io',
                name: 'Ana Torres',
            },
        ],
    }),
});
console.log(respuesta.status, await respuesta.json());

Python

import base64
import os
import uuid
from pathlib import Path

import requests

respuesta = requests.post(
    "https://api.allsign.io/v3/documents",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "file": {
            "content": base64.b64encode(Path("contrato.pdf").read_bytes()).decode(),
            "fileType": "pdf",
            "name": "contrato.pdf",
        },
        "name": "Mi primer contrato (sandbox)",
        "signers": [
            {
                "email": "signer-pending@sandbox.allsign.io",
                "name": "Ana Torres",
            },
        ],
    },
)
print(respuesta.status_code, respuesta.json())

Respuesta · 201

{
  "livemode": false,
  "id": "doc_fdde14eeff0b4444acec4d6b10736068",
  "object": "document",
  "name": "Mi primer contrato (sandbox)",
  "status": "draft",
  "documentType": "EDITABLE",
  "signerCount": 1,
  "signedCount": 0,
  "ownerId": "usr_08f394a003014001b429ca03db05b7f7",
  "orgId": "f4d8bad5-5bb0-451c-a917-2ae6b489d38f",
  "folderId": null,
  "expiresAt": null,
  "signingOrder": "parallel",
  "currentStage": null,
  "expirationReminders": null,
  "templateId": null,
  "templateVersionId": null,
  "parentDocumentId": null,
  "createdAt": "2026-07-11T18:01:02.144000Z",
  "updatedAt": "2026-07-11T18:01:02.144000Z"
}

3 Envíalo a firma

POST /documents/{document_id}/send ver en la referencia

Qué haces

Ahora el documento espera firmas. Desde aquí ya no se edita: si algo estaba mal, lo anulas y creas otro.

Qué mirar

status = "awaiting_signatures"

En producción

Aquí AllSign le manda la invitación a tu firmante por correo o WhatsApp, y con una key live el envío consume créditos de tu saldo; en sandbox no se cobra nada.

cURL

curl -X POST 'https://api.allsign.io/v3/documents/doc_fdde14eeff0b4444acec4d6b10736068/send' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Node

import { randomUUID } from 'node:crypto';

const respuesta = await fetch('https://api.allsign.io/v3/documents/doc_fdde14eeff0b4444acec4d6b10736068/send', {
    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({}),
});
console.log(respuesta.status, await respuesta.json());

Python

import os
import uuid

import requests

respuesta = requests.post(
    "https://api.allsign.io/v3/documents/doc_fdde14eeff0b4444acec4d6b10736068/send",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={},
)
print(respuesta.status_code, respuesta.json())

Respuesta · 200

{
  "livemode": false,
  "id": "doc_fdde14eeff0b4444acec4d6b10736068",
  "object": "document",
  "name": "Mi primer contrato (sandbox)",
  "status": "awaiting_signatures",
  "documentType": "EDITABLE",
  "signerCount": 1,
  "signedCount": 0,
  "ownerId": "usr_08f394a003014001b429ca03db05b7f7",
  "orgId": "f4d8bad5-5bb0-451c-a917-2ae6b489d38f",
  "folderId": null,
  "expiresAt": null,
  "signingOrder": "parallel",
  "currentStage": null,
  "expirationReminders": null,
  "templateId": null,
  "templateVersionId": null,
  "parentDocumentId": null,
  "createdAt": "2026-07-11T18:01:02.144000Z",
  "updatedAt": "2026-07-11T18:01:05.421000Z"
}

4 Consulta a tu firmante

GET /documents/{document_id}/signers ver en la referencia

Qué haces

Cada firmante tiene su id sgr_… y su propio status. Con ese id le recuerdas, lo reasignas o, en sandbox, firmas por él.

Qué mirar

data.0.id = "sgr_d64e1ca6bcf64eebac2d35da21d23c88"
data.0.status = "sent"

cURL

curl 'https://api.allsign.io/v3/documents/doc_fdde14eeff0b4444acec4d6b10736068/signers' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11"

Node

const respuesta = await fetch('https://api.allsign.io/v3/documents/doc_fdde14eeff0b4444acec4d6b10736068/signers', {
    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/documents/doc_fdde14eeff0b4444acec4d6b10736068/signers",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())

Respuesta · 200

{
  "object": "list",
  "data": [
    {
      "livemode": false,
      "id": "sgr_d64e1ca6bcf64eebac2d35da21d23c88",
      "object": "signer",
      "documentId": "doc_fdde14eeff0b4444acec4d6b10736068",
      "email": "signer-pending@sandbox.allsign.io",
      "phone": null,
      "name": "Ana Torres",
      "status": "sent",
      "signedAt": null,
      "routingOrder": null,
      "delivery": null
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "previousCursor": null,
  "limit": null
}

5 Firma por tu firmante (solo en sandbox)

POST /sandbox/signers/{signer_id}/sign ver en la referencia

Qué haces

En sandbox no hay nadie del otro lado: esta operación firma como si tu firmante hubiera abierto su liga, y dispara los mismos eventos que una firma real.

Qué mirar

status = "signed"
signedAt = "2026-07-11T18:01:06.969000Z"

En producción

Aquí firma tu cliente: abre la liga del correo o del WhatsApp, revisa el documento y firma. Esta operación solo funciona en sandbox.

cURL

curl -X POST 'https://api.allsign.io/v3/sandbox/signers/sgr_d64e1ca6bcf64eebac2d35da21d23c88/sign' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11" \
  -H "Idempotency-Key: $(uuidgen)"

Node

import { randomUUID } from 'node:crypto';

const respuesta = await fetch('https://api.allsign.io/v3/sandbox/signers/sgr_d64e1ca6bcf64eebac2d35da21d23c88/sign', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
        'Idempotency-Key': randomUUID(),
    },
});
console.log(respuesta.status, await respuesta.json());

Python

import os
import uuid

import requests

respuesta = requests.post(
    "https://api.allsign.io/v3/sandbox/signers/sgr_d64e1ca6bcf64eebac2d35da21d23c88/sign",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
print(respuesta.status_code, respuesta.json())

Respuesta · 200

{
  "livemode": false,
  "id": "sgr_d64e1ca6bcf64eebac2d35da21d23c88",
  "object": "signer",
  "documentId": "doc_fdde14eeff0b4444acec4d6b10736068",
  "email": "signer-pending@sandbox.allsign.io",
  "phone": null,
  "name": "Ana Torres",
  "status": "signed",
  "signedAt": "2026-07-11T18:01:06.969000Z",
  "routingOrder": null,
  "delivery": null
}

6 Espera el webhook signer.signed

POST tu endpoint · evento signer.signed

Qué haces

Llega en cuanto firma cada persona. Verifica la firma de la entrega antes de confiar en su contenido.

AllSign le hace POST a la URL que registraste, con el evento signer.signed. Responde 2xx rápido y, antes de confiar en el cuerpo, verifica la firma: webhook-signature es un HMAC-SHA256 de webhook-id.webhook-timestamp.cuerpo con el secreto del webhook (Webhooks).

Esta entrega llegó de verdad al receptor del test y su firma se verificó con el secreto del webhook.

Qué mirar

eventType = "signer.signed"
data.documentId = "doc_fdde14eeff0b4444acec4d6b10736068"

Entrega recibida

Entrega recibida · Cuerpo

{
  "data": {
    "name": "Mi primer contrato (sandbox)",
    "signer": {
      "name": "Ana Torres",
      "email": "signer-pending@sandbox.allsign.io",
      "phone": null,
      "signedAt": "2026-07-11T18:01:06.969000Z",
      "signerId": "sgr_d64e1ca6bcf64eebac2d35da21d23c88",
      "authMethod": "POR_DEFINIR"
    },
    "documentId": "doc_fdde14eeff0b4444acec4d6b10736068",
    "signedCount": 1,
    "totalSigners": 1
  },
  "eventId": "evt_b65f702e300448f9906987d0e9aa0ec0",
  "livemode": false,
  "tenantId": "d521e797-924d-41c6-be8b-a3dcd62f5b6f",
  "eventType": "signer.signed",
  "apiVersion": "2026-07-11",
  "occurredAt": "2026-07-11T18:01:07.025Z"
}

Entrega recibida · Cabeceras

{
  "content-type": "application/json",
  "allsign-event": "signer.signed",
  "allsign-livemode": "false",
  "webhook-id": "b65f702e-3004-48f9-9069-87d0e9aa0ec0",
  "webhook-timestamp": "1783792867",
  "webhook-signature": "v1,<firma>",
  "allsign-delivery-id": "7553835d-3b51-4c47-a79b-a036813e0d92"
}

Verifica la firma

Verifica la firma · Node

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verificarWebhook(cuerpoCrudo, headers, secreto) {
    const id = headers['webhook-id'];
    const timestamp = headers['webhook-timestamp'];
    if (!id || !/^\d+$/.test(timestamp ?? '') || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
    const llave = Buffer.from(secreto.replace(/^whsec_/, ''), 'base64');
    const esperada = Buffer.from(createHmac('sha256', llave).update(`${id}.${timestamp}.${cuerpoCrudo}`).digest('base64'));
    return (headers['webhook-signature'] ?? '').split(' ').some((token) => {
        const [version, firma = ''] = token.split(',');
        const candidata = Buffer.from(firma);
        return version === 'v1' && candidata.length === esperada.length && timingSafeEqual(candidata, esperada);
    });
}

Verifica la firma · Python

import base64
import hashlib
import hmac
import time


def verificar_webhook(cuerpo_crudo: bytes, headers: dict, secreto: str) -> bool:
    id_ = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp", "")
    if not id_ or not (timestamp.isascii() and timestamp.isdigit()) or abs(time.time() - int(timestamp)) > 300:
        return False
    llave = base64.b64decode(secreto.removeprefix("whsec_"))
    contenido = f"{id_}.{timestamp}.".encode() + cuerpo_crudo
    esperada = base64.b64encode(hmac.new(llave, contenido, hashlib.sha256).digest())
    return any(
        version == "v1" and hmac.compare_digest(firma.encode(), esperada)
        for version, _, firma in (token.partition(",") for token in headers.get("webhook-signature", "").split())
    )

7 Espera el webhook document.completed

POST tu endpoint · evento document.completed

Qué haces

Llega cuando firmó la última persona y la evidencia ya está lista para descargar. Es la señal para guardar el PDF firmado.

AllSign le hace POST a la URL que registraste, con el evento document.completed. Responde 2xx rápido y, antes de confiar en el cuerpo, verifica la firma: webhook-signature es un HMAC-SHA256 de webhook-id.webhook-timestamp.cuerpo con el secreto del webhook (Webhooks).

Esta entrega llegó de verdad al receptor del test y su firma se verificó con el secreto del webhook.

Qué mirar

eventType = "document.completed"
data.status = "completed"

Entrega recibida

Entrega recibida · Cuerpo

{
  "data": {
    "name": "Mi primer contrato (sandbox)",
    "nom151": null,
    "status": "completed",
    "signers": [
      {
        "name": "Ana Torres",
        "email": "signer-pending@sandbox.allsign.io",
        "signedAt": "2026-07-11T18:01:06.969000Z",
        "signerId": "sgr_d64e1ca6bcf64eebac2d35da21d23c88",
        "authMethod": "POR_DEFINIR"
      }
    ],
    "documentId": "doc_fdde14eeff0b4444acec4d6b10736068",
    "completedAt": "2026-07-11T18:01:08.816000Z",
    "evidencePdf": {
      "url": "https://api.allsign.io/v3/documents/doc_fdde14eeff0b4444acec4d6b10736068/evidence",
      "sha256": "ed345419cea24ebbee27d9226b383468c70176e89b2391c5dec89bd4b7df4682",
      "mimeType": "application/pdf",
      "sizeBytes": 81606
    }
  },
  "eventId": "evt_118e25115c1c4b0b859b732e5ca40301",
  "livemode": false,
  "tenantId": "d521e797-924d-41c6-be8b-a3dcd62f5b6f",
  "eventType": "document.completed",
  "apiVersion": "2026-07-11",
  "occurredAt": "2026-07-11T18:01:08.818Z"
}

Entrega recibida · Cabeceras

{
  "content-type": "application/json",
  "allsign-event": "document.completed",
  "allsign-livemode": "false",
  "webhook-id": "118e2511-5c1c-4b0b-859b-732e5ca40301",
  "webhook-timestamp": "1783792869",
  "webhook-signature": "v1,<firma>",
  "allsign-delivery-id": "8510c66d-8d0a-417a-b767-f1d78612b3ec"
}

Verifica la firma

Verifica la firma · Node

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verificarWebhook(cuerpoCrudo, headers, secreto) {
    const id = headers['webhook-id'];
    const timestamp = headers['webhook-timestamp'];
    if (!id || !/^\d+$/.test(timestamp ?? '') || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
    const llave = Buffer.from(secreto.replace(/^whsec_/, ''), 'base64');
    const esperada = Buffer.from(createHmac('sha256', llave).update(`${id}.${timestamp}.${cuerpoCrudo}`).digest('base64'));
    return (headers['webhook-signature'] ?? '').split(' ').some((token) => {
        const [version, firma = ''] = token.split(',');
        const candidata = Buffer.from(firma);
        return version === 'v1' && candidata.length === esperada.length && timingSafeEqual(candidata, esperada);
    });
}

Verifica la firma · Python

import base64
import hashlib
import hmac
import time


def verificar_webhook(cuerpo_crudo: bytes, headers: dict, secreto: str) -> bool:
    id_ = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp", "")
    if not id_ or not (timestamp.isascii() and timestamp.isdigit()) or abs(time.time() - int(timestamp)) > 300:
        return False
    llave = base64.b64decode(secreto.removeprefix("whsec_"))
    contenido = f"{id_}.{timestamp}.".encode() + cuerpo_crudo
    esperada = base64.b64encode(hmac.new(llave, contenido, hashlib.sha256).digest())
    return any(
        version == "v1" and hmac.compare_digest(firma.encode(), esperada)
        for version, _, firma in (token.partition(",") for token in headers.get("webhook-signature", "").split())
    )

8 Confirma el estado final

GET /documents/{document_id} ver en la referencia

Qué haces

Una sola consulta, después del webhook y nunca en un bucle: el documento está completed y todas las firmas cuentan.

Qué mirar

status = "completed"
signedCount = 1

cURL

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

Node

const respuesta = await fetch('https://api.allsign.io/v3/documents/doc_fdde14eeff0b4444acec4d6b10736068', {
    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/documents/doc_fdde14eeff0b4444acec4d6b10736068",
    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": "doc_fdde14eeff0b4444acec4d6b10736068",
  "object": "document",
  "name": "Mi primer contrato (sandbox)",
  "status": "completed",
  "documentType": "EDITABLE",
  "signerCount": 1,
  "signedCount": 1,
  "ownerId": "usr_08f394a003014001b429ca03db05b7f7",
  "orgId": "f4d8bad5-5bb0-451c-a917-2ae6b489d38f",
  "folderId": null,
  "expiresAt": null,
  "signingOrder": "parallel",
  "currentStage": null,
  "expirationReminders": null,
  "templateId": null,
  "templateVersionId": null,
  "parentDocumentId": null,
  "createdAt": "2026-07-11T18:01:02.144000Z",
  "updatedAt": "2026-07-11T18:01:05.421000Z"
}

Errores comunes de esta receta

Errores reales que el test de esta receta provocó a propósito en sandbox, sobre sus mismos pasos. Cada uno enlaza a su explicación en Errores.

IDEMPOTENCY_KEY_REQUIRED · 400 · en el paso 2 (Crea el documento con su firmante)

Crear sin Idempotency-Key. Qué significa y qué hacer

Respuesta · 400 · IDEMPOTENCY_KEY_REQUIRED

{
  "type": "https://allsign.io/developers/docs/errors#IDEMPOTENCY_KEY_REQUIRED",
  "title": "Bad Request",
  "status": 400,
  "detail": "POST requests that create or charge require a unique Idempotency-Key (UUID v4).",
  "instance": "/v3/documents",
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "requestId": "req_48ab6b50c363414c8d0e41850d05d5f5"
}

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

IDEMPOTENCY_KEY_INVALID · 400 · en el paso 2 (Crea el documento con su firmante)

Crear con una Idempotency-Key que no es UUID v4. Qué significa y qué hacer

Respuesta · 400 · IDEMPOTENCY_KEY_INVALID

{
  "type": "https://allsign.io/developers/docs/errors#IDEMPOTENCY_KEY_INVALID",
  "title": "Bad Request",
  "status": 400,
  "detail": "Idempotency-Key must be a UUID v4.",
  "instance": "/v3/documents",
  "code": "IDEMPOTENCY_KEY_INVALID",
  "requestId": "req_e289ae908d284f7bbbdfc6abc2178d32"
}

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

DOCUMENT_NOT_FOUND · 404 · en el paso 8 (Confirma el estado final)

Consultar un documento que no existe o es de otra cuenta. Qué significa y qué hacer

Respuesta · 404 · DOCUMENT_NOT_FOUND

{
  "type": "https://allsign.io/developers/docs/errors#DOCUMENT_NOT_FOUND",
  "title": "Document not found",
  "status": 404,
  "detail": "No document was found with that id.",
  "instance": "/v3/documents/doc_dd56d81575b84eb790373c6dff92cb95",
  "code": "DOCUMENT_NOT_FOUND",
  "requestId": "req_c72bfc8e0f1f4fc69bcc8111e77dc52d"
}

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

INVALID_STATE_TRANSITION · 409 · en el paso 5 (Firma por tu firmante (solo en sandbox))

Firmar en sandbox un documento que todavía no envías. Qué significa y qué hacer

Respuesta · 409 · INVALID_STATE_TRANSITION

{
  "type": "https://allsign.io/developers/docs/errors#INVALID_STATE_TRANSITION",
  "title": "Conflict",
  "status": 409,
  "detail": "The document has not been sent yet. Send it first with POST /v3/documents/{documentId}/send.",
  "instance": "/v3/sandbox/signers/sgr_592c7816786d4e70bb676a8be0648b5b/sign",
  "code": "INVALID_STATE_TRANSITION",
  "requestId": "req_c1f762446ffa48c2a620e3c8297daa1f",
  "reason": "never_invited"
}

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

Descarga el PDF firmado y su evidencia — El PDF firmado y el PDF de evidencia de un documento completado, con su huella sha256 para archivarlos.
Recibe y verifica los webhooks de AllSign — Un endpoint que recibe los eventos de AllSign, comprueba que de verdad los firmó AllSign y sobrevive a sus propias caídas y a la rotación del secreto.
Varios firmantes, uno después de otro — Un contrato que firma primero la vendedora y después el comprador, con el comprador sin poder firmar antes de su turno.

Lleva tu primer documento a firma

1 Registra tu endpoint de webhooks

Qué haces

Qué mirar

2 Crea el documento con su firmante

Qué haces

Qué mirar en sandbox

3 Envíalo a firma

Qué haces

Qué mirar

En producción

4 Consulta a tu firmante

Qué haces

Qué mirar

5 Firma por tu firmante (solo en sandbox)

Qué haces

Qué mirar

En producción

6 Espera el webhook signer.signed

Qué haces

Qué mirar

7 Espera el webhook document.completed

Qué haces

Qué mirar

8 Confirma el estado final

Qué haces

Qué mirar

Errores comunes de esta receta

Siguiente