# Crear un documento.

Fuente: /document-management/create-document/

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](/work-folders/work-folders-list)). |
| `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](/document-management/custom-signature-position)). 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](/webhooks/document-webhooks) y cómo validar su firma en [Seguridad de webhooks](/webhooks/webhooks-security). |
| `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](#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](#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](/document-management/update-signature-methods).

**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](/document-management/custom-signature-position)). |
| `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](/document-management/update-signature-methods). |
| `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](#parámetros-de-la-petición)) |

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:

```json
{
  "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](/work-folders/work-folders-upload) (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**

```json
{
  "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)**

```json
{
  "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](/document-management/upload-document) para activar el proceso.