EdugovernaDocs

Campañas compartidas

Un colegio o un registrador externo puede compartir contigo un grupo de su padrón — un curso, un segmento, una generación — mediante un registro compartido (registry_share). Sobre esos grupos puedes lanzar campañas de consentimiento que viven en tu propio espacio de trabajo, mientras las solicitudes se crean en el padrón del dueño de los datos y Edugoverna hace todas las entregas. En esta página revisamos los endpoints de lectura de grupos compartidos, la creación de campañas y el envío por sobres.

Las rutas de esta página cuelgan de la URL base https://app.edugoverna.com/api/partner/v1/organizations/:organizationId, pero cuidado con qué organización va en la ruta: en GET /shares y GET /shares/:shareId/subjects, :organizationId es la organización dueña del padrón (el colegio o registro). En todas las rutas /shared-campaigns, :organizationId es tu propia organización de espacio de trabajo — apuntarlas a la organización del dueño responde 403 PARTNER_WORKSPACE_REQUIRED. La guía paso a paso está en Guía de campañas compartidas.

El modelo

  • Registro compartido (share): la concesión con que el dueño te comparte un grupo. Tiene groupKind (course, segment o cohort) y un memberCount. El dueño puede revocarla en cualquier momento; una share revocada deja de resolver titulares.
  • Lectura ofuscada: los titulares de un grupo compartido se leen con obfuscación estructural — nombre, banda etaria, RUT enmascarado (maskedRut) y presencia de contactos (tipo y primario), nunca sus valores. Edugoverna despacha todas las entregas, así que tu integración no necesita el email ni el teléfono de nadie. La divulgación del RUT completo existe como excepción explícita y auditada (ver disclosure=full).
  • Campaña compartida: se crea y publica en una sola llamada sobre uno o más shares. En modo bulk (por defecto) el roster completo se despacha al publicar; en modo per_subject el roster se materializa como sobres (envelopes) — uno por familia — y tú los despachas uno a uno o por lotes, cada uno con su propia URL de destino.
  • Destinos (redirects): al decidir, el firmante puede ser redirigido a tu aplicación. redirectMode es auto (redirección inmediata) o bridge (pantalla intermedia de Edugoverna). Los pares RUT→URL se pueden fijar al crear, al sincronizar audiencia o corregirse después; los RUT que no calcen con el padrón se ignoran en silencio — ninguna respuesta confirma cuáles calzaron.
  • Contrato de no divulgación: en campañas segmentadas por RUT, las respuestas nunca revelan cuántos ni cuáles RUT resolvieron a titulares reales. Los únicos números que se devuelven son los que tú mismo enviaste.
GET/v1/organizations/:organizationId/shares

Listar registros compartidos

Devuelve los registros compartidos activos que esta organización dueña le concedió a tu cuenta de partner. :organizationId es la organización del dueño del padrón.

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

Request

GET
/v1/.../shares
curl https://app.edugoverna.com/api/partner/v1/organizations/org_colegio/shares \
  -H "Authorization: Bearer {keyId}.{secret}"

Response

{
  "shares": [
    {
      "id": "shr_1a2b3c",
      "groupType": "segment",
      "groupKind": "course",
      "groupName": "5° Básico B",
      "memberCount": 34,
      "grantSource": "school_dashboard",
      "createdAt": "2026-03-15T10:00:00.000Z"
    },
    {
      "id": "shr_4d5e6f",
      "groupKind": "cohort",
      "groupName": "Generación 2032"
      // ...
    }
  ]
}
GET/v1/organizations/:organizationId/shares/:shareId/subjects

Listar titulares de un grupo compartido

Devuelve una página de los titulares del grupo compartido, con la proyección ofuscada. :organizationId es la organización dueña; si la share no pertenece a ella, 404 REGISTRY_SHARE_NOT_FOUND; si fue revocada, la lectura se rechaza.

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

Con disclosure=full la respuesta agrega el campo rut con el RUT completo normalizado — lo que necesitas para cruzar el grupo contra tu propia base y segmentar por RUT. Requiere que el dueño tenga habilitada la divulgación de RUT para esa share (si la apagó, 403 SHARE_RUT_DISCLOSURE_DISABLED) y cada lectura ampliada queda auditada en la organización del dueño y en la tuya, con los titulares divulgados. Los valores de contacto siguen ocultos sin excepción, en cualquier modo.

