Proovik
Certificar
REST · JSON · sin host aparte

API de Proovik

Demuestra que tu documento ya existía en una fecha y hora concretas, desde tu propio código. Es la misma API que usa esta web: los endpoints de esta página existen hoy y responden en producción.

URL base https://proovik.com/api

Autenticación · Cabecera Authorization: Bearer TU_API_KEY en los endpoints marcados con «clave». Los marcados «público» no necesitan clave.

Cómo se obtiene la API key hoy

Todavía no es autoservicio. La clave la activa Proovik a mano para tu cuenta y, una vez activada, aparece en tu panel, en la sección API. Una sola clave sirve para certificación y trazabilidad.

  1. Crea una cuenta (gratis).
  2. Pide la activación de la API desde el formulario de contacto, asunto «API», indicando el email de tu cuenta y para qué la vas a usar.
  3. Cuando esté activa, copia la clave desde el panel. Si aún no aparece, la solicitud no se ha procesado: no hay otra vía.
Solicitar activación Ver mi panel

Certificación de documentos

Anclaje del SHA-256 de un fichero en la cadena de Kaspa

El documento nunca se envía: calculas su SHA-256 en tu sistema y mandas solo el hash (64 caracteres hexadecimales).

POST/api/certifyclaveCertificar un hash

Registra el hash en la cadena. Consume un crédito de tu cuenta. Si el mismo hash ya estaba certificado, devuelve el registro existente (already_exists: true) sin consumir nada.

Petición
curl -X POST https://proovik.com/api/certify \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "description": "Contrato v2.1"
  }'
Respuesta · 200 · confirmada
{
  "success": true,
  "status": "success",
  "confirmed": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "explorer_url": "https://explorer.kaspa.org/txs/b173e1ff…802889",
  "timestamp": "2026-01-12 20:48:30",
  "credit_consumed": true,
  "certificate_url": "/api/certificate?hash=e3b0c442…&t=…"
}
202 · enviada y pendiente. La transacción ya está emitida pero aún no es visible: vuelve a enviar el mismo hash pasados unos segundos para obtener el estado final (no hay webhook que te avise).

Errores: 400 invalid_hash · 401 invalid_api_key · 401 identification_required (sin clave: el endpoint queda reservado al formulario web) · 429 no_credits · 502 notary_failed (nada se cobra).

GET/api/verify?hash={sha256}públicoConsultar si un hash está certificado

Cualquiera puede consultarlo, sin clave. Solo devuelve certificaciones confirmadas en la cadena.

Petición
curl "https://proovik.com/api/verify?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Respuesta
{
  "success": true,
  "exists": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "explorer_url": "https://explorer.kaspa.org/txs/b173e1ff…802889",
  "timestamp": "2026-01-12 20:48:30",
  "has_merkle_proof": true
}
// {"success": true, "exists": false}  si no está certificado
GET/api/certificate?hash={sha256}&t={token}públicoDescargar el certificado PDF

La respuesta de /api/certify incluye certificate_url: un enlace firmado (parámetro t) que muestra también tus metadatos privados. Sin t el mismo endpoint sirve la versión pública del certificado a cualquiera. El PDF lleva adjunto el paquete de prueba PVK-PROOF/1, que se puede verificar sin Proovik.

Petición
curl -o certificado.pdf \
  "https://proovik.com/api/certificate?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Errores: 404 not_found · 409 certification_pending (JSON, no PDF: aún no hay certificado) · 429 rate_limited (60 descargas por hora e IP).

GET/api/certify/proof?hash={sha256}clavePrueba Merkle de una certificación

Devuelve la ruta Merkle y la raíz anclada de una certificación hecha con tu clave. Las de otras cuentas responden 404.

Petición
curl "https://proovik.com/api/certify/proof?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "Authorization: Bearer TU_API_KEY"
Respuesta
{
  "success": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "status": "success",
  "txid": "b173e1ff…802889",
  "anchored": true,
  "merkle_root": "d4735e3a…13ab35",
  "merkle_proof": [ { "hash": "…", "position": "left" }, … ]
}

Trazabilidad de lotes

Lotes y eventos encadenados por hash y anclados por lotes Merkle

Cada evento enlaza con el hash del anterior; el primero enlaza con el hash del lote. Los registros se anclan a la cadena de Kaspa en ciclos de unos minutos: el estado pasa de pending a confirmed sin que tengas que hacer nada. Identificadores GS1 (GTIN, SGTIN, GLN) validados con dígito de control.

POST/api/trace/batchclaveCrear un lote

Obligatorio: product_name. Opcionales: batch_id (si no, se genera), gtin, sgtin (único en todo el sistema; repetido responde 409), origin, origin_gln, origin_lat/origin_lng, quantity, quantity_unit, metadata. Admite cabecera Idempotency-Key.

Petición
curl -X POST https://proovik.com/api/trace/batch \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Aceite de oliva virgen extra 500 ml",
    "gtin": "8412345678905",
    "origin": "Jaén",
    "quantity": 5000,
    "quantity_unit": "bottles",
    "metadata": { "variety": "Picual", "harvest_year": 2025 }
  }'
Respuesta · 201
{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "payload_hash": "7f83b165…6d9069",
  "created_at": "2026-09-05T10:00:00+00:00"
}
POST/api/trace/eventclaveAñadir un evento

