Documentacion

API Reference

La API de Keeep te permite certificar contenido web, gestionar certificados y verificar evidencia de forma programatica. Todas las respuestas son JSON salvo las descargas de archivos binarios.

Base URL

https://keeep.omniscius.pro/api

Content-Type: application/json

Autenticacion

La API soporta dos metodos de autenticacion. Ambos se envian en el headerAuthorizationde cada peticion.

JWT Bearer Token

Obtenido al hacer login o registro. Expira en 7 dias. Recomendado para aplicaciones frontend y flujos interactivos.

Authorization: Bearer eyJhbG...

API KeyBUSINESS+

Keys con prefijo wpk_ para integraciones servidor-a-servidor. No expiran hasta ser revocadas.

Authorization: Bearer wpk_live_a1b2...

Ejemplo de peticion autenticada

curl https://keeep.omniscius.pro/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Limites de uso

Para garantizar la estabilidad del servicio, la API aplica limites de velocidad por IP y por usuario. Cuando se excede un limite, la API responde con429 Too Many Requests.

Recurso	Limite	Ventana
Peticiones generales	100	15 minutos
Creacion de sesiones	10	1 hora
Verificaciones	30	15 minutos

Nota: Los headers de respuesta incluyen X-RateLimit-Remaining y X-RateLimit-Reset para que puedas gestionar el consumo de forma proactiva.

Endpoints

Autenticacion

Endpoints para registro, login y gestion de la sesion del usuario.

POST/api/auth/register

AUTH

Crea una nueva cuenta de usuario. El campo name es opcional. Devuelve el objeto de usuario y un token JWT valido para autenticar las siguientes peticiones.

Request body

{
  "email": "usuario@ejemplo.com",
  "password": "miPassword123",
  "name": "Juan Garcia"
}

Response

