Inicio rápido

Esta guía te lleva desde cero hasta tu primera solicitud a la Partner API: cómo se emite la credencial, cómo se autentica una llamada, qué forma tiene la respuesta y cómo recibir tu primer evento por webhook.

Paso 1: la credencial nace en la consola del colegio

El acceso de un partner no se autoconfigura: lo habilita un administrador del colegio desde la consola, en Integraciones → Partners. Ahí se crea la conexión con tu cuenta de partner, se registran el contrato de encargo de datos (DPA) y los alcances autorizados, y se emite la credencial de API.

La credencial en texto plano tiene la forma keyId.secret y se muestra una sola vez al emitirla. Edugoverna almacena únicamente su hash SHA-256 (más un prefijo visible para identificarla en la consola), así que si se pierde no puede recuperarse: hay que revocarla y emitir una nueva.

6f1c1f0a-8b3e-4d2c-9c47-2f9a1d3e5b70.9f86d081884c7d659a2feaa0c55ad015

Guarda el valor completo en una variable de entorno o en tu gestor de secretos. En los ejemplos que siguen lo llamaremos EDUGOVERNA_PARTNER_KEY.

Paso 2: tu primera solicitud

Con la credencial emitida, ya puedes listar el padrón de titulares del colegio. Toda ruta de la Partner API lleva el identificador de la organización (el colegio) en la URL y la credencial en el encabezado Authorization: Bearer.

curl -G "https://app.edugoverna.com/api/partner/v1/organizations/{organizationId}/directory/subjects" \
  -H "Authorization: Bearer $EDUGOVERNA_PARTNER_KEY" \
  -d subjectType=student \
  -d limit=50

Para que la solicitud pase, deben cumplirse cuatro condiciones en orden: la credencial está activa y no expirada, la conexión con ese colegio está activa, el DPA está vigente, y la credencial tiene el permiso y el alcance de la ruta (partner.subjects.read sobre subjects:read). Cualquier puerta que falle responde con un código de error específico que te dice exactamente cuál fue.

Paso 3: la respuesta

La lista viene en subjects, y meta describe la proyección aplicada y la paginación. Los datos llegan bajo la proyección de partner: identidad básica y contacto completo, pero sin fecha de nacimiento, sin dirección y con el RUT reducido a metadatos (tipo y últimos 4 dígitos).

{
  "subjects": [
    {
      "id": "3f6f0a2e-…",
      "subjectType": "student",
      "referenceCode": "EST-2026-0412",
      "status": "active",
      "legalGivenNames": "Martina",
      "legalFamilyNames": "Rojas Fuentes",
      "preferredName": null,
      "birthDate": null,
      "contactType": "email",
      "contactValue": "apoderado@example.com",
      "contactMaskedValue": "a•••o@example.com",
      "identifierType": "rut",
      "identifierValue": null,
      "identifierLast4": "6789"
    }
  ],
  "meta": {
    "projection": {
      "identity": "basic",
      "contact": "full",
      "identifier": "metadata",
      "studentProfile": "redacted",
      "guardianProfile": "redacted"
    },
    "filteredRestrictedCount": 0,
    "totalMatchedCount": 412,
    "nextCursor": "eyJz…"
  }
}

Si meta.nextCursor no es null, hay más páginas: repite la solicitud agregando cursor. El detalle completo está en Paginación.

Paso 4: recibe tu primer webhook

Para no tener que consultar la API en un ciclo, registra un endpoint de webhook. Los endpoints se administran por organización en la consola (Integraciones → Webhooks): se registra una URL HTTPS, un secreto compartido y la lista de eventos habilitados (o * para todos).

Cuando un apoderado registra su decisión sobre un consentimiento, Edugoverna envía un POST con el evento consent.decision.recorded:

{
  "event": "consent.decision.recorded",
  "sourceType": "consent_request",
  "sourceId": "b9d2c1a4-…",
  "occurredAt": "2026-08-25T14:03:22.000Z",
  "data": {
    "…": "la solicitud de consentimiento, proyectada según la audiencia del endpoint"
  }
}

Cada entrega llega firmada. Verifica el HMAC-SHA256 antes de procesarla:

content-type: application/json
x-edugoverna-event: consent.decision.recorded
x-edugoverna-timestamp: 1787061802
x-edugoverna-signature: 4c1f…   # HMAC-SHA256(secreto, `${timestamp}.${cuerpo}`)

¿Qué sigue?

Ya hiciste tu primera solicitud autenticada y sabes cómo llegan los eventos. Algunos enlaces útiles para continuar:

• Autenticación — las cuatro puertas de acceso en detalle y las recomendaciones de manejo del secreto.
• Paginación — cursores y sincronización incremental con since.
• Sujetos del padrón y Consentimientos — los recursos que probablemente uses primero.
• Límites — cuántas solicitudes puedes hacer y cómo comportarte cerca del límite.