Actividades de tratamiento

Una actividad de tratamiento describe, en el registro de actividades de tratamiento (RAT), un uso concreto de datos personales: su finalidad, base de licitud, categorías de datos y destinatarios. Es también el aviso que el titular lee al consentir — por eso está versionada y sellada: cada versión lleva un checksum de su contenido y, una vez publicada, es inmutable. En esta página revisamos los endpoints para declarar tus actividades como encargado, componer sus versiones y publicarlas.

Todas las rutas de esta página cuelgan de la URL base https://app.edugoverna.com/api/partner/v1/organizations/:organizationId. Las versiones publicadas son las que referencian los endpoints de Consentimientos y de Campañas compartidas.

El modelo de versionado

El flujo típico tiene tres pasos:

Crear la actividad (POST /processing-activities) crea la actividad con su versión 1 en borrador (versionStatus: "draft").
Componer el borrador: adjuntar categorías de datos y destinatarios a esa versión mientras siga en borrador. Una versión publicada rechaza estas escrituras con 409 PROCESSING_ACTIVITY_VERSION_PUBLISHED — su contenido es lo que los titulares leyeron.
Publicar (POST .../publish) sella la versión, promueve la actividad de draft a active y la deja disponible para pedir consentimientos.

Para modificar una actividad ya publicada se crea una versión nueva (POST .../versions), que nace ya publicada, hereda las declaraciones de la versión anterior salvo que se sobrescriban y — por defecto — invalida los consentimientos vigentes de las versiones previas, disparando su recaptura. Es la mecánica que garantiza que ningún consentimiento siga vivo sobre un aviso que ya no describe el tratamiento real.

GET/v1/organizations/:organizationId/processing-activities

Listar actividades de tratamiento

Devuelve una página de actividades de la organización, de la más reciente a la más antigua, cada una con su versión vigente (currentVersion) y su política de retención.

Permiso requerido: partner.processing_activities.read · Alcance de conexión: processing_activities:read.

Parámetros de consulta opcionales

Nombre
limit
Tipo
integer
Descripción
Tamaño de página. Por defecto 100, máximo 250.
Nombre
cursor
Tipo
string
Descripción
Cursor de la página anterior (meta.nextCursor). Ver Paginación.

Request

GET

/v1/.../processing-activities

curl -G https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/processing-activities \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -d limit=50

Response

{
  "processingActivities": [
    {
      "id": "pa_71b2",
      "organizationId": "org_2f7a",
      "code": "plataforma-lectura",
      "name": "Plataforma de fomento lector",
      "status": "active",
      "lawfulBasis": "consent",
      "consentRequired": true,
      "involvesSensitiveData": false,
      "involvesMinorData": true,
      "includesAutomatedDecisions": false,
      "includesInternationalTransfers": false,
      "includesMonitoring": false,
      "isHighRisk": false,
      "riskLevel": "medium",
      "currentVersionNumber": 2,
      "currentVersion": {
        "id": "3f2e1d0c-9b8a-4765-b432-1a0f9e8d7c6b",
        "versionNumber": 2,
        "versionStatus": "published",
        "title": "Plataforma de fomento lector",
        "consentModel": "bundled",
        "noticeChecksum": "sha256:…",
        "publishedAt": "2026-07-10T14:00:00.000Z",
        "invalidatesPreviousConsents": true
      },
      "retentionPolicy": null,
      "dpiaAssessmentCount": 0
      // ...
    }
  ],
  "meta": {
    "totalMatchedCount": 3,
    "limit": 50,
    "returnedCount": 3,
    "nextCursor": null,
    "hasMore": false
  }
}

POST/v1/organizations/:organizationId/processing-activities

Crear una actividad de tratamiento

Crea la actividad y su versión 1 en borrador. Responde 201 con la actividad serializada; el evento de auditoría created queda en el registro de la organización. Si el code ya existe, 409 PROCESSING_ACTIVITY_CODE_CONFLICT.

Permiso requerido: partner.processing_activities.write · Alcance de conexión: processing_activities:write.

Atributos requeridos

Nombre
code
Tipo
string
Descripción
Código estable de la actividad (2–80). Es la llave con la que luego referencias la actividad al pedir consentimientos.
Nombre
name
Tipo
string
Descripción
Nombre de la actividad (2–160).

Atributos opcionales

