Consentimientos

Crea una solicitud para un titular del padrón y encola de inmediato sus entregas. Responde 201 con el paquete completo de la solicitud y emite el webhook consent.requested.

El token del portal viaja en deliveryAccessLinks solo en esta respuesta: ni la repetición idempotente (idempotentReplay: true, con deliveryAccessLinks: []) ni el detalle lo devuelven. Si lo pierdes, o el apoderado vuelve pasados los siete días de vigencia, reemite el enlace en vez de crear otra solicitud.

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

La actividad de tratamiento se referencia de una de dos formas: por processingActivityVersionId (UUID exacto de la versión) o por processingActivityCode (más processingActivityVersionNumber opcional; si se omite, se usa la versión vigente). Omitir ambas responde 422; si ambas vienen y no resuelven a la misma versión, 422 PROCESSING_ACTIVITY_REFERENCE_MISMATCH.

Las URLs de redirección deben estar registradas en la lista de destinos permitidos de tu conexión; una URL no registrada rechaza la llamada antes de escribir nada.

Atributos requeridos

Atributos opcionales

Devuelve una página de solicitudes de la organización, ordenadas de la más reciente a la más antigua. A diferencia del detalle, el listado devuelve las filas base de cada solicitud (sin entregas ni decisión); usa el detalle para el paquete completo.

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

since acota a las solicitudes creadas después del instante dado (requestedAt). Para una conciliación incremental usa updatedSince: devuelve sólo las que cambiaron desde ese instante (una decisión, un retiro, un vencimiento, una anulación), ordenadas de la más antigua a la más nueva por updatedAt. Guarda el mayor updatedAt que leíste y úsalo como el próximo updatedSince. El filtro es inclusivo, así que la última fila puede repetirse en la lectura siguiente: deduplica por id + updatedAt. Una solicitud que cambia mientras recorres las páginas pasa al final del recorrido, así que no se pierde.

Combina cualquiera de los dos con cursor para recorrer páginas. El cursor está firmado contra la organización y el juego de filtros con que se emitió: reutilizarlo con filtros distintos responde 422 INVALID_CURSOR. Las solicitudes cuyo titular fue suprimido en origen se omiten de la respuesta. El listado trae las solicitudes que viven en la organización de la URL. Las de una campaña compartida viven en el colegio o en el registrador: léelas con consentimientos de un grupo compartido o síguelas por webhooks.

Cada fila trae exactamente los campos del ejemplo: id, organizationId, processingActivityVersionId, targetSubjectId, requestedForAgeBand, decisionActorType, status, requestedAt, expiresAt, invalidatedAt, invalidationReason, partnerExternalId, idempotencyKey, consentCampaignId, redirectMode, successRedirectUrl, declineRedirectUrl, isSandbox, createdAt y updatedAt.

Parámetros de consulta opcionales

Devuelve el paquete completo de una solicitud: sus entregas con resumen del destinatario, la última decisión con su desglose por permiso (cuando la actividad usa consentimiento granular) y su evidencia, y el último evento del historial.

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

Si la solicitud no existe — o si su titular fue suprimido en la organización de origen — la respuesta es 404 CONSENT_REQUEST_NOT_FOUND en ambos casos, deliberadamente indistinguibles. El resumen de un apoderado suprimido vuelve en null aunque la solicitud siga visible.

Desde tu workspace también puedes leer las solicitudes de tus campañas compartidas, aunque vivan en el colegio o en el registrador. Esas no traen el paquete completo sino la proyección shared_partner, la misma del webhook: sin nombre, RUT, contactos ni entregas. En una campaña segmentada por RUT, una solicitud sin decisión responde 404 CONSENT_REQUEST_NOT_FOUND, igual que una inexistente, para no confirmar qué RUT están en el padrón. Para leer muchas a la vez está consentimientos de un grupo compartido.

Campos destacados del paquete:

