Ejemplos de uso — Firma masiva de folios

Esta sección contiene ejemplos reales y completos de cómo utilizar el endpoint de firma masiva de folios.

Está pensada para que cualquier persona pueda entender:

• Qué se envía
• Cómo se envía
• Qué se recibe
• Cómo usar la respuesta

---

Endpoint

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

---

Headers requeridos

Todos los ejemplos usan los siguientes encabezados:

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

---

Ejemplo de solicitud (Postman)

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

{
  "method": "POST",
  "url": "https://www.sandboxadmin.firmaris.co/api/integrations/massive_sign",
  "headers": {
    "x-api-key": "Bearer sandbox_token_empresa_123"
  },
  "body": {
    "mode": "formdata",
    "formdata": [
      {
        "key": "foliosIds",
        "value": "[\"9ef63bb5b1d84969aed5ef648a1c0beb57758a0961efda6bc11747855f321f68\",\"8cd45f7b2e89567bcfd6ef759b2d1cfc68869b1a73fec7ac22858966e4321g79\"]"
      },
      {
        "key": "signer",
        "value": "[{\"name\":\"Carlos López\",\"email\":\"carlos@example.com\",\"documentType\":\"CC\",\"documentNumber\":\"123456789\",\"cellPhoneNumber\":\"3001234567\"}]"
      },
      {
        "key": "urlReturn",
        "value": "https://miempresa.com/callback"
      }
    ]
  }
}

---

Respuesta exitosa (200 OK)

Cuando todo es válido, la API genera una URL única de firma masiva.

{
  "success": true,
  "status": 200,
  "message": "Generación de URL para firma masiva completada con éxito",
  "data": {
    "signProcessMassiveUrl": "https://www.devapp.firmaris.co/?msv=ENCRYPTED_PACKAGE_ID&a=ENCRYPTED_ACCOUNT_ID&cc=BASE64_DOCUMENT_NUMBER&ur=https://miempresa.com/callback&rej=false",
    "massiveId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  }
}

---

Cómo usar la respuesta

1. Toma el valor signProcessMassiveUrl
2. Envíalo al firmante (correo, WhatsApp, etc.)
3. El firmante accede
4. Firma todos los folios en una sola sesión
5. Usa massiveId para seguimiento posterior

---

Ejemplo de implementación — JavaScript / Node.js

async function firmarFoliosMasivamente(foliosIds, signer, urlReturn, token) {
  const formData = new FormData();

  formData.append('foliosIds', JSON.stringify(foliosIds));
  formData.append('signer', JSON.stringify([signer]));
  formData.append('urlReturn', urlReturn);

  const response = await fetch(
    'https://www.sandboxadmin.firmaris.co/api/integrations/massive_sign',
    {
      method: 'POST',
      headers: {
        'x-api-key': `Bearer ${token}`
      },
      body: formData
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.error?.message || 'Error en firma masiva');
  }

  return data.data;
}

---

Ejemplo de implementación — Python

import requests

def firmar_folios_masivamente(folios_ids, signer, url_return, token):
    url = "https://www.sandboxadmin.firmaris.co/api/integrations/massive_sign"

    payload = {
        "foliosIds": json.dumps(folios_ids),
        "signer": json.dumps([signer]),
        "urlReturn": url_return
    }

    headers = {
        "x-api-key": f"Bearer {token}"
    }

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

    return response.json()["data"]

---

Ejemplo de implementación — PHP

function firmarFoliosMasivamente(array $foliosIds, array $signer, string $urlReturn, string $token): array
{
    $url = 'https://www.sandboxadmin.firmaris.co/api/integrations/massive_sign';

    $postFields = [
        'foliosIds' => json_encode($foliosIds),
        'signer' => json_encode([$signer]),
        'urlReturn' => $urlReturn
    ];

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $postFields,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'x-api-key: Bearer ' . $token
        ]
    ]);

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

    return json_decode($response, true);
}

---

Errores comunes

Error 400 — Validación de parámetros

{
  "success": false,
  "status": 400,
  "message": "Parámetros inválidos en la solicitud."
}

---

Error 403 — Acceso denegado

{
  "success": false,
  "status": 403,
  "error": {
    "message": "Acceso denegado. No tiene permisos para acceder a este recurso."
  }
}

---

Error 409 — Firmante ya firmó o rechazó

{
  "success": false,
  "status": 409,
  "error": {
    "message": "El firmante ya ha realizado la firma o rechazado este folio."
  }
}

---

Recordatorios importantes

• signer SIEMPRE debe ser un array con un solo objeto
• foliosIds NO debe contener duplicados
• Todos los folios deben estar PENDIENTES
• La URL generada expira en 24 horas
• Este endpoint no firma automáticamente, solo genera la URL

---

Este archivo solo contiene ejemplos.
La explicación completa de reglas, validaciones y estructura está en el archivo de integración correspondiente.