Transparencia

El portal de transparencia es la página pública donde el colegio informa, letra por letra del Art. 14 ter, qué datos trata y para qué. Su contenido combina secciones redactadas por el colegio con bloques de datos que se derivan automáticamente del RAT, y cada publicación acuña una versión sellada con checksum — la prueba de qué decía el portal en qué momento. Con una API key el dominio es de lectura (transparency.read); la edición y la publicación son de consola.

El portal público de cada colegio vive en https://app.edugoverna.com/transparencia/:slug, y su contenido JSON se sirve sin autenticación en GET /public/transparency/:slug (con su PDF en …/pdf).

GET/api/transparency/portal

Estado del portal

Requiere transparency.read. La foto completa del portal: configuración, secciones con su letra del artículo, advertencias de publicación (avisan, nunca bloquean), cobertura y el sello de la última versión publicada.

Claves de la respuesta

Nombre
portal
Tipo
object
Descripción
slug, enabled, contactos y si enlaza los portales ARCO y de consentimiento (arcoPortalLinked, consentPortalLinked).
Nombre
sections
Tipo
array
Descripción
Cada sección con sectionKey, letter (a–l o null), title, enabled, position, su cuerpo enriquecido y la guía del catálogo (guidance, required). El cuerpo de la sección con letter: "a" es el texto de la política de tratamiento vigente, no un texto aparte; vacío si aún no hay una aprobada.
Nombre
policy
Tipo
object | null
Descripción
{ title, versionNumber, effectiveFrom, publishedAt } de la política vigente de la que sale la letra a); null si no hay ninguna.
Nombre
warnings
Tipo
array
Descripción
{ letter, sectionKey, message } — lo que faltaría para cubrir el artículo.
Nombre
coverage
Tipo
object
Descripción
{ answered, total }.
Nombre
published
Tipo
object | null
Descripción
{ versionId, versionNumber, publishedAt, checksum, catalogVersion } de la última publicación; null si nunca se publicó.
Nombre
stale
Tipo
boolean
Descripción
true cuando hay cambios sin publicar respecto de la última versión.

Solicitud

GET

/api/transparency/portal

curl "https://app.edugoverna.com/api/transparency/portal" \
  -H "x-api-key: {tu_api_key}"

Respuesta (recortada)

{
  "policy": { "title": "Política de protección de datos", "versionNumber": 2 },
  "portal": {
    "slug": "colegio-andes",
    "enabled": true,
    "contactEmail": "privacidad@colegioandes.cl",
    "arcoPortalLinked": true,
    "consentPortalLinked": true
  },
  "sections": [
    {
      "sectionKey": "finalidades",
      "letter": "b",
      "title": "Para qué usamos los datos",
      "enabled": true,
      "position": 2,
      "required": true
    }
  ],
  "warnings": [],
  "coverage": { "answered": 12, "total": 12 },
  "published": {
    "versionId": "tv07…",
    "versionNumber": 7,
    "publishedAt": "2026-08-01T13:00:00.000Z",
    "checksum": "5d8c…",
    "catalogVersion": "eg-2026.08"
  },
  "stale": false
}

GET/api/transparency/blocks

Bloques de datos

Requiere transparency.read. Los bloques son tablas que el portal materializa desde el RAT y la gobernanza — el colegio no las redacta, se derivan: categorias, universo, finalidades, destinatarios, encargados, transferencias, retencion, medidas, decisiones_automatizadas, fuentes.

GET /transparency/blocks lista el resumen; GET /transparency/blocks/:blockKind resuelve uno con sus columnas y filas (un tipo desconocido responde 404 TRANSPARENCY_BLOCK_UNKNOWN).

Solicitud

GET

/api/transparency/blocks/finalidades

curl "https://app.edugoverna.com/api/transparency/blocks/finalidades" \
  -H "x-api-key: {tu_api_key}"

Respuesta (recortada)

{
  "block": {
    "blockKind": "finalidades",
    "columns": ["Actividad", "Finalidad", "Base de licitud"],
    "rows": [
      ["Comunicaciones académicas", "Informar y coordinar…", "Consentimiento"]
    ]
  }
}

GET/api/transparency/versions

Versiones publicadas

Requiere transparency.read. El historial sellado del portal, hasta 50 versiones en orden descendente. Cada versión guarda el documento resuelto completo (con los bloques ya materializados al momento de publicar), su checksum SHA-256 — el mismo que se imprime al pie del portal público — y el PDF archivado (documentArtifactId).

GET /transparency/versions/:versionId agrega el campo document con la página completa tal como se publicó.

Solicitud

GET

/api/transparency/versions

curl "https://app.edugoverna.com/api/transparency/versions" \
  -H "x-api-key: {tu_api_key}"

Respuesta (recortada)