Nombre
lawfulBasis
Tipo
string
Descripción
Base de licitud. Por defecto "consent".
Nombre
consentRequired
Tipo
boolean
Descripción
Si exige consentimiento. Por defecto true.
Nombre
involvesSensitiveData
Tipo
boolean
Descripción
Trata datos sensibles. Por defecto false.
Nombre
involvesMinorData
Tipo
boolean
Descripción
Trata datos de menores. Por defecto true.
Nombre
includesAutomatedDecisions
Tipo
boolean
Descripción
Incluye decisiones automatizadas. Por defecto false.
Nombre
includesInternationalTransfers
Tipo
boolean
Descripción
Incluye transferencias internacionales. Por defecto false.
Nombre
includesMonitoring
Tipo
boolean
Descripción
Incluye monitoreo u observación sistemática. Por defecto false.
Nombre
isHighRisk
Tipo
boolean
Descripción
Marca de alto riesgo. Por defecto false.
Nombre
retentionPolicyId
Tipo
string
Descripción
Política de retención de la organización (UUID). Si no existe, 404 RETENTION_POLICY_NOT_FOUND.
Nombre
metadata
Tipo
object
Descripción
Objeto libre.
Nombre
currentVersion
Tipo
object
Descripción
Contenido de la versión 1: versionLabel, title, purposeSummary, plainLanguageNotice (el aviso en lenguaje claro, máx. 5000), legalBasisDetail, consentModel (por defecto "bundled"; con "granular" se exige consentOptions), consentOptions (hasta 20 opciones { code, label, description, sortOrder }), retentionSummary, transferSummary, automationSummary, invalidatesPreviousConsents (por defecto true) y metadata.

Request

POST

/v1/.../processing-activities

curl https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/processing-activities \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "plataforma-lectura",
    "name": "Plataforma de fomento lector",
    "currentVersion": {
      "purposeSummary": "Cuentas de estudiante para asignar lecturas y medir avance.",
      "plainLanguageNotice": "Usaremos el nombre y curso de tu hijo/a para crear su cuenta de lectura…"
    }
  }'

Response

{
  "id": "pa_71b2",
  "code": "plataforma-lectura",
  "name": "Plataforma de fomento lector",
  "status": "draft",
  "lawfulBasis": "consent",
  "consentRequired": true,
  "currentVersionNumber": 1,
  "currentVersion": {
    "id": "v1_8e4d",
    "versionNumber": 1,
    "versionStatus": "draft",
    "title": "Plataforma de fomento lector",
    "consentModel": "bundled",
    "noticeChecksum": "sha256:…",
    "publishedAt": null,
    "invalidatesPreviousConsents": true
  },
  "retentionPolicy": null
  // ...
}

GET/v1/organizations/:organizationId/processing-activities/:processingActivityId

Obtener una actividad de tratamiento

Devuelve la ficha completa de una actividad: su versión vigente con las categorías de datos, destinatarios y opciones de consentimiento declaradas, el historial de versiones (versions) y el recuento de solicitudes de consentimiento por versión (consentRequestCounts) — el radio de impacto que conviene mirar antes de publicar una versión que invalida consentimientos.

Permiso requerido: partner.processing_activities.read · Alcance de conexión: processing_activities:read.

Si la actividad no pertenece a la organización, responde 404 PROCESSING_ACTIVITY_NOT_FOUND.

Request

GET

/v1/.../processing-activities/pa_71b2

curl https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/processing-activities/pa_71b2 \
  -H "Authorization: Bearer {keyId}.{secret}"

Response

{
  "id": "pa_71b2",
  "code": "plataforma-lectura",
  "name": "Plataforma de fomento lector",
  "status": "active",
  "currentVersionNumber": 2,
  "currentVersion": {
    "id": "3f2e1d0c-9b8a-4765-b432-1a0f9e8d7c6b",
    "versionNumber": 2,
    "versionStatus": "published",
    "consentModel": "bundled",
    "dataCategories": [
      {
        "id": "adc_11",
        "dataCategoryId": "dc_a1",
        "subjectType": "student",
        "requiresConsent": true,
        "isSensitiveOverride": null,
        "retentionPolicyId": null,
        "categoryCode": "identificacion-basica",
        "categoryName": "Identificación básica",
        "categoryIsSensitive": false,
        "categorySensitivityLevel": "standard"
      }
    ],
    "recipients": [
      {
        "id": "ar_31",
        "recipientType": "processor",
        "name": "Proveedor de hosting",
        "legalBasis": "contrato de encargo",
        "isInternationalTransfer": false,
        "transferDestinationId": null,
        "destinationName": null,
        "destinationCountryCode": null
      }
    ],
    "consentOptions": []
  },
  "versions": [
    { "versionNumber": 2, "versionStatus": "published" },
    { "versionNumber": 1, "versionStatus": "published" }
  ],
  "consentRequestCounts": {
    // totales de solicitudes por versión
  }
  // ...
}

