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	Obligatorio	Descripción
company_id	string	Sí	ID de la carpeta de trabajo (consulta Listar carpetas de trabajo).
sign_mode	enum	Sí	Modo de firmado (CLASSIC, PDF_SIGNATURE, CLASSIC_BATCH).
sign_position	enum	Sí	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). Si sign_mode es CLASSIC, debe ser NONE.
mode_logo	enum	Sí	Cómo se presenta el logo en el documento firmado: FULL_BRANDING, MEDIUM_BRANDING, NO_BRANDING o NO_SIGNATURE_SHEET.
sign_ordered	enum	Sí	ACTIVE para forzar el orden del array de firmantes; INACTIVE para que firmen en cualquier orden.
webhook	string	No	URL que recibirá notificaciones de estado. Debe ser una URL real y accesible: el valor no se valida al crear el documento, así que una URL incorrecta solo se nota cuando las notificaciones dejan de llegar. Ver qué se envía en Webhooks de documentos y cómo validar su firma en Seguridad de webhooks.
redirect_url	string	No	URL a la que se redirige al firmante al concluir el proceso. 100% retrocompatible. Ver URL de redirección por documento.

Configuración de Firma

Campo	Tipo	Obligatorio	Descripción
config	Object	No	Si lo omites por completo, el documento acepta todos los tipos de firma.
config.allow_type_signatures	Array	Sí, si envías config	Métodos permitidos (VERIFICAMEX, EFIRMA, FIREL, TEPJF). Un arreglo vacío equivale a aceptar todos.
config.identity_providers	Array	No	Proveedores admitidos (VERIFICAMEX, LOCAL).
config.custom_branding	boolean	No	true para mostrar el logo de tu carpeta de trabajo en correos, pantalla de firma y validación de identidad, aunque no uses la hoja de firmas. Por defecto false. Ver Logo de tu carpeta en el proceso de firma.

Puedes cambiar allow_type_signatures e identity_providers después de crear el documento, mientras no esté firmado ni rechazado. Ver Cambiar los métodos de firma.

Participantes

Campo	Tipo	Obligatorio	Descripción
signatures	Array	Sí	Lista de personas que deben firmar. Cada firmante requiere name y email. Opcionalmente phone, rfc y positions (coordenadas manuales, ver Firma con posiciones personalizadas).
signatures[].rfc	string	No	RFC o CURP real del firmante. Al firmar con e.firma o FIREL se compara contra el certificado y, si no coincide, la firma se rechaza. Omítelo si no necesitas esta verificación.
signatures[].allowed_signature_methods	Array	No	Métodos permitidos solo para ese firmante: IDENTITY, SIMPLE, EFIRMA, FIREL. Mandan sobre los del documento. Si se omite, el firmante usa los de config. Se pueden cambiar después, ver Cambiar los métodos de firma.
spectators	Array	No	Personas con acceso de solo lectura. Cada espectador requiere name y email.

Notificaciones

Campo	Tipo	Obligatorio	Descripción
notification_mode	enum	No	ENABLED o DISABLED. Si se omite, se usa ENABLED.
tries	int	Sí	Cantidad de intentos de notificación (mínimo 1). Valor predeterminado recomendado: 3.
remember_every	int	Sí	Frecuencia de recordatorios en días. Valor predeterminado recomendado: 3.
remember_at	string	Sí	Hora del recordatorio (HH:mm). Valor predeterminado recomendado: 12:30.

Opciones que dependen de tu plan

Algunas opciones solo están disponibles si el plan del dueño de la carpeta de trabajo las incluye. Si no es así, la API responde 403 con el mensaje “El usuario no tiene los privilegios para usar esta característica”:

• sign_ordered: "ACTIVE" (firma ordenada).
• mode_logo distinto de FULL_BRANDING (hoja de firmas personalizada).
• Recordatorios distintos a los predeterminados (remember_at: "12:30", remember_every: 3, tries: 3).
• rfc en cualquier firmante (verificación del firmante).

---

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 Verificamex Firma: 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 Verificamex Firma. 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 Verificamex Firma 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. Verificamex Firma solo redirige al finalizar.

Cómo funciona

1. Creas el documento incluyendo redirect_url en la petición al endpoint de creación.
2. Verificamex Firma 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.

---

Logo de tu carpeta en el proceso de firma

Puedes mostrar el logo de tu carpeta de trabajo, en lugar del de Verificamex, en todo lo que ve el firmante durante el proceso:

