Ejemplos de uso — Cancelación de Folios

Esta sección muestra ejemplos reales y completos de cómo cancelar uno o varios folios mediante la API de Firmaris.

Está pensada para que cualquier persona — incluso sin experiencia previa — pueda entender:

• Qué se envía
• Qué se recibe
• Cómo interpretar la respuesta del sistema

---

Endpoint

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

---

Headers requeridos

Todos los ejemplos utilizan los siguientes encabezados HTTP:

x-api-key: Bearer {TOKEN_EMPRESA}
Content-Type: multipart/form-data

---

Parámetros de entrada (form-data)

Parámetro	Tipo	Requerido	Descripción
folios	JSON string	Sí	Lista de IDs de folios a cancelar
observation	string	Sí	Motivo de la cancelación

---

Ejemplo de solicitud (Postman)

Este ejemplo representa exactamente lo que Postman enviaría al backend.

{
  "method": "POST",
  "url": "https://www.sandboxadmin.firmaris.co/api/integrations/cancel",
  "headers": {
    "x-api-key": "Bearer sandbox_token_empresa_123"
  },
  "body": {
    "mode": "formdata",
    "formdata": [
      {
        "key": "folios",
        "value": "[\"9ef63bb5b1d84969aed5ef648a1csdfsfsfs58a0961efda6bc11747855f321f68\",\"8cd45f7b2dgdfg845g8d6ef759b2d1cfc68869b1a73fec7ac22858966e4321g79\"]"
      },
      {
        "key": "observation",
        "value": "Cancelación por pruebas en ambiente sandbox"
      }
    ]
  }
}

---

Respuesta exitosa (200 OK)

Cuando los folios son válidos y el token tiene permisos, la API responde:

{
  "success": true,
  "status": 200,
  "message": "Los folios han sido anulados correctamente"
}

---

Respuesta con detalle por folio

En algunos casos, la API retorna el resultado individual de cada folio.

{
  "success": true,
  "status": 200,
  "message": "Proceso de cancelación ejecutado",
  "data": {
    "cancelledFolios": 1,
    "failedFolios": 1,
    "details": [
      {
        "folioId": "9ef63bb5b1d84969aed5ef648a1c0bedfg5848dfg961efda6bc11747855f321f68",
        "status": "CANCELLED",
        "message": "Folio cancelado exitosamente"
      },
      {
        "folioId": "1111111111111111111111111111111111111111111111111111111111111111",
        "status": "FAILED",
        "message": "El folio no se encuentra en un estado cancelable"
      }
    ]
  }
}

---

Ejemplo de implementación — JavaScript / Node.js

async function cancelarFolios(folioIds, observation, token) {
  const response = await fetch(
    'https://www.sandboxadmin.firmaris.co/api/integrations/cancel',
    {
      method: 'POST',
      headers: {
        'x-api-key': `Bearer ${token}`
      },
      body: new URLSearchParams({
        folios: JSON.stringify(folioIds),
        observation
      })
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || 'Error cancelando folios');
  }

  return data;
}

---

Ejemplo de implementación — Python

import requests
import json

def cancelar_folios(folios, observation, token):
    url = "https://www.sandboxadmin.firmaris.co/api/integrations/cancel"
    headers = {
        "x-api-key": f"Bearer {token}"
    }
    data = {
        "folios": json.dumps(folios),
        "observation": observation
    }

    response = requests.post(url, headers=headers, data=data)
    response.raise_for_status()

    return response.json()

---

Ejemplo de implementación — PHP

function cancelarFolios(array $folios, string $observation, string $token): array
{
    $url = 'https://www.sandboxadmin.firmaris.co/api/integrations/cancel';

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => [
            'folios' => json_encode($folios),
            'observation' => $observation
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            "x-api-key: Bearer {$token}"
        ]
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

---

Respuestas de error comunes

Error 400 — Parámetros inválidos

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

Error 403 — Acceso denegado

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

Error 500 — Error interno

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

---

Este endpoint se utiliza para gestionar el ciclo de vida de los folios, mantener el sistema limpio y cumplir con procesos de auditoría.