Campañas compartidas

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.

Un share es exactamente un grupo. Cuando el grupo es un curso (groupKind: "course"), course trae schoolYear, gradeLevel y courseCode (la letra o sección), si el dueño los cargó. Si no es un curso, course es null.

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

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 en cualquier modo; el único que puede salir es el correo del estudiante, de a un sobre y con consentimiento otorgado.

Cada titular trae enrollment: el curso del share (courseName, schoolYear, gradeLevel, courseCode), o null si el grupo no es un curso.

contacts son los canales propios del estudiante, y no dicen si una campaña lo alcanza: la solicitud va a quien decide, que bajo 14 años (bajo 16 si tu finalidad trata datos sensibles) es su apoderado. Eso lo dice consentReach, separado en general y sensitive porque entre 14 y 15 años difieren. Cada uno trae decidedBy (self, guardian, o null si falta la fecha de nacimiento), status (ok, guardian_missing, authority_undetermined) y channels: los canales de campaña (email, whatsapp) por los que se alcanza a alguien que puede decidir. Si el estudiante tiene varios apoderados con autoridad, la solicitud les llega a todos y decide el primero; basta con alcanzar a uno.

meta.missingContactCount cuenta, en todo el grupo, los titulares cuyo channels queda vacío en al menos uno de los dos tipos; meta.unreachableCount trae el mismo conteo separado ({ general, sensitive }). Con since, un contacto o apoderado nuevo no marca al titular como cambiado: vuelve a leer sin since para refrescar el alcance.

Parámetros de consulta opcionales

Hash de RUT por partner

Con include=nationalIdHash cada titular trae nationalIdPartnerHash: un HMAC del RUT con una clave propia de tu cuenta. El mismo RUT da el mismo hash para ti y otro distinto para cualquier otro partner, y rotar claves no lo cambia. Sirve para cruzar el grupo contra tu base sin guardar RUT en claro. Para hashear RUTs que tú tienes (por ejemplo, el que escribe un estudiante en tu página) está POST /v1/organizations/:organizationId/shares/:shareId/national-id-hash con { "ruts": [...] } (hasta 100); responde { "hashes": [...] }, con null para un RUT inválido, y consume el mismo presupuesto diario por share que la segmentación por RUT (429 SHARE_RUT_LOOKUP_BUDGET_EXCEEDED).

No hace falta disclosure=full, pero sí que el dueño mantenga habilitada la divulgación de RUT para esa share: aunque no revela el RUT, un hash comparable responde la misma pregunta de pertenencia —«¿este RUT está en el curso?»—, así que la decide el mismo interruptor. Si está apagado, ambas vías responden 403 SHARE_RUT_DISCLOSURE_DISABLED; en ese curso sincroniza con subjectId y maskedRut. Cada lectura queda auditada como divulgación.

Devuelve el estado de consentimiento de los titulares del grupo: una fila por solicitud de cualquiera de tus campañas sobre esta share —también las declaradas por el registrador, que no tienen sobres—. Es la otra mitad de listar titulares: cada fila trae subjectId, el mismo identificador, para cruzar las dos lecturas.

Cada fila es la misma proyección shared_partner que el webhook y el detalle por id, más subjectId, processingActivityCode, processingActivityVersionNumber e invalidatedAt. Nunca trae RUT, contactos ni nombre del titular, y de la decisión trae el rol que decidió (decisionAuthority) y cómo se capturó (captureMethod: portal_link_otp o registrar_attestation), nunca quién.

:organizationId es la organización dueña, como en el resto de las lecturas de shares. Una share de otra organización o de otro partner responde 404 REGISTRY_SHARE_NOT_FOUND; una revocada, 409 REGISTRY_SHARE_REVOKED.

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

Las filas se ordenan por updatedAt ascendente: para conciliar, guarda el mayor updatedAt que leíste y úsalo como el próximo updatedSince (inclusivo: deduplica por consentRequestId + updatedAt). Una solicitud reemplazada por otra campaña sigue saliendo, con invalidatedAt; quédate con la vigente de cada titular y actividad. En una campaña segmentada por RUT, una solicitud sin decisión no aparece hasta que el titular decide, y un titular suprimido en origen no aparece nunca.

Parámetros de consulta opcionales

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

Atributos opcionales

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.

