---
title: "Inicio rápido"
description: "De la credencial de partner a la primera respuesta: crea la conexión en la consola, consulta el padrón y recibe tu primer webhook."
url: "https://docs.edugoverna.com/inicio-rapido"
---
# 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. {{ className: 'lead' }}
La Partner API es para plataformas que actúan como encargados de tratamiento
de un colegio. Si lo que necesitas es integrar los scripts internos de tu
propio colegio, usa las [API keys de organización](/autenticacion).
## 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.
Esa pantalla vive detrás del módulo `integrations` del plan del colegio: sin
él la consola no la ofrece, y toda ruta `partner.*` responde
`403 MODULE_NOT_LICENSED`. No exige el plan mayor — se puede sumar sobre un
plan intermedio sin cambiarse de plan
([planes](https://www.edugoverna.com/precios)).
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.
```text {{ title: 'Credencial de ejemplo (keyId.secret)' }}
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`.
```bash {{ title: 'cURL' }}
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
```
```js
const response = await fetch(
`https://app.edugoverna.com/api/partner/v1/organizations/${organizationId}/directory/subjects?subjectType=student&limit=50`,
{
headers: {
Authorization: `Bearer ${process.env.EDUGOVERNA_PARTNER_KEY}`,
},
}
)
if (!response.ok) {
const { error } = await response.json()
throw new Error(`${error.code}: ${error.message}`)
}
const { subjects, meta } = await response.json()
```
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](/errores) 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).
```json {{ title: 'Respuesta (recortada)' }}
{
"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](/paginacion).
## 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`:
```json {{ title: 'Entrega de webhook' }}
{
"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:
```text {{ title: 'Encabezados de la entrega' }}
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](/autenticacion) — las cuatro puertas de acceso en detalle y las recomendaciones de manejo del secreto.
- [Paginación](/paginacion) — cursores y sincronización incremental con `since`.
- [Sujetos del padrón](/api-organizacion/sujetos) y [Consentimientos](/api-organizacion/consentimientos) — los recursos que probablemente uses primero.
- [Límites](/limites) — cuántas solicitudes puedes hacer y cómo comportarte cerca del límite.