Ir al contenido

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).

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.

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.

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.

  1. Preparar. POST /v1/events/prepare con el paso: { issuer, type, case, public, docs, actor }. Responde { event, canonical, hash, challenge }, donde event queda sobre la cabeza actual de su bitácora.

  2. Revisar y firmar. Compare event con lo que envió y luego firme los 32 bytes de hash con su llave Ed25519. Firmar solo lo que usted quiso firmar es el propósito de este paso.

  3. Enviar. POST /v1/events con { event, sig: { kind: "ed25519", signature: <base64url> } }. Responde 201 con { hash, seq, receipt, proof }. Con 409, otro paso llegó primero: prepare de nuevo sobre la cabeza que devuelve.

Ventana de terminal
# 1. Prepare
curl -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. Submit
curl -s https://api.hardstate.net/v1/events -H 'content-type: application/json' \
-d '{ "event": { … the event returned by prepare … },
"sig": { "kind": "ed25519", "signature": "…" } }'

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.

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.

  • 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 types más reducido que funcione.
  • Reintentos. 409 significa 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.