Extiende o adelanta el endsAt de una campaña, también ya publicada. Las solicitudes pendientes pasan a vencer en la fecha nueva, incluidas las que viven en el padrón de cada colegio. Las que ya vencieron no reviven: para pedirlas de nuevo dentro del plazo nuevo está el reenvío del sobre. Los sobres que se despachen después toman el endsAt nuevo.

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

La fecha debe ser futura (422 VALIDATION_ERROR) y la campaña no puede estar cerrada (409 CONSENT_CAMPAIGN_CLOSED). Cada cambio deja el evento de auditoría updated con el endsAt nuevo y cuántas solicitudes se reprogramaron.

Solo actúa sobre campañas compartidas. Una campaña de tu workspace creada con audiencia en línea responde 409 PARTNER_CAMPAIGN_FAMILY_MISMATCH y se gestiona con PATCH /consents/campaigns/:campaignId.

La respuesta trae origin (operator o registrar_attestation), el mismo valor de la lectura de la campaña. En una campaña declarada (registrar_attestation) esta es una de las pocas ediciones permitidas, junto al nombre y la descripción.

Adelantar el cierre corta los recordatorios y el portal al llegar la fecha nueva, pero no es inmediato y la campaña sigue published. Para terminarla ya, ciérrala.

Cierra la campaña de inmediato, con la misma cascada que el botón «Cerrar campaña» de la Consola, también sobre las solicitudes que viven en el padrón de cada colegio:

• las solicitudes pendientes pasan a invalidated (invalidationReason: "campaign_closed") y cada una emite consent.invalidated — al colegio y, con la proyección para partners, a ti;
• sus enlaces dejan de abrir el formulario, no salen más recordatorios y la completación pública se cierra;
• los sobres que nunca se despacharon quedan cancelados, y despachar o reenviar un sobre responde 409 CONSENT_CAMPAIGN_CLOSED;
• la campaña queda closed y ya no se puede editar.

Las decisiones ya registradas no se tocan: quien otorgó o rechazó conserva su comprobante y la evidencia sigue disponible; un consentimiento otorgado sigue vigente hasta que se revoque. Si el titular te pide el retiro a ti, regístralo con POST /consents/requests/:consentRequestId/revoke sobre tu workspace. Cerrar no se deshace.

Permiso requerido: partner.shared_campaigns.write · Alcance de conexión: consents:write. La organización de la URL es tu workspace (403 PARTNER_WORKSPACE_REQUIRED). Una campaña con audiencia en línea responde 409 PARTNER_CAMPAIGN_FAMILY_MISMATCH y se cierra con POST /consents/campaigns/:campaignId/close. Cerrar una campaña ya cerrada responde 409 CONSENT_CAMPAIGN_ALREADY_CLOSED, así que un reintento después de un timeout se reconoce por ese código.

La respuesta trae también origin, para que una campaña declarada no se confunda con una lanzada por ti; cerrar una campaña declarada está permitido. El cuerpo es opcional. La respuesta no trae conteos —en una campaña segmentada por RUT dirían cuántos de los RUT enviados estaban en el padrón—; cada solicitud anulada te llega por su propio consent.invalidated. En una campaña segmentada por RUT no recibes ninguno: solo se anulan solicitudes sin decisión, y eso es justo lo que ese modo no revela.

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

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). Trae además portalAccessLinks: el token del portal por entrega, para que muestres el enlace dentro de tu app sin esperar a que el apoderado abra el correo.
• already_sent — el sobre ya tenía solicitud; se devuelve la existente. Reintentar es seguro: hay una solicitud por sobre, garantizada por esquema.
• already_granted — el titular ya otorgó esta versión de la actividad en otra campaña: no se le pide de nuevo ni se envía nada, y consentRequestId es el de ese consentimiento.
• 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.
• authority_unresolved — todavía nadie puede decidir por este titular: errorCode dice por qué (CONSENT_AUTHORITY_UNDETERMINED si falta la fecha de nacimiento, GUARDIAN_AUTHORITY_REQUIRED si no hay apoderado vigente, SUBJECT_PROCESSING_OPPOSED si el titular se opuso a esta finalidad). El resto del lote se envía igual. La autoridad se re-evalúa en cada despacho: cuando el colegio corrija el padrón, reenvía el mismo sobre. En un envío individual esto es un 409 con ese mismo código.

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

Reenvía la entrega de un sobre, opcionalmente con un destino nuevo. Hay una solicitud por sobre a la vez, 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.