POST/v1/organizations/:organizationId/processing-activities/:processingActivityId/versions

Crear una versión nueva

Crea la versión siguiente de la actividad, ya publicada, y la deja como versión vigente. Todos los campos son opcionales: lo que se omite se hereda de la versión anterior — incluidas sus categorías de datos, destinatarios y opciones de consentimiento. Responde 201 con { activity, invalidatedConsentRequestIds }.

Permiso requerido: partner.processing_activities.write · Alcance de conexión: processing_activities:write.

Cuando invalidatesPreviousConsents es true (el valor heredado por defecto), las solicitudes pending y granted de las versiones anteriores pasan a invalidated, sus decisiones otorgadas se revocan y cada titular queda marcado para recaptura — los IDs afectados vuelven en invalidatedConsentRequestIds. Publica una versión nueva sólo cuando el cambio de aviso realmente lo amerite.

Atributos opcionales

Nombre
versionLabel
Tipo
string
Descripción
Etiqueta legible de la versión (máx. 80).
Nombre
title
Tipo
string
Descripción
Título del aviso (máx. 160).
Nombre
purposeSummary
Tipo
string
Descripción
Resumen de la finalidad (máx. 2000).
Nombre
plainLanguageNotice
Tipo
string
Descripción
Aviso en lenguaje claro (máx. 5000).
Nombre
legalBasisDetail
Tipo
string
Descripción
Detalle de la base de licitud (máx. 1000).
Nombre
consentModel
Tipo
string
Descripción
bundled o granular. Con granular se exige consentOptions. Para volver de granular a bundled envía consentModel: "bundled" junto con consentOptions: [] — si omites consentOptions se copian las opciones de la versión anterior, y una versión bundled con opciones se rechaza con 422 CONSENT_OPTIONS_NOT_ALLOWED.
Nombre
consentOptions
Tipo
array
Descripción
Hasta 20 opciones { code, label, description, sortOrder }. Si se omite, se copian las de la versión anterior.
Nombre
retentionSummary
Tipo
string
Descripción
Resumen de retención (máx. 1000).
Nombre
transferSummary
Tipo
string
Descripción
Resumen de transferencias (máx. 1000).
Nombre
automationSummary
Tipo
string
Descripción
Resumen de decisiones automatizadas (máx. 1000).
Nombre
invalidatesPreviousConsents
Tipo
boolean
Descripción
Si publica invalidando los consentimientos previos. Heredado de la versión anterior; true por defecto.
Nombre
retentionPolicyId
Tipo
string
Descripción
Política de retención (UUID).
Nombre
metadata
Tipo
object
Descripción
Objeto libre.

Request

POST

/v1/.../processing-activities/pa_71b2/versions

curl https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/processing-activities/pa_71b2/versions \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "versionLabel": "2026-2",
    "purposeSummary": "Se agrega el módulo de audiolibros al servicio.",
    "invalidatesPreviousConsents": true
  }'

Response

{
  "activity": {
    "id": "pa_71b2",
    "code": "plataforma-lectura",
    "status": "active",
    "currentVersionNumber": 3,
    "currentVersion": {
      "versionNumber": 3,
      "versionStatus": "published",
      "versionLabel": "2026-2",
      "publishedAt": "2026-08-25T12:30:00.000Z",
      "invalidatesPreviousConsents": true
    }
    // ...
  },
  "invalidatedConsentRequestIds": [
    "c4a1b2d3-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  ]
}

POST/v1/organizations/:organizationId/processing-activities/:processingActivityId/versions/:processingActivityVersionId/data-categories

Declarar una categoría de datos

Vincula una categoría de datos a una versión en borrador. Puedes referenciar una categoría existente por dataCategoryId o crear una nueva en la misma llamada con newDataCategory; omitir ambas responde 422 VALIDATION_ERROR.

Permiso requerido: partner.processing_activities.write · Alcance de conexión: processing_activities:write.

El vínculo es idempotente sobre la tupla (versión, categoría, subjectType): repetir la declaración devuelve el vínculo existente en lugar de fallar. Sobre una versión publicada, 409 PROCESSING_ACTIVITY_VERSION_PUBLISHED.

Atributos opcionales

Nombre
dataCategoryId
Tipo
string
Descripción
UUID de una categoría existente de la organización.
Nombre
newDataCategory
Tipo
object
Descripción
Categoría a crear: code y name (requeridos), description, categoryGroup, subjectType, sensitivityLevel, isSensitive, requiresExpressConsent, defaultRetentionDays.
Nombre
subjectType
Tipo
string
Descripción
Tipo de titular al que aplica. Por defecto "student".
Nombre
requiresConsent
Tipo
boolean
Descripción
Si esta categoría requiere consentimiento dentro de la actividad. Por defecto true.
Nombre
isSensitiveOverride
Tipo
boolean
Descripción
Sobrescribe la sensibilidad de la categoría en esta actividad (null = usar la de la categoría).
Nombre
retentionPolicyId
Tipo
string
Descripción
Política de retención específica para esta categoría.

Request

POST

/v1/.../versions/v1_8e4d/data-categories

curl https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/processing-activities/pa_71b2/versions/v1_8e4d/data-categories \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "newDataCategory": {
      "code": "avance-lector",
      "name": "Avance lector",
      "description": "Libros leídos y tiempo de lectura."
    },
    "subjectType": "student"
  }'

