Integración con la API
El objetivo: que nadie abra una consola para registrar cada paso. Un funcionario autoriza su software una vez; a partir de ahí, el sistema de la propia institución registra cada punto de control — un expediente abierto, una inspección, una aprobación, un pago — y le entrega al ciudadano un comprobante. Escribir no requiere API key: un evento solo se acepta si extiende la HardState Log de su institución y lo firma una llave que esa bitácora autoriza.
Todo lo que sigue usa la API pública en https://api.hardstate.net (http://localhost:8787 cuando se corre en local).
1. Elija quién firma
Sección titulada «1. Elija quién firma»| Quién firma | Cuándo usarlo | Cómo se autoriza | Se atribuye a |
|---|---|---|---|
Sesión de una persona (role: session) |
Un equipo, una tableta o una app de campo durante el turno de alguien | La persona la aprueba una vez con su llave de acceso (session.open); vence (≤ 30 días) |
Esa persona, por su nombre |
Llave de sistema (role: system) |
Un proceso sin una persona detrás: una pasarela de pago, un sistema de citas, un escáner | Un administrador la registra una vez (key.add), con alcance a algunos tipos de paso |
El sistema, por su nombre |
| Llave de acceso, paso a paso | Poco volumen, o actos de alto impacto firmados en persona | Ya registrada en la bitácora de la institución | Esa persona |
Prefiera las sesiones para todo aquello de lo que responde una persona: la responsabilidad sigue siendo personal, y un
dispositivo perdido se cierra con un clic. Use llaves de sistema solo para pasos que no realiza ninguna persona, y
siempre con alcance ("types": ["fee.paid"]). Vea Funcionarios y sesiones para saber cómo se crean.
2. Los tipos de evento son suyos
Sección titulada «2. Los tipos de evento son suyos»Cada paso es un evento del tipo que usted elija, escrito domain.action en minúsculas: case.open, case.inspect,
permit.approve, permit.deny, fee.paid, diploma.issue, aid.delivered, contract.award,
land_title.transfer. El protocolo solo reserva issuer.*, key.* y session.*. Use un tipo por cada clase de
acto, ponga los datos públicos del acto en public y use case para el número de expediente o de trámite, para que
todo el trámite de un ciudadano se lea como una sola línea de tiempo.
3. Autorice su software (una vez)
Sección titulada «3. Autorice su software (una vez)»Su software genera su propio par de llaves Ed25519 y guarda la llave privada: un archivo con permisos 0600 o, mejor,
un HSM o un KMS en la nube. Después pide que lo autoricen con un enlace de solicitud:
https://app.hardstate.net/console?device=<base64url(JSON)>
JSON = { "v": 1, "label": "Permits system — City Hall", "publicKey": "<SPKI DER, base64url>", "types": ["case.*", "permit.*"] }Abra el enlace con la sesión iniciada en la consola (Dispositivos y sesiones):
- un funcionario lo aprueba como su sesión, por el tiempo que elija; o
- un administrador lo registra como llave de sistema, válida hasta que se revoque.
El id de llave que su software usa como actor es:
actor = "ed25519:" + hex(SHA-256(spki))[0:32]4. Registre cada punto de control: preparar → firmar → enviar
Sección titulada «4. Registre cada punto de control: preparar → firmar → enviar»Puede integrarse cualquier lenguaje que pueda hacer una petición HTTP y una firma Ed25519. No hace falta una biblioteca de JSON canónico: la API le prepara el evento exacto.
-
Preparar.
POST /v1/events/preparecon el paso:{ issuer, type, case, public, docs, actor }. Responde{ event, canonical, hash, challenge }, dondeeventqueda sobre la cabeza actual de su bitácora. -
Revisar y firmar. Compare
eventcon lo que envió y luego firme los 32 bytes dehashcon su llave Ed25519. Firmar solo lo que usted quiso firmar es el propósito de este paso. -
Enviar.
POST /v1/eventscon{ event, sig: { kind: "ed25519", signature: <base64url> } }. Responde201con{ hash, seq, receipt, proof }. Con409, otro paso llegó primero: prepare de nuevo sobre la cabeza que devuelve.
# 1. Preparecurl -s https://api.hardstate.net/v1/events/prepare -H 'content-type: application/json' -d '{ "issuer": "city-of-esperanza", "type": "permit.approve", "case": "BP-2026-0042", "public": { "decision": "approved", "validUntil": "2027-10-20" }, "actor": "ed25519:4be1…"}'
# 2. Sign the returned .hash (32 bytes) with your Ed25519 key, then:
# 3. Submitcurl -s https://api.hardstate.net/v1/events -H 'content-type: application/json' \ -d '{ "event": { … the event returned by prepare … }, "sig": { "kind": "ed25519", "signature": "…" } }'import base64, hashlib, json, urllib.requestfrom cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKeyfrom cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
API = "https://api.hardstate.net"b64url = lambda b: base64.urlsafe_b64encode(b).rstrip(b"=").decode()
def post(path, body): req = urllib.request.Request(API + path, json.dumps(body).encode(), {"content-type": "application/json"}) with urllib.request.urlopen(req) as r: return json.load(r)
key = Ed25519PrivateKey.generate() # load yours from a protected file, HSM, or KMSspki = key.public_key().public_bytes(Encoding.DER, PublicFormat.SubjectPublicKeyInfo)actor = "ed25519:" + hashlib.sha256(spki).hexdigest()[:32]
def record(issuer, type_, case, public, docs=()): p = post("/v1/events/prepare", {"issuer": issuer, "type": type_, "case": case, "public": public, "docs": list(docs), "actor": actor}) assert p["event"]["type"] == type_ and p["event"]["public"] == public # sign only what you meant sig = key.sign(bytes.fromhex(p["hash"])) return post("/v1/events", {"event": p["event"], "sig": {"kind": "ed25519", "signature": b64url(sig)}})
r = record("city-of-esperanza", "permit.approve", "BP-2026-0042", {"decision": "approved"})print(r["receipt"]) # put this link (and its QR) in the notification you already send the citizenconst API = "https://api.hardstate.net";const b64url = (b: ArrayBuffer) => Buffer.from(b).toString("base64url");const post = async (path: string, body: unknown) => (await fetch(API + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) })).json();
// Your Ed25519 key (load yours from a protected file, HSM, or KMS).const { privateKey, publicKey } = await crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]) as CryptoKeyPair;const spki = await crypto.subtle.exportKey("spki", publicKey);const actor = "ed25519:" + Buffer.from(await crypto.subtle.digest("SHA-256", spki)).toString("hex").slice(0, 32);
async function record(issuer: string, type: string, kase: string, pub: Record<string, unknown>) { const p = await post("/v1/events/prepare", { issuer, type, case: kase, public: pub, docs: [], actor }); if (p.event.type !== type) throw new Error("sign only what you meant"); const sig = await crypto.subtle.sign({ name: "Ed25519" }, privateKey, Buffer.from(p.hash, "hex")); return post("/v1/events", { event: p.event, sig: { kind: "ed25519", signature: b64url(sig) } });}
const r = await record("city-of-esperanza", "permit.approve", "BP-2026-0042", { decision: "approved" });console.log(r.receipt);5. Los documentos siguen siendo privados
Sección titulada «5. Los documentos siguen siendo privados»Nunca envíe documentos a HardState, salvo que la institución decida publicarlos. En su lugar, comprométase con cada archivo:
digest = SHA-256(file)salt = 32 random bytes (keep it: it goes in the citizen's receipt)commitment = SHA-256("hardstate/doc/v1" ‖ salt ‖ digest)docs = [{ "label": "Inspection report", "commitment": hex(commitment), "mime": "application/pdf" }]Entréguele al ciudadano el enlace del comprobante con las sales en su fragmento:
<receipt>#k=<commitment[0:16]>.<salt hex>,…. El fragmento nunca llega a ningún servidor; con él, cualquiera que
tenga el archivo puede comprobar que es el registrado. Para publicar un documento a propósito, envíe
publish: [{ commitment, digest, salt }] con el evento y luego PUT /v1/docs/<commitment> con los bytes del archivo.
6. Comprobantes para los ciudadanos
Sección titulada «6. Comprobantes para los ciudadanos»POST /v1/events devuelve un enlace receipt (https://app.hardstate.net/r/<hash>). Agregue el fragmento #k=…
cuando el paso tenga documentos, y ponga el enlace y su QR en lo que el ciudadano ya recibe: correo, SMS, el formato
impreso. Cada paso del expediente enlaza a la línea de tiempo completa, y cualquiera puede verificarlo
contra Bitcoin.
7. Operación
Sección titulada «7. Operación»- Custodia. Las llaves privadas de sistema y de sesión nunca salen de la máquina que las usa (
0600, HSM o KMS). - Alcance. Dele a cada llave el conjunto de
typesmás reducido que funcione. - Reintentos.
409significa que la cabeza de la bitácora se movió: prepare de nuevo. Ante errores de red, es seguro reintentar con el mismo evento firmado: un duplicado se rechaza, no se registra dos veces. - Ritmo. Los registros llegan a Bitcoin en 1–3 horas mediante OpenTimestamps (gratis) y en la HardState Anchor diaria. El anclaje exprés (~10–20 min) está disponible en los planes institucionales.
HardState es una empresa de Zevlat Intelligence. © 2026 Zevlat Intelligence.