{
  "user": {
    "id": "usr_abc123",
    "email": "usuario@ejemplo.com",
    "name": "Juan Garcia",
    "plan": "free",
    "createdAt": "2026-01-15T10:30:00.000Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

POST/api/auth/login

AUTH

Inicia sesion con credenciales existentes. Devuelve el usuario y un nuevo token JWT.

Request body

{
  "email": "usuario@ejemplo.com",
  "password": "miPassword123"
}

Response

{
  "user": {
    "id": "usr_abc123",
    "email": "usuario@ejemplo.com",
    "name": "Juan Garcia",
    "plan": "professional",
    "createdAt": "2026-01-15T10:30:00.000Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

GET/api/auth/me

AUTH

Devuelve la informacion del usuario autenticado. Util para validar el token y obtener el estado actual de la cuenta.

Response

{
  "user": {
    "id": "usr_abc123",
    "email": "usuario@ejemplo.com",
    "name": "Juan Garcia",
    "plan": "professional",
    "certsUsed": 3,
    "certsLimit": 10,
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

Sesiones

Crea y gestiona sesiones de certificacion. Una sesion representa el proceso de captura de una pagina web.

POST/api/sessions

AUTH

Crea una nueva sesion de certificacion. El campo sessionType puede ser "static" (captura unica) o "interactive" (sesion con navegacion en vivo, plan Professional+). La URL debe ser accesible publicamente.

Request body

{
  "targetUrl": "https://ejemplo.com/pagina",
  "sessionType": "static"
}

Response

{
  "session": {
    "id": "ses_xyz789",
    "targetUrl": "https://ejemplo.com/pagina",
    "sessionType": "static",
    "status": "created",
    "createdAt": "2026-02-14T08:00:00.000Z"
  }
}

POST/api/sessions/:id/start

AUTH

Inicia la captura de la sesion. El servidor lanzara un navegador headless, capturara la pagina, generara screenshots, y comenzara el proceso de certificacion (hashing, firma, sello temporal).

Response

{
  "session": {
    "id": "ses_xyz789",
    "status": "capturing",
    "startedAt": "2026-02-14T08:00:05.000Z"
  },
  "message": "Sesion iniciada correctamente"
}

POST/api/sessions/:id/stop

AUTH

Detiene una sesion interactiva en curso. Solo aplicable a sesiones de tipo "interactive". Las sesiones estaticas finalizan automaticamente.

Response

{
  "session": {
    "id": "ses_xyz789",
    "status": "processing",
    "stoppedAt": "2026-02-14T08:05:00.000Z"
  },
  "message": "Sesion detenida, procesando certificado"
}

GET/api/sessions/:id

AUTH

Obtiene el estado detallado de una sesion. Usa este endpoint para hacer polling del estado mientras la sesion esta en "capturing" o "processing".

Response

{
  "session": {
    "id": "ses_xyz789",
    "targetUrl": "https://ejemplo.com/pagina",
    "sessionType": "static",
    "status": "completed",
    "certificateId": "cert_abc456",
    "createdAt": "2026-02-14T08:00:00.000Z",
    "startedAt": "2026-02-14T08:00:05.000Z",
    "completedAt": "2026-02-14T08:00:35.000Z"
  }
}

GET/api/sessions

AUTH

Lista todas las sesiones del usuario autenticado, ordenadas por fecha de creacion descendente. Soporta paginacion con los parametros query ?page=1&limit=20.

Response

{
  "sessions": [
    {
      "id": "ses_xyz789",
      "targetUrl": "https://ejemplo.com/pagina",
      "status": "completed",
      "certificateId": "cert_abc456",
      "createdAt": "2026-02-14T08:00:00.000Z"
    }
  ]
}

Certificados

Consulta, descarga y gestiona los certificados generados tras completar una sesion de captura.

GET/api/certificates

AUTH

Lista todos los certificados del usuario. Cada certificado incluye metadatos de verificacion, estado del sello temporal y anclaje Bitcoin si aplica.

Response

{
  "certificates": [
    {
      "id": "cert_abc456",
      "url": "https://ejemplo.com/pagina",
      "status": "certified",
      "verificationCode": "KP-2026-A7X9B2",
      "sha256": "a1b2c3d4e5f6...",
      "hasRSA": true,
      "hasTimestamp": true,
      "hasBitcoin": false,
      "createdAt": "2026-02-14T08:00:35.000Z"
    }
  ]
}

GET/api/certificates/:id

AUTH

Obtiene el detalle completo de un certificado, incluyendo toda la cadena de evidencia: hashes, firma RSA, sello RFC 3161, transaccion Bitcoin (si aplica) y metadatos del proceso.

Response

{
  "certificate": {
    "id": "cert_abc456",
    "url": "https://ejemplo.com/pagina",
    "status": "certified",
    "verificationCode": "KP-2026-A7X9B2",
    "sha256": "a1b2c3d4e5f6...",
    "rsaSignature": "base64...",
    "timestampToken": "base64...",
    "timestampAuthority": "DigiCert TSA",
    "bitcoinTx": null,
    "screenshots": ["screenshot_001.png"],
    "createdAt": "2026-02-14T08:00:35.000Z"
  }
}

POST/api/certificates/:id/download-token

AUTH

Genera un token temporal de descarga (valido 5 minutos). Necesario para descargar el ZIP o el video de la sesion. Este mecanismo evita exponer el JWT en URLs de descarga directa.

Response

{
  "downloadToken": "dt_temp_abc123xyz..."
}

GET/api/certificates/:id/download?dt=TOKEN

AUTH

Descarga el paquete ZIP del certificado. Incluye: capturas de pantalla, manifest SHA-256, firma RSA (.sig), sello temporal RFC 3161 (.tsr), certificado PDF y metadatos JSON. Requiere un download token valido.

Response

// Respuesta binaria: application/zip
// Nombre: certificado-KP-2026-A7X9B2.zip
//
// Contenido del ZIP:
//   manifest.json
//   manifest.json.sig
//   timestamp.tsr
//   certificate.pdf
//   screenshots/
//     screenshot_001.png

GET/api/certificates/:id/video?dt=TOKEN

AUTH

Transmite el video MP4 de la sesion de captura (solo disponible para sesiones interactivas, plan Professional+). Soporta Range headers para streaming progresivo.

Response

// Respuesta binaria: video/mp4
// Content-Disposition: inline
// Accept-Ranges: bytes

Verificacion

Endpoints publicos para verificar la autenticidad de cualquier certificado. No requieren autenticacion.

GET/api/verify/:code

PUBLICO

Verifica un certificado por su codigo de verificacion (ej: KP-2026-A7X9B2). Endpoint publico, no requiere autenticacion. Devuelve el estado de validez y toda la cadena de evidencia verificable.

Response

{
  "valid": true,
  "certificate": {
    "verificationCode": "KP-2026-A7X9B2",
    "url": "https://ejemplo.com/pagina",
    "sha256": "a1b2c3d4e5f6...",
    "certifiedAt": "2026-02-14T08:00:35.000Z",
    "hasRSA": true,
    "hasTimestamp": true,
    "timestampAuthority": "DigiCert TSA",
    "hasBitcoin": false
  },
  "blockchain": {
    "anchored": false,
    "txId": null,
    "confirmations": null
  }
}

GET/api/verify/:code/ots

PUBLICO

Descarga el archivo OpenTimestamps (.ots) del certificado. Permite verificacion independiente del anclaje Bitcoin usando la herramienta ots-cli o cualquier verificador compatible.

Response

// Respuesta binaria: application/octet-stream
// Content-Disposition: attachment; filename="KP-2026-A7X9B2.ots"

API Keys

Gestiona API keys para integraciones programaticas. Disponible exclusivamente en el plan Business+.

POST/api/api-keys

AUTHBUSINESS+

Crea una nueva API key para integraciones programaticas. Las keys tienen el prefijo wpk_ y solo se muestran una vez al crearlas. Maximo 5 keys activas por cuenta.

Request body

{
  "name": "Integracion produccion"
}

Response

{
  "apiKey": {
    "id": "key_abc123",
    "name": "Integracion produccion",
    "key": "wpk_live_a1b2c3d4e5f6g7h8i9j0...",
    "createdAt": "2026-02-14T10:00:00.000Z"
  }
}

GET/api/api-keys

AUTHBUSINESS+

Lista todas las API keys del usuario. Por seguridad, la key completa no se muestra; solo los ultimos 8 caracteres.

Response

{
  "apiKeys": [
    {
      "id": "key_abc123",
      "name": "Integracion produccion",
      "lastChars": "...i9j0k1l2",
      "lastUsedAt": "2026-02-14T09:30:00.000Z",
      "createdAt": "2026-02-14T10:00:00.000Z"
    }
  ]
}

DELETE/api/api-keys/:id

AUTHBUSINESS+

Revoca permanentemente una API key. Las peticiones que usen esta key seran rechazadas inmediatamente. Esta accion no se puede deshacer.

Response

{
  "success": true
}

Certificacion por lotes

Certifica multiples paginas en una sola operacion. Disponible exclusivamente en el plan Business+.

POST/api/batch/certify

AUTHBUSINESS+

Certifica multiples URLs en una sola peticion (maximo 10 por lote). Crea sesiones estaticas para cada URL y las inicia automaticamente. Ideal para flujos de trabajo automatizados.

Request body

{
  "urls": [
    "https://ejemplo.com/pagina-1",
    "https://ejemplo.com/pagina-2",
    "https://ejemplo.com/pagina-3"
  ]
}

Response

{
  "sessions": [
    {
      "id": "ses_001",
      "targetUrl": "https://ejemplo.com/pagina-1",
      "status": "capturing"
    },
    {
      "id": "ses_002",
      "targetUrl": "https://ejemplo.com/pagina-2",
      "status": "capturing"
    },
    {
      "id": "ses_003",
      "targetUrl": "https://ejemplo.com/pagina-3",
      "status": "capturing"
    }
  ]
}

Exportacion e informes

Exporta datos y genera informes profesionales. Disponible exclusivamente en el plan Business+.

GET/api/export/certificates?format=csv|json

AUTHBUSINESS+

Exporta todos los certificados del usuario en formato CSV o JSON. Util para auditoria, informes internos o integracion con sistemas externos. El parametro format acepta "csv" o "json".

Response

// format=json
{
  "certificates": [
    {
      "id": "cert_abc456",
      "verificationCode": "KP-2026-A7X9B2",
      "url": "https://ejemplo.com/pagina",
      "sha256": "a1b2c3d4e5f6...",
      "status": "certified",
      "createdAt": "2026-02-14T08:00:35.000Z"
    }
  ],
  "exportedAt": "2026-02-14T12:00:00.000Z",
  "total": 1
}

// format=csv
// Content-Type: text/csv
// id,verificationCode,url,sha256,status,createdAt
// cert_abc456,KP-2026-A7X9B2,https://ejemplo.com/pagina,a1b2c3...,certified,2026-02-14T08:00:35.000Z

GET/api/reports/certificate/:id

AUTHBUSINESS+

Genera un informe PDF detallado del certificado. Incluye toda la cadena de evidencia, capturas de pantalla, metadatos tecnicos y un codigo QR de verificacion. Ideal para presentar como evidencia en procedimientos legales.

Response

// Respuesta binaria: application/pdf
// Content-Disposition: attachment; filename="informe-KP-2026-A7X9B2.pdf"

Usuario

Actualiza el perfil del usuario y gestiona el branding personalizado.

PUT/api/user/profile

AUTH

Actualiza el perfil del usuario autenticado. Actualmente permite modificar el nombre mostrado.

Request body

{
  "name": "Juan Garcia Lopez"
}

Response

{
  "user": {
    "id": "usr_abc123",
    "email": "usuario@ejemplo.com",
    "name": "Juan Garcia Lopez",
    "plan": "professional"
  }
}

POST/api/user/logo

AUTHBUSINESS+

Sube un logotipo personalizado para incluir en los certificados PDF. La imagen debe enviarse codificada en base64. Formatos soportados: PNG, JPG, SVG. Tamano maximo: 2 MB.

Request body

{
  "logo": "data:image/png;base64,iVBORw0KGgo..."
}

Response

{
  "logoUrl": "https://keeep.omniscius.pro/uploads/logos/usr_abc123.png"
}

DELETE/api/user/logo

AUTH

Elimina el logotipo personalizado. Los certificados futuros usaran el diseno por defecto.

Response

{
  "success": true
}

Inicio rapido

Este ejemplo muestra el flujo completo: autenticarte, crear una sesion de certificacion estatica, iniciarla, esperar a que termine y listar tus certificados.

Iniciar sesion

Obtener el token JWT para las siguientes peticiones.

curl -X POST https://keeep.omniscius.pro/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@ejemplo.com",
    "password": "miPassword123"
  }'

Crear sesion

Crear una sesion estatica con la URL a certificar.

curl -X POST https://keeep.omniscius.pro/api/sessions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://ejemplo.com/pagina",
    "sessionType": "static"
  }'

Iniciar captura

Lanzar el proceso de captura y certificacion.

curl -X POST https://keeep.omniscius.pro/api/sessions/ses_xyz789/start \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Verificar estado

Hacer polling hasta que el status sea "completed".

curl https://keeep.omniscius.pro/api/sessions/ses_xyz789 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Listar certificados

Confirmar que el certificado ha sido generado.

curl https://keeep.omniscius.pro/api/certificates \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Errores

La API utiliza codigos de estado HTTP estandar. Todos los errores devuelven un JSON con el campo error describiendo el problema.

Formato de error

{
  "error": "Descripcion del error"
}

Codigo	Nombre	Descripcion
400	Bad Request	Parametros invalidos o faltantes en la peticion.
401	Unauthorized	Token ausente, invalido o expirado.
402	Payment Required	Limite de certificaciones alcanzado en el plan actual.
403	Forbidden	No tienes permisos para este recurso o accion (ej: endpoint Business+ con plan Free).
404	Not Found	El recurso solicitado no existe o no pertenece a tu cuenta.
429	Too Many Requests	Limite de velocidad excedido. Consulta los headers X-RateLimit-*.
500	Internal Server Error	Error interno del servidor. Si persiste, contacta soporte.

Buenas practicas

→Siempre verifica el codigo de estado HTTP antes de procesar el cuerpo de la respuesta.
→Implementa reintentos con backoff exponencial para errores 429 y 500.
→Guarda el token JWT de forma segura y renovalo antes de que expire.
→Usa API keys (wpk_) en lugar de JWT para integraciones servidor-a-servidor de larga duracion.