Parámetros de consulta opcionales

  • Nombre
    offset
    Tipo
    integer
    Descripción

    Desplazamiento de la página. Por defecto 0.

  • Nombre
    limit
    Tipo
    integer
    Descripción

    Tamaño de página, entre 1 y 200. Por defecto 50.

  • Nombre
    disclosure
    Tipo
    string
    Descripción

    full para la lectura ampliada con RUT completo.

Request

GET
/v1/.../shares/shr_1a2b3c/subjects
curl -G https://app.edugoverna.com/api/partner/v1/organizations/org_colegio/shares/shr_1a2b3c/subjects \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -d limit=50 \
  -d disclosure=full

Response

{
  "share": {
    "id": "shr_1a2b3c",
    "groupType": "segment",
    "groupKind": "course",
    "groupName": "5° Básico B",
    "memberCount": 34
  },
  "subjects": [
    {
      "subjectId": "9c1f6d1e-1c9d-4f6a-9a44-1f2ab5c0d9e1",
      "displayName": "Martina Rojas Pino",
      "subjectType": "student",
      "currentAgeBand": "under_14",
      "maskedRut": "**.***.435-2",
      "rut": "25678435-2",
      "contacts": [
        { "contactType": "email", "isPrimary": true }
      ]
    }
  ],
  "meta": {
    "totalCount": 34,
    "offset": 0,
    "limit": 50,
    "missingContactCount": 3
  }
}
POST/v1/organizations/:organizationId/shared-campaigns

Crear una campaña compartida

Crea y publica una campaña de consentimiento sobre uno o más registros compartidos. :organizationId es tu organización de espacio de trabajo; cada share del cuerpo se re-autoriza contra tu cuenta de partner. Responde 202 Accepted con una forma idéntica resuelva lo que resuelva la audiencia — el contrato de no divulgación.

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

Cada target apunta a un share y, opcionalmente, a una lista de RUTs dentro del grupo (segmentación por RUT, hasta 500 por share y 1000 por campaña). Sin ruts, la campaña cubre el grupo completo (modo group); con ruts, sólo los que calcen por índice ciego (modo rut, con proyección de no divulgación de membresía).

Las URLs de redirección son tuyas y no llevan lista blanca en este flujo: en una campaña compartida el aviso que el titular lee lo firma tu organización, y el dueño lo aceptó al conectarse.

Atributos requeridos

  • Nombre
    processingActivityVersionId
    Tipo
    string
    Descripción

    UUID de la versión de tu actividad de tratamiento — usa la versión publicada vigente: es el aviso que el titular leerá al decidir.

  • Nombre
    name
    Tipo
    string
    Descripción

    Nombre de la campaña (2–160).

  • Nombre
    targets
    Tipo
    array
    Descripción

    Entre 1 y 50 entradas { shareId, ruts? }. Máximo 1000 RUTs sumados.

Atributos opcionales

  • Nombre
    description
    Tipo
    string
    Descripción

    Descripción (máx. 2000).

  • Nombre
    channels
    Tipo
    array
    Descripción

    ["email"], ["whatsapp"] o ambos. Por defecto ["email"].

  • Nombre
    endsAt
    Tipo
    timestamp
    Descripción

    Cierre de la campaña (ISO 8601, futuro).

  • Nombre
    reminderDayOffsets
    Tipo
    array
    Descripción

    Hasta 10 recordatorios en días desde el envío (1–60).

  • Nombre
    dispatchMode
    Tipo
    string
    Descripción

    bulk (por defecto: despacha el roster completo al publicar) o per_subject (materializa sobres y espera tus envíos uno a uno).

  • Nombre
    defaultSuccessRedirectUrl
    Tipo
    string
    Descripción

    URL de éxito por defecto para toda la campaña.

  • Nombre
    defaultDeclineRedirectUrl
    Tipo
    string
    Descripción

    URL de rechazo por defecto.

  • Nombre
    redirectMode
    Tipo
    string
    Descripción

    auto o bridge.

  • Nombre
    redirects
    Tipo
    array
    Descripción

    Hasta 2500 pares { rut, successRedirectUrl, declineRedirectUrl?, redirectMode? } decididos al crear. Quedan como destino planificado del sobre de cada estudiante y cualquier vía de completación resuelve el mismo. Los RUT que no calcen se ignoran en silencio.

  • Nombre
    publicCompletionEnabled
    Tipo
    boolean
    Descripción

    Abre la puerta pública de completación: un titular del roster sin canal registrado puede identificarse con su RUT, verificar un contacto propio con OTP y firmar su propio sobre. La respuesta incluye publicCompletionUrl.