La pregunta que una plataforma se hace antes de mostrar una funcionalidad — «¿este titular tiene consentimiento para esta actividad?» — respondida en una llamada, sin recorrer el listado.

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

«Vigente» es la solicitud más reciente del titular sobre cualquier versión de la actividad que no haya sido invalidada (una recaptura o una reemisión invalida a la anterior). expiresAt es el plazo para decidir: una pending que lo pasa se informa como expired, pero un granted sigue granted aunque su campaña haya terminado. Un «sí» vale hasta que el titular lo retire o una regla lo reemplace (ver qué cambia un consentimiento otorgado). isCurrentVersion distingue una decisión sobre la versión publicada de una sobre un aviso anterior: sigue siendo válida, pero no es la versión vigente.

Titular inexistente (o suprimido en origen): 404 TARGET_SUBJECT_NOT_FOUND. Actividad inexistente: 404 PROCESSING_ACTIVITY_NOT_FOUND.

Parámetros de consulta requeridos

Campos de la respuesta

Acuña un token nuevo para una entrega de una solicitud pendiente. El anterior deja de servir en el mismo instante: una plataforma que ofrece «copiar enlace» tiene siempre un único enlace vivo. Responde 201 con el token y su vencimiento (siete días), y deja el evento de auditoría consent_delivery · portal_token_reissued con tu cuenta de partner como actor.

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

Una solicitud ya decidida, revocada, invalidada o vencida responde 409 CONSENT_REQUEST_NOT_OPEN: reemitir su enlace abriría un portal sin nada que decidir. Una entrega que no pertenece a la solicitud, 404 CONSENT_DELIVERY_NOT_FOUND; una solicitud cuyo titular fue suprimido en origen, 404 CONSENT_REQUEST_NOT_FOUND.

Esta llamada no reenvía nada: si quieres que Edugoverna vuelva a escribir al apoderado, el canal sigue siendo el de la solicitud. Sirve para el enlace que muestras tú.

Registra el retiro de un consentimiento otorgado cuando el titular te lo pidió a ti. Es la misma revocación que hace el colegio desde la Consola: la solicitud pasa a revoked, queda sellada la evidencia del retiro y se emite consent.revoked con context.revocationSource = "partner". La respuesta es la solicitud, con la misma forma que GET …/requests/:consentRequestId.

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

Qué solicitudes puedes revocar:

• En tu workspace: cualquiera de las suyas y las de tus campañas compartidas, aunque vivan en el colegio o en el registrador. La actividad es tuya y eres el responsable nombrado en el aviso.
• En la organización de un colegio: sólo las que emitió tu credencial, directas o de una campaña en línea tuya. Las del colegio responden 404 CONSENT_REQUEST_NOT_FOUND, igual que una solicitud inexistente.

Una solicitud que no está otorgada (pendiente, rechazada, vencida o anulada) responde 409 ACTIVE_CONSENT_NOT_FOUND. Revocar una ya revocada responde 200 con la solicitud tal cual y no emite otro evento, así que puedes reintentar sin miedo después de un timeout. Si el titular vuelve a otorgar después (por ejemplo en el portal de transparencia) y retira de nuevo, ese segundo retiro trae su propio consent.revoked.

El cuerpo es opcional.

Crea y publica en una sola llamada una campaña de consentimiento sobre una lista de estudiantes que viaja en el propio cuerpo (audiencia "en línea"), creando una solicitud por estudiante. De pasada puede hacer upsert del estudiante, del apoderado y del vínculo de cada entrada, con los mismos esquemas del padrón.

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

La audiencia en línea acepta hasta 100 estudiantes por llamada — la creación es síncrona y alguien espera la respuesta. Para lotes mayores, pagina: cada página es idempotente por su idempotencyKey, así que reenviar una página no duplica nada. Para campañas sobre padrones compartidos por un colegio, usa Campañas compartidas.

