Crear un documento.

El primer paso para iniciar un proceso de firmado legalmente vinculante es la configuración inicial. Aquí definirás quién firma, cómo firma y qué notificaciones recibirá.

1. Configuración del Proceso: Define métodos de firma, proveedores y orden de ejecución.
2. Definición de Participantes: Indica quiénes son los firmantes y espectadores.
3. Personalización: Configura notificaciones, recordatorios y webhooks.

---

Endpoint de Creación

Para crear un nuevo documento, realiza una petición al siguiente endpoint:

Método: POST https://api.digitafirma.com/v1/documents

Identity Providers

Define qué tecnología validará la identidad:

• VERIFICAMEX: Firma con identidad (INE vigente).
• LOCAL: Firma simple (ideal para extranjeros).

Sign Modes

Determina cómo se visualizarán las firmas:

• PDF_SIGNATURE: Firma incrustada en el PDF.
• CLASSIC: Firma tradicional.
• CLASSIC_BATCH: Firmado masivo.

---

Parámetros de la Petición

General

Campo	Tipo	Descripción
company_id	string	ID de la carpeta de trabajo (consulta Listar carpetas de trabajo).
sign_mode	enum	Modo de firmado (CLASSIC, PDF_SIGNATURE, CLASSIC_BATCH).
sign_position	enum	Posición de la firma en el documento: UPPER_RIGHT, UPPER_LEFT, LOWER_RIGHT, LOWER_LEFT, NONE o CUSTOM (coordenadas manuales, ver Firma con posiciones personalizadas).
webhook	string	URL que recibirá notificaciones de estado.
sign_ordered	enum	ACTIVE para forzar el orden del array de firmantes.
redirect_url	string	URL a la que se redirige al firmante al concluir el proceso. Opcional y 100% retrocompatible. Ver URL de redirección por documento.

Configuración de Firma

Campo	Tipo	Descripción
config.identity_providers	Array	Proveedores admitidos (LOCAL, VERIFICAMEX).
config.allow_type_signatures	Array	Métodos permitidos (VERIFICAMEX, FIREL, EFIRMA).

Participantes

Campo	Tipo	Descripción
signatures	Array	Lista de personas que deben firmar. Requiere name, email, phone, rfc. Opcionalmente positions para colocar la firma en coordenadas manuales (ver Firma con posiciones personalizadas).
spectators	Array	Personas con acceso de solo lectura. Requiere name, email.

Notificaciones

Campo	Tipo	Descripción
notification_mode	enum	ENABLED o DISABLED.
tries	int	Cantidad de intentos de notificación (mínimo 1).
remember_every	int	Frecuencia de recordatorios en días.
remember_at	string	Hora del recordatorio (HH:mm).

---

identity_providers vs. allow_type_signatures

Estos dos campos de config resuelven preguntas distintas y son independientes entre sí. La confusión más común es asumir que uno reemplaza al otro, o que con configurar uno de los dos es suficiente.

Campo	Responde a…	¿Cuándo importa?
allow_type_signatures	¿Qué certificado se acepta como válido para firmar criptográficamente?	Siempre. Es lo único que el backend valida al momento de firmar.
identity_providers	¿Cómo se valida que el firmante es quien dice ser?	Solo dentro del flujo guiado (ver regla clave abajo).

allow_type_signatures: qué certificados se aceptan

Valor	Significa
FIREL	El firmante sube su propio certificado (.pfx o key+cer) emitido por el Consejo de la Judicatura Federal.
EFIRMA	El firmante sube su propio certificado e.firma (SAT).
TEPJF	El firmante sube su propio certificado del Tribunal Electoral.
VERIFICAMEX	Habilita el flujo guiado de Digitafirma: el firmante no necesita tener un certificado propio; el sistema le emite uno automáticamente después de validar su identidad.

Regla clave