Request

POST
/v1/.../shared-campaigns
curl https://app.edugoverna.com/api/partner/v1/organizations/org_milectura/shared-campaigns \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "processingActivityVersionId": "3f2e1d0c-9b8a-4765-b432-1a0f9e8d7c6b",
    "name": "Alta 5° Básico B — Colegio San Martín",
    "dispatchMode": "per_subject",
    "defaultSuccessRedirectUrl": "https://app.milectura.cl/bienvenida",
    "redirectMode": "bridge",
    "publicCompletionEnabled": true,
    "targets": [{ "shareId": "shr_1a2b3c" }]
  }'

Response

{
  "campaignId": "a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7",
  "submittedShareCount": 1,
  "publicCompletionEnabled": true,
  "publicCompletionUrl": "https://app.edugoverna.com/consentimientos/c/pct_…",
  "status": "accepted"
}
GET/v1/organizations/:organizationId/shared-campaigns/:campaignId

Obtener una campaña compartida

Devuelve el estado agregado de la campaña: el embudo de desenlaces (outcomes) y — en campañas por grupo — el total del roster y su desglose de cobertura. En campañas segmentadas por RUT la respuesta trae decidedOnly: true y omite denominadores, de nuevo por el contrato de no divulgación: sólo se describen los contactos que ya decidieron.

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

  • Nombre
    outcomes
    Tipo
    object
    Descripción

    counts (granted, denied, revoked, expired, cancelled, errored), inProgress y total.

  • Nombre
    coverage
    Tipo
    object
    Descripción

    Sólo en modo grupo: totalStudents, deliverableStudents, manualDeliveryStudents, authorityUndetermined, guardianMissing y, en modo sobre, awaitingSendStudents.

Request

GET
/v1/.../shared-campaigns/a9b8c7d6...
curl https://app.edugoverna.com/api/partner/v1/organizations/org_milectura/shared-campaigns/a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7 \
  -H "Authorization: Bearer {keyId}.{secret}"

Response

{
  "campaignId": "a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7",
  "name": "Alta 5° Básico B — Colegio San Martín",
  "status": "published",
  "dispatchMode": "per_subject",
  "targetingMode": "group",
  "channels": ["email"],
  "publishedAt": "2026-08-25T12:30:00.000Z",
  "closedAt": null,
  "endsAt": null,
  "publicCompletionEnabled": true,
  "publicCompletionUrl": "https://app.edugoverna.com/consentimientos/c/pct_…",
  "outcomes": {
    "counts": {
      "granted": 12,
      "denied": 1,
      "revoked": 0,
      "expired": 0,
      "cancelled": 0,
      "errored": 0
    },
    "inProgress": 21,
    "total": 34
  },
  "rosterTotal": 34,
  "coverage": {
    "totalStudents": 34,
    "deliverableStudents": 13,
    "manualDeliveryStudents": 0,
    "authorityUndetermined": 0,
    "guardianMissing": 0,
    "awaitingSendStudents": 21
  }
}
GET/v1/organizations/:organizationId/shared-campaigns/:campaignId/envelopes

Listar sobres de una campaña

Devuelve el roster de la campaña sobre a sobre, con el estado de cada uno y su destino planificado. Es tu tablero de seguimiento en modo per_subject. En campañas segmentadas por RUT esta lectura se rechaza con 409 CONSENT_CAMPAIGN_RUT_MODE_RESTRICTED — el estado por titular revelaría membresía.

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

El campo completedVia de un sobre completado distingue dispatch (firmó por su enlace despachado) de public_completion (firmó por la puerta pública; en ese caso reviewStatus refleja la revisión del staff: pending, verified o rejected).

Parámetros de consulta opcionales

  • Nombre
    status
    Tipo
    string
    Descripción

    Filtra por estado del sobre (por ejemplo awaiting_send, queued, completed, error).

Request