• Los correos de invitación, de recordatorio y de documento firmado.
• La pantalla de firma.
• La validación de identidad.

Hay dos formas de activarlo:

Opción	Hoja de firmas	¿Requiere plan?
config.custom_branding: true	Independiente: usa la que elijas en mode_logo, incluso FULL_BRANDING o NO_SIGNATURE_SHEET.	No (el mode_logo que elijas sigue sus propias reglas)
mode_logo: "MEDIUM_BRANDING"	La hoja de firmas también lleva tu logo.	Sí, hoja de firmas personalizada (ver Opciones que dependen de tu plan)

Usa custom_branding si quieres tu logo en el proceso de firma sin personalizar la hoja de firmas. Por ejemplo, con la hoja de firmas estándar, que funciona con cualquier plan:

{
  "sign_mode": "PDF_SIGNATURE",
  "sign_position": "LOWER_RIGHT",
  "mode_logo": "FULL_BRANDING",
  "config": {
    "allow_type_signatures": ["VERIFICAMEX"],
    "custom_branding": true
  }
}

Antes de activarlo

• Tu carpeta de trabajo debe tener logo. Súbelo con Actualizar carpetas de trabajo (campo companyRequest.logo). Si la carpeta no tiene logo, o no se puede leer, se usa el de Verificamex y el proceso de firma continúa sin errores.
• Se define al crear el documento y no se puede cambiar después.
• No aplica a documentos dentro de contenedores (lotes), que manejan su logo por separado.

---

Ejemplo de Integración

JSON de Petición

{
  "company_id": "ac110005-9d0c-1243-819d-0c3b71220000",
  "sign_mode": "PDF_SIGNATURE",
  "sign_position": "LOWER_RIGHT",
  "mode_logo": "FULL_BRANDING",
  "sign_ordered": "INACTIVE",
  "config": {
    "identity_providers": [
      "VERIFICAMEX",
      "LOCAL"
    ],
    "allow_type_signatures": [
      "VERIFICAMEX",
      "EFIRMA",
      "FIREL"
    ]
  },
  "signatures": [
    {
      "name": "Juan Perez",
      "email": "jpe@gmail.com",
      "phone": "+522291449388"
    }
  ],
  "spectators": [
    {
      "name": "Hector Lavoe",
      "email": "hl@hotmail.com"
    }
  ],
  "webhook": "https://tudominio.com/webhooks/verificamex-firma",
  "redirect_url": "https://tudominio.com/fin-firma",
  "notification_mode": "ENABLED",
  "tries": 3,
  "remember_every": 3,
  "remember_at": "12:30"
}

Este ejemplo usa los valores predeterminados de recordatorios y sign_ordered: "INACTIVE", así que funciona con cualquier plan. Para verificar el RFC o CURP del firmante, agrega "rfc" con su valor real (ver la pestaña Participantes).

Respuesta Exitosa (201 Created)

{
  "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": "Nombre Apellido <dueno@tudominio.com>",
    "isOwner": true,
    "rejected_message": null,
    "tries": 3,
    "remember_at": "12:30:00",
    "remember_every": 3,
    "signed_at": null,
    "created_at": "2026-05-04T20:14:56.945158",
    "redirect_url": "https://tudominio.com/fin-firma",
    "config": {
      "allow_type_signatures": [
        "VERIFICAMEX",
        "EFIRMA",
        "FIREL"
      ],
      "primary_color": null,
      "secondary_color": null,
      "lock_phone_for_otp": false,
      "identity_providers": [
        "VERIFICAMEX",
        "LOCAL"
      ],
      "custom_branding": false,
      "sender_name": null,
      "sender_email": null
    },
    "notification_mode": "ENABLED",
    "createdBy": "Nombre Apellido <dueno@tudominio.com>"
  },
  "relationships": {
    "signatures": {
      "data": [
        {
          "type": "signatures",
          "id": "ac110005-9df4-1d1b-819d-f5eac478003b",
          "links": {
            "self": "/signatures/ac110005-9df4-1d1b-819d-f5eac478003b"
          },
          "attributes": {
            "name": "Juan Perez",
            "rfc": null,
            "curp": null,
            "email": "jpe@gmail.com",
            "sign_status": "PENDING",
            "certificate_serial_number": null,
            "certificate_issuer_name": null,
            "signed_at": null,
            "signature": null,
            "redirect_url": "https://tudominio.com/fin-firma",
            "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.