Firmar con e.firma

e.firma (antes Firma Electrónica Avanzada) es el certificado digital personal que emite el SAT. En Verificamex Firma, un firmante puede usarlo para firmar un documento directamente con su propio certificado, sin pasar por el flujo guiado de validación de identidad.

Precaución

Para que un firmante pueda usar e.firma, el documento debe haberse creado con "EFIRMA" incluido en allow_type_signatures. Si el documento no lo permite, el endpoint responde con “El documento no permite firmas de este tipo”. Ver configuración de allow_type_signatures.

Endpoint

Método: POST https://api.digitafirma.com/v1/sign/{signatureId}

Encabezados de la Solicitud

Encabezado	Valor	Descripción
X-Api-Key	{id}:{secret}	Tu API Key, ver Uso de tokens.
Content-Type	multipart/form-data	El certificado y la llave se envían como archivos binarios.

Parámetros de Form-Data

Campo	Tipo	Requerido	Descripción
cer	file	Sí*	Certificado público de la e.firma (.cer).
key	file	Sí*	Llave privada de la e.firma (.key).
pfx	file	Sí*	Alternativa a cer + key: certificado en formato PKCS12 (.pfx).
password	string	Sí	Contraseña de la llave privada.

^* Envía cer + key, o bien pfx — no es necesario enviar los tres. Si no envías ninguna de las dos combinaciones completas, el endpoint responde con error de validación.

Nota

No existe un campo para indicar “esto es e.firma”. El sistema lee el certificado y detecta el tipo automáticamente según quién lo emitió (SERVICIO DE ADMINISTRACION TRIBUTARIA → e.firma). El mismo mecanismo reconoce certificados de FIREL y TEPJF, que se envían con los mismos campos.

Ejemplo

cURL

curl --location 'https://api.digitafirma.com/v1/sign/ac110005-9d7a-148c-819d-9cdca24f033e' \
  --header 'X-Api-Key: TU_ID:TU_SECRET' \
  --form 'cer=@"/ruta/a/certificado.cer"' \
  --form 'key=@"/ruta/a/llave.key"' \
  --form 'password=contraseña_de_la_llave'

Respuesta Exitosa (200)

{
  "data": [
    {
      "type": "signatures",
      "id": "ac110005-9d7a-148c-819d-9cdca24f033e",
      "links": {
        "self": "/signatures/ac110005-9d7a-148c-819d-9cdca24f033e"
      },
      "attributes": {
        "name": "JUAN PEREZ LOPEZ",
        "rfc": "PELJ800101ABC",
        "curp": "PELJ800101HDFRPN01",
        "email": "juanperez@gmail.com",
        "sign_status": "SIGNED",
        "certificate_serial_number": "3A2B1C...",
        "certificate_issuer_name": "SERVICIO DE ADMINISTRACION TRIBUTARIA",
        "signed_at": "2026-04-17T13:20:45.128Z",
        "signature": "MIIF...",
        "redirect_url": null,
        "allowed_signature_methods": null
      }
    }
  ]
}

Cómo firmar correctamente

1. El certificado debe ser una e.firma personal, no un CSD. Un Certificado de Sello Digital (el que se usa para timbrar facturas) tiene un campo OU que la e.firma personal no tiene. Si subes un CSD por error, la firma se rechaza.

2. El certificado debe estar vigente. El sistema valida las fechas de vigencia del propio certificado antes de firmar. Un certificado vencido o aún no vigente se rechaza.

3. El RFC o CURP debe coincidir con el firmante registrado, si al crear el documento le asignaste un rfc a ese firmante. El sistema extrae el RFC y el CURP directamente del certificado y los compara; si no coinciden con el firmante esperado, la firma se rechaza. Si no le asignaste un RFC al firmante, esta validación se omite.

4. La contraseña debe corresponder exactamente a la llave privada enviada. Una contraseña incorrecta impide abrir la llave y la firma falla.

5. En producción, el certificado no debe estar revocado. El sistema consulta al SAT (OCSP) para confirmar que la e.firma sigue vigente y no fue revocada antes de aplicar la firma.

Errores comunes

Código	Mensaje	Causa
400	El formato ingresado pertenece a un CSD, favor de ingresar una e.firma (FIEL)	Se envió un Certificado de Sello Digital en vez de una e.firma personal.
400	El certificado digital no está vigente	El certificado está vencido o su vigencia aún no inicia.
400	El RFC o CURP asignado a este firmante no coincide con el certificado digital esperado	El firmante fue registrado con un RFC distinto al que trae el certificado.
400	El certificado digital no es soportado	El emisor del certificado no es reconocido (no es SAT, Judicatura Federal, TEPJF ni Verificamex).
400	El documento no permite firmas de este tipo	El documento no incluyó "EFIRMA" en allow_type_signatures al crearse.
400	El documento ya ha sido firmado	Ese signatureId ya está en estatus SIGNED o REJECTED.

Consejo

Todos estos errores llegan con status HTTP 400 (o 401 si el problema es de autenticación) dentro de errors[0].detail, siguiendo el mismo formato de respuesta que el resto de la API.