GET
/v1/.../shared-campaigns/a9b8c7d6.../envelopes
curl -G https://app.edugoverna.com/api/partner/v1/organizations/org_milectura/shared-campaigns/a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7/envelopes \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -d status=awaiting_send

Response

{
  "campaignId": "a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7",
  "envelopes": [
    {
      "envelopeId": "env_7f8e9d",
      "subjectId": "9c1f6d1e-1c9d-4f6a-9a44-1f2ab5c0d9e1",
      "referenceCode": null,
      "partnerExternalId": null,
      "status": "awaiting_send",
      "errorCode": null,
      "errorMessage": null,
      "consentRequestId": null,
      "requestStatus": null,
      "sentAt": null,
      "successRedirectUrl": null,
      "plannedSuccessRedirectUrl": "https://app.milectura.cl/bienvenida?e=88231",
      "completedVia": null,
      "reviewStatus": null
    }
  ]
}
POST/v1/organizations/:organizationId/shared-campaigns/:campaignId/envelopes

Despachar sobres

Despacha uno o varios sobres de una campaña per_subject publicada, cada uno con su propia URL de destino. Acepta un sobre (el cuerpo es el objeto directamente) o un lote ({ "envelopes": [...] }, hasta 200). Responde 202 con el resultado por sobre.

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

Cada sobre identifica al estudiante por exactamente uno de subjectId (el ID de la lectura del grupo) o rut. Los estados posibles del resultado:

  • sent — se creó la solicitud y se encoló su entrega (webhook consent.requested en la organización del titular).
  • already_sent — el sobre ya tenía solicitud; se devuelve la existente. Reintentar es seguro: hay una solicitud por sobre, garantizada por esquema.
  • not_in_campaign — el titular no está en el roster. En un envío individual esto es 404 CONSENT_CAMPAIGN_CONTACT_NOT_FOUND; en un lote, cada fila lleva su propio desenlace.
  • share_revoked — el dueño revocó la share; el sobre no se envía.

Requisitos de la campaña: publicada (409 CONSENT_CAMPAIGN_NOT_PUBLISHED), no cerrada (409 CONSENT_CAMPAIGN_CLOSED), modo per_subject (409 CONSENT_CAMPAIGN_DISPATCH_MODE_UNSUPPORTED) y no segmentada por RUT. Cada despacho deja el evento de auditoría envelopes_dispatched con los conteos del lote.

Atributos por sobre

  • Nombre
    subjectId
    Tipo
    string
    Descripción

    UUID del titular (excluyente con rut).

  • Nombre
    rut
    Tipo
    string
    Descripción

    RUT del estudiante (excluyente con subjectId).

  • Nombre
    successRedirectUrl
    Tipo
    string
    Descripción

    URL de destino tras otorgar; prevalece sobre la planificada.

  • Nombre
    declineRedirectUrl
    Tipo
    string
    Descripción

    URL de destino tras denegar.

  • Nombre
    redirectMode
    Tipo
    string
    Descripción

    auto o bridge.

  • Nombre
    partnerExternalId
    Tipo
    string
    Descripción

    Tu correlativo para este sobre (1–160).

  • Nombre
    idempotencyKey
    Tipo
    string
    Descripción

    Llave de idempotencia (8–120).

Request

POST
/v1/.../shared-campaigns/a9b8c7d6.../envelopes
curl https://app.edugoverna.com/api/partner/v1/organizations/org_milectura/shared-campaigns/a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7/envelopes \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "rut": "25678435-2",
    "successRedirectUrl": "https://app.milectura.cl/bienvenida?e=88231",
    "partnerExternalId": "lic-88231"
  }'

Response

{
  "subjectId": "9c1f6d1e-1c9d-4f6a-9a44-1f2ab5c0d9e1",
  "rut": "25678435-2",
  "envelopeId": "env_7f8e9d",
  "consentRequestId": "c4a1b2d3-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "sent"
}
POST/v1/organizations/:organizationId/shared-campaigns/:campaignId/envelopes/:envelopeId/resend

Reenviar un sobre

Reenvía la entrega de un sobre, opcionalmente con un destino nuevo. Hay una solicitud por sobre para siempre, así que un reenvío con URL distinta no crea una segunda solicitud: actualiza el destino de la existente y re-encola su entrega — el titular recibe el mismo enlace de siempre, ahora apuntando al destino corregido. Si el sobre nunca se había enviado, esta llamada equivale a su primer despacho. Responde 202 con el resultado del sobre.

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

