Archive: System v4 - Estado al 2024-12-24

v4-archive/contratos-comunes/docs/HST_API.md

@@ -0,0 +1,156 @@
+# HST API v2.0
+
+**Servidor:** https://tzrtech.org
+**Estado:** Producción
+**Última actualización:** 2025-12-18
+
+---
+
+## Estadísticas
+
+| Tabla | Registros | Descripción |
+|-------|-----------|-------------|
+| hst   | 658       | Etiquetas del sistema |
+| spe   | 145       | Especialidades |
+| flg   | 65        | Flags |
+| vsn   | 84        | Versiones |
+| vue   | 21        | Vistas |
+| **Total** | **973** | Todas con h_maestro |
+
+---
+
+## Sistema Dual de Hashes
+
+```
+h_maestro = SHA256(grupo || ':' || ref)
+    → Identidad SEMÁNTICA (determinista)
+    → Ejemplo: SHA256("hst:abk") = "335350bb41a329c..."
+
+mrf = SHA256(bytes_imagen)
+    → Identidad de ARCHIVO
+    → URL: https://tzrtech.org/{mrf}.png
+```
+
+---
+
+## Endpoints
+
+### Dump completo
+```
+GET https://tzrtech.org/api/index.json
+```
+
+Retorna array con todos los tags.
+
+### Tag por h_maestro
+```
+GET https://tzrtech.org/api/tags/{h_maestro}
+```
+
+Ejemplo:
+```bash
+curl https://tzrtech.org/api/tags/335350bb41a329c31acac43197232850bc6828ec76650291ce230446e520774f
+```
+
+### Búsqueda y filtro
+```
+GET https://tzrtech.org/api/tags?grupo={grupo}
+GET https://tzrtech.org/api/tags?q={query}
+GET https://tzrtech.org/api/tags?grupo={grupo}&q={query}
+```
+
+Ejemplos:
+```bash
+# Todas las etiquetas hst
+curl "https://tzrtech.org/api/tags?grupo=hst"
+
+# Buscar "finanzas"
+curl "https://tzrtech.org/api/tags?q=finanzas"
+
+# Buscar "yoga" en vsn
+curl "https://tzrtech.org/api/tags?grupo=vsn&q=yoga"
+```
+
+---
+
+## Formato de Respuesta
+
+```json
+{
+  "ref": "abk",
+  "h_maestro": "335350bb41a329c31acac43197232850bc6828ec76650291ce230446e520774f",
+  "mrf": "ed456cb46151edb46106863d16b4e4cade7af8e33d8c7cae8489125aee76ffa7",
+  "nombre_es": "audiolibro",
+  "nombre_en": "audiobook",
+  "grupo": "hst",
+  "imagen_url": "https://tzrtech.org/ed456cb46151edb46106863d16b4e4cade7af8e33d8c7cae8489125aee76ffa7.png"
+}
+```
+
+---
+
+## Uso desde DECK
+
+```python
+import requests
+
+# Obtener tag por h_maestro
+def get_tag(h_maestro: str) -> dict:
+    response = requests.get(f"https://tzrtech.org/api/tags/{h_maestro}")
+    return response.json()
+
+# Buscar tags por grupo
+def search_tags(grupo: str = None, query: str = None) -> list:
+    params = {}
+    if grupo:
+        params["grupo"] = grupo
+    if query:
+        params["q"] = query
+    response = requests.get("https://tzrtech.org/api/tags", params=params)
+    return response.json()
+
+# Calcular h_maestro localmente (para verificación)
+import hashlib
+
+def calculate_h_maestro(grupo: str, ref: str) -> str:
+    return hashlib.sha256(f"{grupo}:{ref}".encode()).hexdigest()
+```
+
+---
+
+## Uso en S-CONTRACT
+
+```json
+{
+  "context": {
+    "tags": {
+      "hst": ["335350bb41a329c...", "a7b3c9d4e5f6..."],
+      "hsu": [],
+      "emp": ["empresa_h_maestro..."],
+      "pjt": ["proyecto_h_maestro..."]
+    }
+  }
+}
+```
+
+---
+
+## Subdominios Semánticos
+
+Las imágenes también son accesibles via subdominio:
+
+```
+https://hst_finanzas.tzrtech.org → redirect → /{mrf}.png
+https://spe_aluminio.tzrtech.org → redirect → /{mrf}.png
+```
+
+Formato: `{grupo}_{ref_normalizado}.tzrtech.org`
+
+---
+
+## Historial
+
+| Versión | Fecha | Cambios |
+|---------|-------|---------|
+| 1.0 | 2025-12 | MVP imágenes con mrf |
+| 2.0 | 2025-12-18 | Añadido h_maestro, API endpoints, limpieza duplicados |