El procesamiento es por estudiante y tolerante a fallos: un error en una entrada no detiene el resto. Cada resultado vuelve con status created, idempotent_replay o error (con error.code y error.message); las entradas con error quedan también visibles en el embudo de la campaña. Si el correo o teléfono de una entrada ya es de otro titular de la organización, el código es SUBJECT_CONTACT_CONFLICT; en tu propio workspace el error trae además error.holderReferenceCode, el referenceCode del titular que ya lo tiene (ver padrón). Por cada solicitud creada se encolan las entregas y se emite el webhook consent.requested.

Quien ya otorgó no recibe otra solicitud. Si el titular ya tiene un granted para la misma versión de la actividad —de otra campaña, aunque esa ya haya terminado—, la entrada vuelve idempotent_replay con el consentRequestId de ese consentimiento, no se envía nada y el embudo lo muestra como «Ya otorgado». Una pending de otra campaña sí se reemplaza por la nueva, y la reemplazada emite consent.invalidated con context.invalidationReason = "superseded_by_campaign".

La actividad tiene que exigir consentimiento: si su base de licitud es otra, la llamada responde 409 CONSENT_NOT_REQUIRED antes de crear la campaña.

Usar URLs de redirección exige una conexión de partner (403 PARTNER_CONNECTION_REQUIRED en su ausencia) y que todas las URLs del lote estén en la lista de destinos permitidos — se validan completas antes de escribir nada.

Retiro sin RUT. El portal de transparencia de la organización de la campaña (/transparencia/{slug}/retirar) encuentra al titular por RUT o, si no tiene RUT registrado, por el correo de contacto que le diste: el código llega sólo a esa dirección. Un titular que creas con un seudónimo en referenceCode y un correo puede revisar y retirar su consentimiento sin pedírselo a nadie, y el comprobante de cada decisión trae el enlace a ese portal. Sin RUT ni correo no hay forma de identificarlo ahí: para ese caso, registra tú el retiro con POST …/revoke.

Atributos requeridos

Además debe venir processingActivityVersionId o processingActivityCode, igual que en la creación individual.

Atributos opcionales

Extiende o adelanta el endsAt de una campaña con audiencia en línea, también ya publicada. Las solicitudes pendientes pasan a vencer en la fecha nueva; las que ya vencieron no reviven. Al pasar la fecha nueva, el barrido marca las pendientes expired (con su consent.expired), el portal deja de aceptar decisiones y los recordatorios no se envían. La campaña sigue published: para cerrarla de inmediato usa …/close.

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

Actúa sobre las campañas creadas con POST …/consents/campaigns: en tu workspace, cualquiera de las tuyas; en la organización de un colegio conectado, solo las que creó tu cuenta de partner — las demás responden 404 CONSENT_CAMPAIGN_NOT_FOUND. Una campaña sobre padrón compartido responde 409 PARTNER_CAMPAIGN_FAMILY_MISMATCH: se gestiona en /shared-campaigns/:campaignId.

La fecha debe ser futura (422 VALIDATION_ERROR) y la campaña no puede estar cerrada (409 CONSENT_CAMPAIGN_CLOSED).

Cierra la campaña de inmediato, con la misma cascada que el botón «Cerrar campaña» de la Consola:

• las solicitudes pendientes pasan a invalidated (invalidationReason: "campaign_closed") y cada una emite consent.invalidated;
• sus enlaces dejan de abrir el formulario y no salen más recordatorios;
• la campaña queda closed y ya no se puede editar (409 CONSENT_CAMPAIGN_CLOSED).

Las decisiones ya registradas no se tocan: quien otorgó o rechazó conserva su comprobante, y un consentimiento otorgado sigue vigente hasta que se revoque. Cerrar no se deshace.

Permiso requerido: partner.consents.write · Alcance de conexión: consents:write. Mismas reglas de alcance que el PATCH. 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.

El cuerpo es opcional. La respuesta no trae conteos: cada solicitud anulada te llega por su propio consent.invalidated.