Para desarrolladores

API pública de verificación

Toda credencial de OpenChapitas es verificable por terceros sin necesitar cuenta ni depender de que este servidor exista — resolviendo el did:web del emisor y comprobando la firma híbrida (Ed25519 + ML-DSA-65) directamente. Estos son los endpoints públicos y los webhooks para integrar tus propios sistemas.

Verificación

GET/.well-known/did.json

Documento DID del emisor — claves públicas Ed25519 (con histórico de versiones) y ML-DSA-65.

curl https://openchapitas.org/.well-known/did.json

POST/api/verify

Verifica una credencial firmada (JSON completo en el body). Devuelve validez de cada prueba, si es post-cuántica, y si está vigente/revocada.

curl -X POST https://openchapitas.org/api/verify \
  -H "Content-Type: application/json" \
  -d '{"credential": <VC firmada>}'

GET/api/credentials/{id}

Credencial firmada en JSON-LD (con Accept: application/vc+ld+json) o página pública HTML.

curl https://openchapitas.org/api/credentials/{id} \
  -H "Accept: application/vc+ld+json"

GET/status/list-1

BitstringStatusList firmada — estado de revocación de todas las credenciales, comprobable offline.

curl https://openchapitas.org/status/list-1

Datos públicos

GET/api/public/stats

Conteos agregados sin PII: credenciales vigentes y nº de emisores.

GET/api/public/orgs

Directorio de organizaciones emisoras con vitrina pública.

GET/api/public/org/{slug}

Perfil de una organización + las insignias que otorga.

Webhooks

Configurables desde tu consola. Cada entrega llega firmada con HMAC-SHA256 (secreto propio de cada webhook). La firma en X-OpenChapitas-Signature (formato sha256=<hex>) cubre timestamp.body, donde el timestamp viaja en X-OpenChapitas-Timestamp. Rechaza la entrega si el timestamp queda fuera de una tolerancia (p.ej. 5 min) para evitar reenvíos (replay), y usa X-OpenChapitas-Id para descartar entregas duplicadas (idempotencia).

POSTcredential.issue

Se dispara al emitir una credencial.

{"event":"credential.issue","credential_id":"...","achievement_id":"...","status":"valid","url":"https://openchapitas.org/credentials/..."}

POSTcredential.revoke

Se dispara al revocar una credencial.

{"event":"credential.revoke","credential_id":"...","reason":"...","url":"https://openchapitas.org/credentials/..."}

Verificación de firma (Node/Python — cualquier librería HMAC-SHA256 estándar sirve):

# Python — rechaza (no uses assert en producción: -O lo elimina)
import time, hmac, hashlib

ts  = request.headers["X-OpenChapitas-Timestamp"]
sig = request.headers["X-OpenChapitas-Signature"]

# 1) frescura: descarta reenvíos fuera de la tolerancia (anti-replay)
if abs(time.time() - int(ts)) > 300:
    return Response(status=401)

# 2) firma sobre timestamp.body, comparación en tiempo constante
signed   = ts.encode() + b"." + body_raw_bytes
expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, sig):
    return Response(status=401)

# 3) idempotencia: ignora si ya procesaste este id
if seen(request.headers["X-OpenChapitas-Id"]):
    return Response(status=200)

¿Necesitas algo que no está aquí? La API es de solo lectura para verificación pública — la emisión requiere una API key de tu organización (Bearer token), disponible desde la consola.