{
  "versions": [
    {
      "id": "tv07…",
      "versionNumber": 7,
      "checksum": "5d8c…",
      "catalogVersion": "eg-2026.08",
      "warnedLetters": [],
      "notes": "Actualiza destinatarios tras nuevo LMS",
      "publishedAt": "2026-08-01T13:00:00.000Z",
      "publishedByUserId": "usr_…",
      "documentArtifactId": "ar91…"
    }
  ]
}

Política de privacidad y edición

GET /transparency/policy (con transparency.read) devuelve { policy, approvalPending }: la política vigente —la última versión aprobada y publicada— o null si la propuesta aún espera su aprobación a cuatro ojos. La letra a) de la página pública muestra el texto de esa política; aprobarla no cambia la página ya publicada, aparece al publicar una nueva versión. GET /transparency/preview arma el documento completo con los datos de hoy, sin publicarlo.

La edición es de consola:

Método y ruta	Permiso	Qué hace
`PUT /transparency/portal`	`transparency.write`	Configura el portal. Sólo sesión.
`POST /transparency/sections` · `PATCH /transparency/sections/:sectionId` · `PATCH /transparency/sections/reorder` · `DELETE` · `POST …/:sectionId/draft`	`transparency.write`	Redacción de secciones; el cuerpo de la letra a) se rechaza con `409 TRANSPARENCY_SECTION_FROM_POLICY` (se edita en la política). Sólo sesión.
`PUT /transparency/policy`	`schools.write`	Propone la política; queda `approvalPending` hasta que otra persona apruebe. Sólo sesión.
`POST /transparency/publish`	`transparency.publish`	Acuña la versión sellada: responde `{ published: { versionId, versionNumber, checksum, publishedAt, warnedLetters, documentArtifactId } }`. Sólo sesión — publicar exige una persona identificable.

PATCH/api/branding/color

Marca del colegio

El color y el logo tiñen los portales públicos (transparencia, ARCO, consentimiento). Ambas rutas aceptan API key con schools.write y quedan auditadas.

PATCH /branding/color — cuerpo { "color": "#RRGGBB" } (hex de 6 dígitos) o { "color": null } para limpiar. Responde { ok, brandColor }.
POST /branding/logo — multipart/form-data, campo file, PNG o JPEG. Responde { url, artifactId, contentType, sizeBytes }; la url es pública y versionada por checksum.
DELETE /branding/logo — responde { ok, removed }.

Solicitud

PATCH

/api/branding/color

curl -X PATCH "https://app.edugoverna.com/api/branding/color" \
  -H "x-api-key: {tu_api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "color": "#D64545" }'

Respuesta

{ "ok": true, "brandColor": "#D64545" }

GET/api/organization/portal-domains

Dominios propios

Sirve los portales públicos bajo el dominio del colegio (transparencia.colegio.cl, denuncias.colegio.cl). El portal debe existir antes de conectarle un dominio: un canal apagado responde 422 PORTAL_DOMAIN_SURFACE_NOT_READY. Requiere el módulo custom_domains del plan; lectura con schools.read, escrituras con schools.write.

Cada dominio indica su surface (arco, transparency o convivencia, el canal de denuncias), su status (pending_dns → pending_certificate → active; sólo active enruta) y los dnsRecords exactos que el colegio debe crear. La lectura trae también surfaces: los portales que existen (surface, slug, canonicalPath), que son los únicos a los que se les puede conectar un dominio. En despliegues sin dominios configurados la respuesta es inerte: { available: false, domains: [], cnameTarget: null }.

Método y ruta	Qué hace
`POST /organization/portal-domains`	Registra `{ hostname, surface }`.
`POST …/:portalDomainId/check`	Re-verifica DNS y certificado. Devuelve además `observations`: por cada registro, `expected`, `found` y `state` (`ok` · `missing` · `appended_zone` · `mismatch` · `unknown`).
`PATCH …/:portalDomainId`	`{ redirectLegacyPath }`.
`DELETE …/:portalDomainId`	Elimina el dominio.

Solicitud

GET

/api/organization/portal-domains

curl "https://app.edugoverna.com/api/organization/portal-domains" \
  -H "x-api-key: {tu_api_key}"

Respuesta (recortada)

{
  "available": true,
  "cnameTarget": "portales.edugoverna.com",
  "domains": [
    {
      "id": "pd3f…",
      "hostname": "transparencia.colegioandes.cl",
      "surface": "transparency",
      "status": "active",
      "statusMessage": null,
      "redirectLegacyPath": true,
      "dnsRecords": [
        {
          "type": "CNAME",
          "name": "transparencia",
          "absoluteName": "transparencia.colegioandes.cl",
          "value": "portales.edugoverna.com",
          "purpose": "routing"
        }
      ],
      "verifiedAt": "2026-08-02T15:30:00.000Z"
    }
  ]
}