Response

{
  "id": "adc_12",
  "organizationId": "org_2f7a",
  "processingActivityVersionId": "v1_8e4d",
  "dataCategoryId": "dc_b7",
  "subjectType": "student",
  "requiresConsent": true,
  "isSensitiveOverride": null,
  "retentionPolicyId": null,
  "createdAt": "2026-08-25T12:30:00.000Z"
}

POST/v1/organizations/:organizationId/processing-activities/:processingActivityId/versions/:processingActivityVersionId/recipients

Declarar un destinatario

Declara un destinatario de los datos en una versión en borrador (un subencargado, un servicio interno, un destino de transferencia internacional). Responde 201 con el destinatario creado. Sobre una versión publicada, 409 PROCESSING_ACTIVITY_VERSION_PUBLISHED.

Permiso requerido: partner.processing_activities.write · Alcance de conexión: processing_activities:write.

Atributos requeridos

Nombre
name
Tipo
string
Descripción
Nombre del destinatario (2–160).

Atributos opcionales

Nombre
recipientType
Tipo
string
Descripción
Tipo de destinatario. Por defecto "internal".
Nombre
legalBasis
Tipo
string
Descripción
Base que habilita la comunicación de datos (máx. 160).
Nombre
isInternationalTransfer
Tipo
boolean
Descripción
Si implica transferencia internacional. Por defecto false.
Nombre
notes
Tipo
string
Descripción
Notas (máx. 1000).

Request

POST

/v1/.../versions/v1_8e4d/recipients

curl https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/processing-activities/pa_71b2/versions/v1_8e4d/recipients \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Proveedor de hosting",
    "recipientType": "processor",
    "legalBasis": "contrato de encargo"
  }'

Response

{
  "id": "ar_32",
  "organizationId": "org_2f7a",
  "processingActivityVersionId": "v1_8e4d",
  "recipientType": "processor",
  "name": "Proveedor de hosting",
  "legalBasis": "contrato de encargo",
  "isInternationalTransfer": false,
  "transferDestinationId": null,
  "partnerAccountId": null,
  "notes": null,
  "createdAt": "2026-08-25T12:30:00.000Z"
}

POST/v1/organizations/:organizationId/processing-activities/:processingActivityId/versions/:processingActivityVersionId/publish

Publicar una versión

Sella una versión en borrador: la marca published, la deja como versión vigente y promueve la actividad de draft a active. Desde ese momento la versión es inmutable y puede referenciarse al crear solicitudes de consentimiento. La operación es idempotente: republicar una versión ya publicada es un no-op que devuelve la versión tal cual.

Permiso requerido: partner.processing_activities.write · Alcance de conexión: processing_activities:write.

Publicar cuenta como revisión del RAT: actualiza el reloj de revisión anual de la actividad. Si la versión declara consentModel: "granular" sin opciones de consentimiento, la publicación se rechaza — el mismo control que rige al crearla.

Request

POST

/v1/.../versions/v1_8e4d/publish

curl -X POST https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/processing-activities/pa_71b2/versions/v1_8e4d/publish \
  -H "Authorization: Bearer {keyId}.{secret}"

Response

{
  "id": "v1_8e4d",
  "organizationId": "org_2f7a",
  "processingActivityId": "pa_71b2",
  "versionNumber": 1,
  "versionStatus": "published",
  "title": "Plataforma de fomento lector",
  "consentModel": "bundled",
  "noticeChecksum": "sha256:…",
  "publishedAt": "2026-08-25T12:30:00.000Z",
  "invalidatesPreviousConsents": true
  // ...
}