Flujo completo de integración — Gestión de folios en Firmaris

Este documento describe el flujo técnico recomendado para integrar Firmaris en un sistema externo, mostrando qué endpoint usar, cuándo usarlo y cómo implementarlo en cada etapa.

El flujo está diseñado para ser claro, auditable y escalable.

---

1. Creación del folio

Descripción

El flujo inicia con la creación de un folio, donde se definen:

• Documentos a firmar
• Firmantes
• Tipo de firma
• Mensajes iniciales

El sistema responde con un folioId, que será el identificador único del proceso.

Ninguna operación posterior es posible sin el folioId.

---

Endpoint

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

---

Ejemplo de implementación — JavaScript

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

  const data = await response.json();
  return data.data.folioId;
}

---

2. Proceso de firma

Descripción

Una vez creado, el folio entra en estado:

• PENDIENTE

Durante esta etapa:

• Se envían correos de firma
• Se generan enlaces de acceso
• Se registra cada acción del firmante

Este proceso es asíncrono y puede durar minutos u horas.

No existe un endpoint para “forzar” la firma; el proceso depende del firmante.

---

3. Consulta de folios

3.1 Consulta individual

Descripción

Permite conocer el estado actual de un folio específico, incluyendo:

• Estado general
• Firmantes
• Documentos
• Historial básico

Se usa para dashboards, validaciones y seguimiento.

---

Endpoint

GET https://www.sandboxadmin.firmaris.co/api/integrations/consult?folioId={folioId}

---

Ejemplo de implementación — JavaScript

async function consultarFolio(folioId, token) {
  const response = await fetch(
    `https://www.sandboxadmin.firmaris.co/api/integrations/consult?folioId=${folioId}`,
    {
      headers: {
        'x-api-key': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.json();
}

---

3.2 Consulta múltiple (masiva)

Descripción

Permite consultar varios folios en una sola solicitud.

Ideal para:

• Procesos batch
• Reportes
• Sincronización de estados

Cada folio se procesa de forma independiente.

---

Endpoint

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

---

Ejemplo de implementación — JavaScript

async function consultarFoliosMasivo(folios, token) {
  const formData = new FormData();
  formData.append('folios', JSON.stringify(folios));

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

  return response.json();
}

---

4. Acciones posteriores sobre el folio

Estas acciones no crean folios nuevos y dependen del estado actual.

---

4.1 Reenvío de correos de firma

Descripción

Permite reenviar correos de firma a firmantes existentes.

Características:

• No modifica el estado del folio
• No genera nuevos links
• Permite corregir email y teléfono

---

Endpoint

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

---

Ejemplo de implementación — JavaScript

async function reenviarCorreos(folioId, signers, token) {
  const formData = new FormData();
  formData.append('folioId', folioId);
  formData.append('signers', JSON.stringify(signers));

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

  return response.json();
}

---

4.2 Descarga de documentos

Descripción

Permite descargar un documento mediante su documentId.

• Retorna archivo binario (PDF)
• Requiere permisos
• Genera evento de auditoría

---

Endpoint

GET https://www.sandboxadmin.firmaris.co/api/integrations/download?documentId={documentId}

---

Ejemplo de implementación — JavaScript

async function descargarDocumento(documentId, token) {
  const response = await fetch(
    `https://www.sandboxadmin.firmaris.co/api/integrations/download?documentId=${documentId}`,
    {
      headers: {
        'x-api-key': `Bearer ${token}`
      }
    }
  );

  return response.blob();
}

---

4.3 Cancelación de folios

Descripción

Permite cancelar uno o varios folios de forma irreversible.

Requisitos:

• Observación obligatoria
• Estados cancelables
• Token válido

---

Endpoint

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

---

Ejemplo de implementación — JavaScript

async function cancelarFolios(folios, observation, token) {
  const formData = new FormData();
  formData.append('folios', JSON.stringify(folios));
  formData.append('observation', observation);

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

  return response.json();
}

---

5. Manejo de errores en el flujo

Errores comunes:

• 400 Validación
• 403 Permisos
• 404 Recurso inexistente
• 500 Error interno

Buenas prácticas:

• Manejar errores por folio en operaciones masivas
• Registrar operaciones críticas
• No reintentar errores de negocio

---

Conclusión

Este flujo representa la forma correcta y profesional de integrar Firmaris:

• Cada endpoint tiene una responsabilidad clara
• El folioId gobierna todo el ciclo
• El flujo es auditable y seguro
• Se adapta a procesos síncronos y asíncronos

---