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

# 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 |