Un :envelopeId que no pertenece a la campaña responde 404 CONSENT_CAMPAIGN_CONTACT_NOT_FOUND.

Atributos opcionales

  • Nombre
    successRedirectUrl
    Tipo
    string
    Descripción

    Nuevo destino tras otorgar.

  • Nombre
    declineRedirectUrl
    Tipo
    string
    Descripción

    Nuevo destino tras denegar.

  • Nombre
    redirectMode
    Tipo
    string
    Descripción

    auto o bridge.

Request

POST
/v1/.../envelopes/env_7f8e9d/resend
curl https://app.edugoverna.com/api/partner/v1/organizations/org_milectura/shared-campaigns/a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7/envelopes/env_7f8e9d/resend \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{ "successRedirectUrl": "https://app.milectura.cl/bienvenida?e=88231&retry=1" }'

Response

{
  "subjectId": "9c1f6d1e-1c9d-4f6a-9a44-1f2ab5c0d9e1",
  "rut": null,
  "envelopeId": "env_7f8e9d",
  "consentRequestId": "c4a1b2d3-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "sent"
}
POST/v1/organizations/:organizationId/shared-campaigns/:campaignId/sync-audience

Sincronizar la audiencia

La segunda ola: cuando el dueño del padrón agrega estudiantes nuevos a un curso ya compartido, esta llamada re-resuelve los grupos guardados de la campaña contra el registro de hoy y agrega sólo los contactos faltantes. En una campaña bulk publicada, además emite y despacha sus solicitudes por tramos; en modo per_subject, los nuevos quedan awaiting_send para que tú los despaches. Responde 202.

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

El comando es repetible por diferencia: si pendingRequestCount vuelve mayor que cero, quedan solicitudes por emitir de esta ola — vuelve a llamar hasta que llegue a cero. Los redirects del cuerpo aplican sólo a los contactos que esta pasada agrega; para corregir destinos de sobres ya existentes está el endpoint de redirects.

Atributos opcionales

  • Nombre
    redirects
    Tipo
    array
    Descripción

    Hasta 2500 pares { rut, successRedirectUrl, declineRedirectUrl?, redirectMode? } para los contactos nuevos de esta ola.

Request

POST
/v1/.../shared-campaigns/a9b8c7d6.../sync-audience
curl https://app.edugoverna.com/api/partner/v1/organizations/org_milectura/shared-campaigns/a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7/sync-audience \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "redirects": [
      { "rut": "26011822-5", "successRedirectUrl": "https://app.milectura.cl/bienvenida?e=90112" }
    ]
  }'

Response

{
  "addedContactCount": 2,
  "materializedRequestCount": 0,
  "pendingRequestCount": 0,
  "submittedRedirectCount": 1
}
POST/v1/organizations/:organizationId/shared-campaigns/:campaignId/redirects

Corregir destinos planificados

Re-escribe las URLs planificadas de los sobres que aún no tienen solicitud (por ejemplo, los awaiting_send de una campaña per_subject, o los pendientes de una bulk aún en materialización). Un sobre ya despachado no cambia retroactivamente por esta vía — para ese existe el reenvío con destino nuevo.

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

Sólo disponible en campañas por grupo (no segmentadas por RUT) y no cerradas (409 CONSENT_CAMPAIGN_CLOSED). Por cada RUT gana el último par de la lista; los RUT que no calcen se ignoran en silencio.

Atributos requeridos

  • Nombre
    redirects
    Tipo
    array
    Descripción

    Entre 1 y 2500 pares { rut, successRedirectUrl, declineRedirectUrl?, redirectMode? }.

Request

POST
/v1/.../shared-campaigns/a9b8c7d6.../redirects
curl https://app.edugoverna.com/api/partner/v1/organizations/org_milectura/shared-campaigns/a9b8c7d6-e5f4-4321-a0b1-c2d3e4f5a6b7/redirects \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "redirects": [
      { "rut": "25678435-2", "successRedirectUrl": "https://app.milectura.cl/bienvenida?e=88231-b" }
    ]
  }'

Response

{
  "submittedRedirectCount": 1,
  "updatedContactCount": 1
}

¿Te sirvió esta página?