Obligatorios: batch_id y event_type, uno de COMMISSION, OBSERVE, TRANSFORM, SHIP, RECEIVE, AGGREGATE, DISAGGREGATE, CUSTOM. Opcionales: location {name, gln, lat, lng}, actor {name, id, role}, data, evidence_hash, gs1_bizstep.

Petición
curl -X POST https://proovik.com/api/trace/event \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_id": "BATCH-20260905-A1B2C3D4",
    "event_type": "SHIP",
    "location": { "name": "Almacén central", "gln": "8412345000010" },
    "data": { "carrier": "Transportes Sur", "pallets": 12 }
  }'
Respuesta · 201
{
  "success": true,
  "event_id": 17,
  "sequence": 3,
  "event_hash": "e3b0c442…52b855",
  "prev_event_hash": "9f86d081…00a08",
  "status": "pending"
}
GET/api/trace/batch/{batch_id}clave opcionalLeer un lote con sus eventos

Sin clave devuelve la vista pública del lote; con tu clave, los datos completos de tus propios lotes.

Petición
curl "https://proovik.com/api/trace/batch/BATCH-20260905-A1B2C3D4" \
  -H "Authorization: Bearer TU_API_KEY"
GET/api/trace/verify/{batch_id}clave opcionalVerificar la integridad de un lote

Recalcula el hash del lote, la cadena de eventos y las pruebas Merkle contra lo anclado. overall_valid solo es true si todo cuadra; fully_verified exige además que todos los eventos estén confirmados.

Petición
curl "https://proovik.com/api/trace/verify/BATCH-20260905-A1B2C3D4"
Respuesta
{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "verification": {
    "overall_valid": true,
    "batch_integrity": { "valid": true, … },
    "chain_integrity": { "valid": true, … },
    "fully_verified": true
  }
}

También existen, con clave: GET /api/trace/search?gtin=|sgtin=|lot=|product=, GET /api/trace/event/{event_id}, GET /api/trace/event/{event_id}/proof, GET /api/trace/batch/{batch_id}/proof y GET /api/trace/batch/{batch_id}/qr. Detalle en la referencia completa.

Límites por clave: 60 escrituras y 300 lecturas por minuto. Al superarlos responde 429 con Retry-After.

Verificación independiente (PVK-PROOF/1)

Comprobar una prueba sin fiarse de Proovik

El verificador recalcula los cuatro eslabones de la prueba: el hash del documento está en la transacción, la transacción está en el árbol Merkle del bloque, la cabecera reproduce el hash del bloque y esa cabecera tiene una prueba de trabajo válida. El hash del documento lo aportas tú siempre: nunca se lee del paquete. Tres veredictos: VALIDO, INCOMPLETO (no se pudo determinar; nunca cuenta como válido) e INVALIDO.

POST/api/verify/proofpúblicoVerificar un paquete de prueba

Envía el fichero .pvkproof.json (el que va adjunto al PDF) o el paquete en JSON, junto con el SHA-256 de tu copia del documento. No consulta la red: verifica lo que le das. Sin clave.

Petición
curl -X POST https://proovik.com/api/verify/proof \
  -F "hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -F "[email protected]"
Respuesta
{
  "spec": "PVK-PROOF/1",
  "modo": "paquete",
  "documento_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "resultado": "VALIDO",
  "valido": true,
  "completo": true,
  "eslabones": [
    { "n": 1, "estado": "OK", … },
    { "n": 2, "estado": "OK", … },
    { "n": 3, "estado": "OK", … },
    { "n": 4, "estado": "OK", … }
  ],
  "algoritmo": { … }
}
GET/api/verify/proof/{txid}?hash={sha256}públicoReconstruir y verificar desde la cadena

Solo con el txid y el hash, reconstruye el paquete consultando la red de Kaspa. La cabecera completa del bloque solo está disponible unas 40 horas: pasado ese plazo los eslabones 3 y 4 quedan INCOMPLETO. Sin clave; con CORS abierto; 30 peticiones por hora e IP.

Petición
curl "https://proovik.com/api/verify/proof/b173e1ff9d73e09b51db78b9050a4be578f232f3d5e106a214950a8265802889?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Especificación y verificador en línea

Lo que esta API no tiene (todavía)

  • Webhooks salientes. Nada te avisa cuando una transacción se confirma. Para certificaciones, reenvía el mismo hash a POST /api/certify o consulta GET /api/verify?hash=; para trazabilidad, consulta GET /api/trace/verify/{batch_id}.
  • SDKs. No hay librerías oficiales en ningún lenguaje. Es HTTP y JSON: cualquier cliente HTTP vale.
  • Fichero OpenAPI. La referencia de campos y respuestas está en la documentación técnica enlazada abajo.
  • Claves autoservicio, varias claves o ámbitos. Una clave por cuenta, activada a mano.
  • Entorno de pruebas. Cada certificación real consume un crédito. Para probar sin gastar, usa los endpoints públicos de consulta y verificación.
PVK-PROOF/1

Referencia completa y verificador

La documentación técnica describe todos los campos y respuestas (por ahora solo en español). El verificador en línea comprueba cualquier certificado sin cuenta.

Documentación técnica Verificador en línea Solicitar API key