Solicitud vencida. Si la solicitud del sobre venció sin respuesta y la campaña sigue en fecha (por ejemplo, porque se extendió su endsAt), el reenvío emite una solicitud nueva para el mismo titular, con el destino de la anterior salvo que mandes otro. La respuesta trae el consentRequestId nuevo, sus portalAccessLinks y previousConsentRequestId; la vencida sigue en la campaña con su historial. Una decisión ya tomada no se vuelve a pedir: quien dijo que no puede cambiar de opinión en el portal de transparencia.

Sin nada que reenviar la respuesta es status: "not_resendable" con reason, nunca sent:

• already_decided — la solicitud ya tiene decisión (otorgada, rechazada o revocada) o se anuló.
• campaign_ended — venció junto con la campaña; no hay plazo para pedirla de nuevo.
• nothing_queued — sigue vigente, pero ninguna entrega quedó en cola (quien decide no tiene un canal utilizable).

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.

La respuesta trae portalAccessLinks con el token vigente de cada entrega reenviada — el mismo que recibe el apoderado: se conserva mientras siga válido y se acuña uno nuevo si venció.

Atributos opcionales

Para más de 200 sobres: hasta 5.000 en una llamada. Responde 202 con el job. Edugoverna los despacha en tramos de 200 con el mismo proceso que el envío síncrono, así que cada sobre tiene los mismos desenlaces (sent, already_sent, authority_unresolved, …) y reintentar es igual de seguro. Al terminar recibes envelopes.job.completed con los conteos.

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

Mandar la cabecera Idempotency-Key hace que repetir la llamada devuelva el mismo job en vez de crear otro. Los requisitos de la campaña (publicada, per_subject, no segmentada por RUT) se validan al crear el job, no a mitad de camino. Si la campaña se cierra mientras corre, el job termina en failed con errorCode.

GET …/envelope-jobs/:jobId devuelve el estado (queued, running, completed o failed), los conteos y los resultados por fila en el orden en que los mandaste (position), paginados con cursor y limit (hasta 500).

El correo primario del estudiante de un sobre, para que le escribas sobre lo que su familia autorizó. Nunca el de un apoderado, y nunca un teléfono. Se lee de a un sobre. Responde { envelopeId, email } con Cache-Control: no-store.

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

Condiciones, todas a la vez:

• El dueño del padrón habilitó la entrega en el share (apagada por defecto; el colegio la enciende en su consola y el registrador en su portal). Si no, 403 SHARE_STUDENT_EMAIL_DISCLOSURE_DISABLED.
• El consentimiento del sobre está otorgado y vigente. Sin eso, o si el sobre no existe o el estudiante no tiene correo, responde 404 CONSENT_ENVELOPE_STUDENT_CONTACT_NOT_AVAILABLE, sin distinguir entre los casos.

Cada lectura (y cada negativa) deja una fila de divulgación en la Auditoría del dueño y otra en la tuya.

La prueba del consentimiento de un sobre ya decidido, para exhibirla ante un apoderado o un fiscalizador sin pedírsela al colegio. No trae datos de quien decidió, solo el rol (decisionAuthority). Qué se decidió, cuándo, sobre qué versión del aviso (notice.noticeChecksum), y el id, tipo y checksum de cada artefacto sellado: el manifiesto firmado (sealed_manifest) y sus recibos. Cada artefacto trae su verificationUrl.

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

Un sobre sin decisión responde 404 CONSENT_ENVELOPE_DECISION_NOT_FOUND, igual que uno que no existe.

captureMethod es portal_link_otp cuando la familia decidió con su enlace y código, y registrar_attestation cuando el consentimiento fue declarado por el establecimiento. En ese caso el manifiesto cita la declaración jurada del registrador (registrarDeclaration) y el colegio conserva los originales firmados: no es una firma con código de un solo uso.

Verificar un checksum

GET /api/public/evidence/verify?checksum=<sha256> es público y no revela de quién es la evidencia. Responde { "valid": false } o { "valid": true, evidenceType, capturedAt, signedAt, algorithm, kid }. EduGoverna re-hashea el artefacto guardado y verifica la firma Ed25519 del manifiesto con la clave publicada en /api/public/jwks.json, no con la que trae el propio documento. El mismo checksum llega en los webhooks (latestDecision.evidence).

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.

Sobre una campaña declarada (origin: "registrar_attestation") responde 409 CONSENT_CAMPAIGN_ATTESTED_READ_ONLY: agregaría al curso entero, también a quienes el colegio no marcó, y les enviaría la solicitud.

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

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