Integración — Cancelación de Folios

Este endpoint permite cancelar uno o varios folios existentes en el sistema de Firmaris.

La cancelación es un proceso irreversible y requiere una observación obligatoria que quedará registrada en el historial del folio para efectos de auditoría y trazabilidad.

Endpoint

POST https://www.sandboxadmin.firmaris.co/api/integrations/cancel

Autenticación

La solicitud debe incluir un token de empresa válido en el encabezado HTTP.

x-api-key: Bearer {TOKEN_EMPRESA}

Body (form-data)

El cuerpo de la solicitud debe enviarse como multipart/form-data.

Parámetro	Tipo	Requerido	Descripción	Validaciones
`folios`	JSON string	Sí	Lista de IDs de folios a cancelar	JSON válido, array de strings, máximo 50 elementos
`observation`	string	Sí	Motivo de la cancelación	Mínimo 10 caracteres, máximo 500

Comportamiento del endpoint

El sistema procesa todos los folios enviados en la solicitud.
Cada folio es evaluado individualmente para verificar si se encuentra en un estado cancelable.
La cancelación no se revierte una vez ejecutada.
Si uno o más folios no pueden cancelarse, el sistema informará el resultado por folio.
La operación no bloquea la cancelación de folios válidos por errores en otros.

Estados permitidos para cancelación

Un folio solo puede cancelarse si se encuentra en alguno de los siguientes estados:

PENDIENTE

Estados NO cancelables

No es posible cancelar folios que se encuentren en estado:

FIRMADO
ANULADO
RECHAZADO

Estructura de la respuesta

La API retorna una respuesta JSON con el resultado del proceso de cancelación.

{
  "success": boolean,
  "status": number,
  "message": string,
  "data": {
    "cancelledFolios": number,
    "failedFolios": number,
    "details": [
      {
        "folioId": string,
        "status": string,
        "message": string
      }
    ]
  }
}

El objeto data puede variar según la implementación, pero siempre se retornará al menos el campo message.

Reglas y restricciones

Máximo 50 folios por solicitud
El campo observation es obligatorio
La cancelación es irreversible
El token debe pertenecer a la empresa propietaria de los folios
Folios ya cancelados o firmados no pueden ser anulados nuevamente

Impacto de la cancelación

Los firmantes asociados reciben notificación de cancelación
Los documentos dejan de estar disponibles para firma
El evento queda registrado para auditoría
La cancelación impacta métricas y reportes del sistema

Errores comunes

Error 400 — Parámetros inválidos

{
  "success": false,
  "status": 400,
  "error": {
    "message": "El parámetro (folios y observación) son obligatorios"
  }
}

Error 403 — Acceso denegado

{
  "success": false,
  "status": 403,
  "error": {
    "message": "Acceso denegado. No tiene permisos para cancelar uno o más folios."
  }
}

Error 500 — Error interno

{
  "success": false,
  "status": 500,
  "error": {
    "message": "No fue posible cancelar los folios, intente nuevamente."
  }
}

Checklist previo a la integración

Antes de consumir este endpoint, asegúrate de:

Contar con un token válido y activo
Tener permisos sobre todos los folios a cancelar
Enviar un array folios válido y no vacío
Enviar una observación con longitud permitida
Verificar que los folios estén en estado cancelable