Ejemplos de uso — Consulta múltiple de folios

Esta sección muestra ejemplos reales y completos de cómo consumir el endpoint de consulta múltiple de folios.

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

• Qué se envía
• Qué se recibe
• Cómo interpretar la respuesta cuando hay múltiples resultados

---

Endpoint

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

---

Headers requeridos

Todos los ejemplos usan los siguientes encabezados HTTP:

x-api-key: Bearer {TOKEN_EMPRESA}
Content-Type: application/json

---

Parámetros de entrada

Campo	Ubicación	Tipo	Requerido	Descripción
folioId	Body	array de string	Sí	Lista de identificadores únicos de folios

---

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/consult",
  "headers": {
    "x-api-key": "Bearer sandbox_token_empresa_123",
    "Content-Type": "application/json"
  },
  "body": {
    "folioId": [
      "FOL_SANDBOX_001",
      "FOL_SANDBOX_002",
      "FOL_SANDBOX_003"
    ]
  }
}

---

Respuesta exitosa (200 OK)

Cuando la solicitud es válida, la API responde con un arreglo de resultados, uno por cada folio consultado.

Cada folio contiene su propio estado, lo que permite manejar resultados mixtos.

{
  "success": true,
  "status": 200,
  "data": [
    {
      "success": true,
      "status": 200,
      "message": "Consulta de folio completada con éxito.",
      "folioId": "15149c16b2e2d3733577d4036eb9d72fa7a392b2c40d4eb74058d59d3e22f266",
      "data": {
        "folioData": {
          "folioId": "15149c16b2e2d3733577d4036eb9d72fa7a392b2c40d4eb74058d59d3e22f266",
          "name": "Proceso de Contrato",
          "message": "Por favor firme el documento adjunto",
          "observation": null,
          "dateCreate": "2025-11-05 09:53:18",
          "dateLastUpdate": "2025-11-06 08:27:06",
          "state": "6",
          "flag_drop": "0",
          "stateName": "ANULADO",
          "signatureType": "1",
          "signatureTypeName": "OTP Básico"
        },
        "documents": [
          {
            "documentId": "e7c516cd6cbb4a4bdcbc2b4aa153a39fc9879ca3fe83a0490e8f0a0cf0390976",
            "name": "contrato.pdf",
            "dateCreate": "2025-11-05 09:53:18"
          }
        ],
        "signers": [
          {
            "name": "Juan Pérez",
            "documentType": "CC",
            "documentNumber": "1099377508",
            "email": "juan.perez@empresa.com",
            "cellPhoneNumber": "3002416734",
            "folioState": "2",
            "folioStateName": "PENDIENTE",
            "ipSignatureAddress": null,
            "dateLastUpdate": null
          }
        ]
      }
    },
    {
      "success": false,
      "status": 403,
      "message": "Acceso denegado. No tiene permisos para consultar este folio.",
      "folioId": "FOL_NO_AUTORIZADO",
      "data": null
    }
  ]
}

---

Cómo interpretar la respuesta

• Cada elemento del arreglo representa un folio
• Un folio puede:
  • Responder correctamente
  • Fallar por permisos
  • Fallar por formato inválido
• Un error en un folio no afecta a los demás

Esto permite manejar consultas masivas sin perder control individual.

---

Ejemplo de implementación — JavaScript / Node.js

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

  const data = await response.json();

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

  return data.data;
}

---

Ejemplo de implementación — Python

import requests

def consultar_folios(folio_ids, token):
    url = "https://www.sandboxadmin.firmaris.co/api/integrations/consult"
    headers = {
        "x-api-key": f"Bearer {token}",
        "Content-Type": "application/json"
    }

    response = requests.post(url, headers=headers, json={
        "folioId": folio_ids
    })

    response.raise_for_status()
    return response.json()["data"]

---

Ejemplo de implementación — PHP

function consultarFolios(array $folioIds, string $token): array
{
    $url = "https://www.sandboxadmin.firmaris.co/api/integrations/consult";

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode([
            'folioId' => $folioIds
        ]),
        CURLOPT_HTTPHEADER => [
            "x-api-key: Bearer {$token}",
            "Content-Type: application/json"
        ]
    ]);

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

    return json_decode($response, true)["data"];
}

---

Respuestas de error comunes

Error 400 — Solicitud inválida

{
  "success": false,
  "status": 400,
  "message": "El cuerpo de la solicitud no cumple el formato esperado."
}

---

Error 403 — Acceso denegado

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

---

Este endpoint se usa exclusivamente para lectura, seguimiento y auditoría. No modifica el proceso de firma ni altera información del sistema.