Cancelar un documento

En ocasiones puede ser necesario cancelar un documento que aún no ha sido firmado completamente. Este tutorial explica cómo cancelar un documento utilizando la API de Signatura.

Acción irreversible

La cancelación de un documento es una acción permanente que no se puede deshacer. Asegúrate de que realmente deseas cancelar el documento antes de proceder.

Requisitos previos

Para cancelar un documento necesitas:

• Una API key válida
• El ID del documento (document_id)
• El documento debe estar en estado Borrador (DR) o Pendiente (PE)

No es posible cancelar documentos que ya han sido completados o cancelados previamente.

Endpoint

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

El parámetro {id} corresponde al UUID del documento que deseas cancelar.

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
cancel_reason	string	No	Motivo de la cancelación (máximo 254 caracteres)

Ejemplo de solicitud

curl -X PATCH "https://connect.signatura.co/api/v2/documents/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel" \
  -H "Authorization: Bearer <apikey>" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_reason": "El contrato fue reemplazado por una nueva versión"
  }'

Ejemplo de respuesta

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "Contrato de servicios",
  "status": "CA",
  "cancel_reason": "El contrato fue reemplazado por una nueva versión",
  "signatures": [
    {
      "id": "f5407940-6d19-4508-baed-195c03fcf739",
      "created_date": "2024-01-15T10:30:00Z",
      "validations": {
        "EM": {"value": "cliente@example.com", "validated": false}
      },
      "invite_channel": ["EM"],
      "status": "CA",
      "url": "https://connect.signatura.co/s/abc123"
    }
  ]
}

Campos de la respuesta

Campo	Tipo	Descripción
id	string	UUID del documento
title	string	Título del documento
status	string	Nuevo estado del documento (CA = Cancelado)
cancel_reason	string	Motivo de la cancelación
signatures	array	Lista de firmas asociadas al documento
signatures[].id	string	UUID de la firma
signatures[].status	string	Estado de la firma (CA = Cancelada)

Estados de documento

Código	Estado	¿Se puede cancelar?
DR	Borrador	Sí
PE	Pendiente	Sí
CO	Completado	No
CA	Cancelado	No

Códigos de respuesta

Código	Descripción
200	Documento cancelado correctamente
400	El documento no está en estado Borrador o Pendiente
404	El documento no existe
429	Demasiadas solicitudes (rate limiting)

¿Qué sucede al cancelar un documento?

Cuando cancelas un documento:

1. El estado del documento cambia a Cancelado (CA)
2. Todas las firmas pendientes se cancelan automáticamente
3. Los firmantes que aún no han firmado ya no podrán hacerlo
4. Se envía un webhook DC (Document status Changed) si tienes configurado uno
5. El documento permanece visible en tu cuenta para referencia histórica

Notificaciones webhook

Si tienes configurado un webhook, recibirás una notificación cuando el documento sea cancelado:

{
  "notification_action": "DC",
  "document_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "new_status": "CA"
}

Para más información sobre webhooks, consulta la documentación de webhooks.