Para que un firmante pueda usar el flujo guiado (tanto “firma con identidad” como “firma simple”, sin traer su propio certificado), allow_type_signatures siempre debe incluir "VERIFICAMEX", sin importar qué identity_providers elijas. El certificado que el sistema emite en ese flujo siempre es de tipo VERIFICAMEX. Si configuras, por ejemplo, identity_providers: ["LOCAL"] pero omites "VERIFICAMEX" de allow_type_signatures, el firmante recibirá el error “El documento no permite firma electrónica simple” al intentar firmar.

identity_providers: cómo se valida la identidad dentro del flujo guiado

Solo tiene efecto si allow_type_signatures incluye "VERIFICAMEX". Determina qué método(s) de validación puede elegir el firmante antes de que el sistema le emita su certificado:

Valor	Método de validación	Ideal para
VERIFICAMEX	Valida INE vigente y CURP contra fuentes oficiales (RENAPO). Mayor nivel de certeza sobre la identidad.	Firmantes mexicanos con INE vigente.
LOCAL	Validación simplificada: video de identificación + código OTP al teléfono. No requiere INE.	Extranjeros o casos donde no aplica validar con INE.

Puedes habilitar ambos valores (["VERIFICAMEX", "LOCAL"]) para que el firmante elija, o solo uno para forzar un método específico.

Recetas comunes

Objetivo	identity_providers	allow_type_signatures
Firma con identidad (máxima certeza, requiere INE)	["VERIFICAMEX"]	["VERIFICAMEX"]
Firma simple (sin INE, ideal para extranjeros)	["LOCAL"]	["VERIFICAMEX"]
Dejar que el firmante elija cómo validar su identidad	["VERIFICAMEX", "LOCAL"]	["VERIFICAMEX"]
Solo aceptar certificados propios (e.firma / FIEL), sin flujo guiado	(se puede omitir)	["EFIRMA", "FIREL"]
Aceptar certificados propios y también flujo guiado	["VERIFICAMEX", "LOCAL"]	["EFIRMA", "VERIFICAMEX"]

---

URL de redirección por documento

Por defecto, cuando un firmante termina de firmar, permanece dentro de la pantalla de DigitaFirma. Con redirect_url puedes decidir a dónde enviar al firmante al concluir el proceso: tu propia plataforma, tu pantalla de éxito, el siguiente paso de tu onboarding o el siguiente trámite — sin que el firmante “se quede” en DigitaFirma sin saber qué hacer a continuación.

El campo es 100% opt-in: si no lo envías, todo sigue funcionando como antes.

Opcional y retrocompatible

Si redirect_url se omite o se envía vacío, no aparece en el documento ni en la respuesta de la API. Las integraciones existentes no se ven impactadas y no están obligadas a migrar.

Aplica a todos los flujos de firma

Firma con identidad (VerificameX), firma simple por OTP (Local) y firma directa con certificado propio .cer / .key. La URL se entrega en cada respuesta del proceso, lista para que el frontend redirija al firmante al concluir.

Validación estricta de esquema

