Ejemplos de uso — Consulta individual de folio

Esta sección muestra ejemplos reales y completos de cómo consumir el endpoint de consulta de folios. Está pensada para que cualquier persona — incluso sin experiencia previa — pueda entender qué se envía, qué se recibe y cómo usar la respuesta.

---

Endpoint

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

---

Headers requeridos

Todos los ejemplos usan los siguientes encabezados HTTP:

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

---

Parámetros de entrada

Parámetro	Ubicación	Tipo	Requerido	Descripción
folioId	Query	string	Sí	Identificador único del folio a consultar

---

Ejemplo de solicitud (Postman)

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

{
  "method": "GET",
  "url": "https://www.sandboxadmin.firmaris.co/api/integrations/consult?folioId=9ef63bb5b1d84969aed5ef648a1c0beb57758a0961efda6bc11747855f321f68",
  "headers": {
    "x-api-key": "Bearer sandbox_token_empresa_123",
    "Content-Type": "application/json"
  }
}

Respuesta exitosa (200 OK)
Cuando el folio existe y el token es válido, la API responde con toda la información estructurada del proceso.

{
  "success": true,
  "status": 200,
  "message": "Consulta de folio completada con éxito.",
  "data": {
    "folioData": {
      "folioId": "abc123def456ghi789ayehnr6no345pqr678",
      "name": "archivo1",
      "message": "Para continuar con el proceso se debe firmar el documento adjunto...",
      "observation": null,
      "dateCreate": "2024-01-15 10:30:00",
      "dateLastUpdate": "2024-01-16 14:45:00",
      "state": "1",
      "flag_drop": "0",
      "stateName": "FIRMADO",
      "signatureType": "1",
      "signatureTypeName": "OTP Básico"
    },
    "documents": [
      {
        "documentId": "doc1234567890abcdef9874561230abcdef",
        "name": "ejemplo.pdf",
        "dateCreate": "2024-01-15 10:30:00"
      }
    ],
    "signers": [
      {
        "name": "EJEMPLO NOMBRE APELLIDO",
        "documentType": "CC",
        "documentNumber": "1234567890",
        "email": "ejemplo@empresa.com",
        "cellPhoneNumber": "3001234567",
        "folioState": "1",
        "folioStateName": "FIRMADO",
        "ipSignatureAddress": "192.168.1.100",
        "dateLastUpdate": "2024-01-16 14:45:00"
      }
    ]
  }
}

Ejemplo de implementación — JavaScript / Node.js

async function consultarFolio(folioId, token) {
  const url = `https://www.sandboxadmin.firmaris.co/api/integrations/consult?folioId=${folioId}`;

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'x-api-key': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();

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

  return data.data;
}

Ejemplo de implementación — Python

import requests

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

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()["data"]

Ejemplo de implementación — PHP

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

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        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 — Folio inválido

{
  "success": false,
  "status": 400,
  "message": "El ID del folio a consultar no existe o no contiene un formato válido."
}

Error 403 — Acceso denegado

{
  "success": false,
  "status": 403,
  "message": "Acceso denegado. No tiene permisos para consultar este folio."
}

Error 404 — Recurso no encontrado

{
  "success": false,
  "status": 404,
  "message": "El recurso solicitado no existe."
}

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