Invalidar una firma

Cuando necesitas reemplazar a un firmante o corregir datos incorrectos en una firma ya completada, puedes invalidar la firma existente y opcionalmente invitar a un nuevo firmante. Este tutorial explica cómo invalidar una firma utilizando la API de Signatura.

Acción irreversible

La invalidación de una firma es una acción permanente que no se puede deshacer. La firma invalidada quedará marcada como tal y no podrá ser restaurada.

Casos de uso comunes

• El firmante utilizó datos incorrectos (email, teléfono o documento de identidad equivocado)
• Se necesita reemplazar al firmante por otra persona
• El firmante ya no está autorizado para firmar el documento
• Se detectó un error después de que la firma fue completada

Requisitos previos

Para invalidar una firma necesitas:

• Una API key válida
• El ID de la firma (signature_id) que deseas invalidar
• Un motivo de invalidación

Endpoint

PATCH /api/v2/signatures/{id}/invalidate
Authorization: Bearer <apikey>
Content-Type: application/json

El parámetro {id} corresponde al UUID de la firma que deseas invalidar.

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
invalidation_reason	string	Sí	Motivo de la invalidación
new_signer	string	No	Email o teléfono del nuevo firmante. Requerido si deseas enviar la invitación a una persona diferente
custom_signature	object	No	Configuración personalizada para la nueva firma (validaciones, mensaje, canal de invitación)
notify	boolean	Sí	Si es true, se notifica al firmante original sobre la invalidación

Estructura de custom_signature

Si necesitas cambiar las validaciones o el canal de invitación para el nuevo firmante:

Campo	Tipo	Descripción
validations	object	Validaciones requeridas (EM, PH, BI, AF)
message	string	Mensaje personalizado para la invitación por email
invite_channel	array	Canales de invitación: ["EM"] para email, ["PH"] para SMS

Ejemplo: Invalidar y notificar al firmante original

curl -X PATCH "https://connect.signatura.co/api/v2/signatures/f5407940-6d19-4508-baed-195c03fcf739/invalidate" \
  -H "Authorization: Bearer <apikey>" \
  -H "Content-Type: application/json" \
  -d '{
    "invalidation_reason": "El firmante utilizó un documento de identidad incorrecto",
    "notify": true
  }'

Ejemplo: Reemplazar al firmante por otra persona

curl -X PATCH "https://connect.signatura.co/api/v2/signatures/f5407940-6d19-4508-baed-195c03fcf739/invalidate" \
  -H "Authorization: Bearer <apikey>" \
  -H "Content-Type: application/json" \
  -d '{
    "invalidation_reason": "Cambio de representante legal",
    "new_signer": "nuevo_firmante@example.org",
    "notify": true
  }'

Ejemplo: Reemplazar con validaciones personalizadas

curl -X PATCH "https://connect.signatura.co/api/v2/signatures/f5407940-6d19-4508-baed-195c03fcf739/invalidate" \
  -H "Authorization: Bearer <apikey>" \
  -H "Content-Type: application/json" \
  -d '{
    "invalidation_reason": "Datos incorrectos",
    "new_signer": "nuevo_firmante@example.org",
    "custom_signature": {
      "validations": {
        "EM": "nuevo_firmante@example.org",
        "PH": null
      },
      "message": "Por favor, firme este documento actualizado.",
      "invite_channel": ["EM"]
    },
    "notify": false
  }'

Ejemplo de respuesta

{
  "id": "f5407940-6d19-4508-baed-195c03fcf739",
  "invalidation_reason": "Cambio de representante legal",
  "status": "CA",
  "new_signature_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

Campos de la respuesta

Campo	Tipo	Descripción
id	string	UUID de la firma invalidada
invalidation_reason	string	Motivo de la invalidación
status	string	Nuevo estado de la firma (CA = Cancelada)
new_signature_id	string	UUID de la nueva firma creada para reemplazar la invalidada (solo si se especificó new_signer o custom_signature)

Códigos de respuesta

Código	Descripción
200	Firma invalidada correctamente
400	Datos de entrada inválidos
404	La firma no existe
429	Demasiadas solicitudes (rate limiting)

¿Qué sucede al invalidar una firma?

Cuando invalidas una firma:

1. El estado de la firma original cambia a Cancelada (CA)
2. Se registra el motivo de invalidación
3. Si especificaste new_signer o custom_signature, se crea una nueva firma con estado Inicial (IN)
4. Si notify es true, el firmante original recibe una notificación
5. Si se creó una nueva firma, el nuevo firmante recibe una invitación según el canal configurado
6. El documento permanece en estado Pendiente (PE) hasta que se completen las firmas requeridas

Diferencia entre invalidar y cancelar

Acción	Alcance	Efecto en el documento
Invalidar firma	Solo afecta una firma específica	El documento continúa activo, se puede asignar un nuevo firmante
Cancelar documento	Afecta todo el documento y todas sus firmas	El documento completo queda cancelado

Usa invalidar cuando necesites corregir o reemplazar una firma específica sin afectar al resto del documento.