Solo se aceptan URLs con esquema http o https válidos (por ejemplo, https://tudominio.com/fin-firma). Cualquier otro esquema (mailto:, tel:, javascript:) o rutas relativas serán rechazados al crear el documento.

Control del customer journey

Tú decides el siguiente paso dentro de tu propia plataforma: página de éxito, continuación del onboarding, acuse, cierre del flujo, siguiente trámite, etc. DigitaFirma solo redirige al finalizar.

Cómo funciona

1. Creas el documento incluyendo redirect_url en la petición al endpoint de creación.
2. DigitaFirma notifica al firmante y gestiona todo el proceso de firma (validación de identidad, emisión de certificado y firma criptográfica).
3. Al finalizar, el firmante es redirigido automáticamente a la URL indicada — sin intervención extra de tu backend ni cambios en la integración actual.

Casos de uso

Contexto	Qué logras con redirect_url
Bancos / fintech	Firmar el contrato y continuar el alta directamente dentro de tu propia app.
RRHH	Firmar políticas y regresar al portal del empleado para el siguiente paso.
Seguros	Firmar la póliza y avanzar a la siguiente pantalla del trámite.
Gobierno / notarías	Firmar y mostrar el acuse o el siguiente requisito directamente en tu sitio.
SaaS integrados	Orquestar la firma dentro de tu flujo de usuario, regresando al firmante al punto correcto de tu producto.

Regla de validación

redirect_url debe ser una URL completa y válida con esquema http o https. Esquemas como mailto:, tel:, javascript: o rutas relativas serán rechazados por el backend al momento de crear el documento. Si no la necesitas, omítela — enviar una URL vacía tiene el mismo efecto que no enviarla.

---

Ejemplo de Integración

JSON de Petición

{
"company_id": "ac110005-9d0c-1243-819d-0c3b71220000",
"config": {
    "identity_providers": [
        "VERIFICAMEX",
        "LOCAL"
    ],
    "allow_type_signatures": [
        "VERIFICAMEX",
        "EFIRMA",
        "FIREL"
    ]
},
"signatures": [
    {
        "name": "Juan Perez",
        "email": "jpe@gmail.com",
        "phone": "+522291449388",
        "rfc": "XXXX941024V93"
    }
],
"spectators": [
    {
        "name": "Hector Lavoe",
        "email": "hl@hotmail.com"
    }
],
"webhook": "{URL-WEBHOOK}",
"redirect_url": "https://tudominio.com/fin-firma",
"sign_ordered": "ACTIVE",
"notification_mode": "ENABLED",
"tries": 3,
"remember_every": 1,
"remember_at": "16:54"
}

Respuesta Exitosa (200 OK)

{
"type": "documents",
"id": "ac110005-9df4-1d1b-819d-f5eac471003a",
"links": {
    "self": "/documents/ac110005-9df4-1d1b-819d-f5eac471003a"
},
"attributes": {
    "original_hash": null,
    "file_name": "",
    "sign_status": 1,
    "signed": false,
    "signature_mode": "PDF_SIGNATURE",
    "signature_ordered": "INACTIVE",
    "owner": "Leonardo Daniel CRUZ ROSAS <leonardo.rosas041024@gmail.com>",
    "isOwner": true,
    "rejected_message": null,
    "tries": 3,
    "remember_at": "16:54:00",
    "remember_every": 3,
    "signed_at": null,
    "created_at": "2026-05-04T20:14:56.945158",
    "config": {
        "allow_type_signatures": [
            "VERIFICAMEX"
        ],
        "primary_color": null,
        "secondary_color": null,
        "lock_phone_for_otp": false,
        "identity_providers": [
            "LOCAL",
            "VERIFICAMEX"
        ]
    },
    "notification_mode": "ENABLED",
    "createdBy": null
},
"relationships": {
    "signatures": {
        "data": [
            {
                "type": "signatures",
                "id": "ac110005-9df4-1d1b-819d-f5eac478003b",
                "links": {
                    "self": "/signatures/ac110005-9df4-1d1b-819d-f5eac478003b"
                },
                "attributes": {
                    "name": "Leonardo Rosas",
                    "rfc": null,
                    "curp": null,
                    "email": "leonardo.rosas041024@gmail.com",
                    "sign_status": "PENDING",
                    "certificate_serial_number": null,
                    "certificate_issuer_name": null,
                    "signed_at": null,
                    "signature": null,
                    "updatedAt": "2026-05-04T20:14:56.888310424",
                    "createdAt": "2026-05-04T20:14:56.888302104"
                },
                "relationships": {
                    "timestamp": null
                }
            }
        ],
        "links": {
            "self": "/signatures"
        }
    },
    "constancy": null
}
}

Siguiente Paso

Una vez creado el registro, el documento se encuentra en estado “Pendiente de archivo”. Debes Subir el PDF para activar el proceso.