Primeros pasos

La API de EduPay permite que otros sistemas de la escuela — ERP, CRM, sitio web, plataforma de enseñanza, BI — lean y graben los datos de la escuela en EduPay: catálogo, alumnos, matrículas, contratos y cobros. Y avisa a esos sistemas en el momento en que algo ocurre, como un pago confirmado.

Cada clave pertenece a una escuela y solo ve los datos de esa escuela.

Qué se puede hacer#

• Consultar el catálogo (ofertas, trayectos, grupos, planes de pago y páginas de ventas), alumnos, matrículas, contratos (con el PDF) y cuotas, con los datos para pagar.
• Grabar: registrar y modificar alumnos, crear y cancelar matrículas y generar la segunda copia de una cuota. La matrícula creada por la API sigue el mismo camino que la matrícula hecha en el panel: genera las cuotas y el contrato, inscribe al alumno en Moodle y emite el cobro.
• Recibir avisos (webhooks) de alumno, matrícula, contrato y cuota, firmados para comprobar que vienen de EduPay.
• Abrir el portal del alumno con la sesión ya iniciada, desde otro sistema, con un enlace que vale una sola vez.

La integración con Moodle tiene plugin propio y rutas propias. Está descrita en Integración con Moodle.

Direcciones#

1. Activar la API y crear la clave#

Esto lo hace el titular de la cuenta de la escuela en EduPay:

1. Entre al panel y abra Integraciones → Tokens de API.
2. En el recuadro API pública (v1), haga clic en Activar API. La API viene desactivada en todas las escuelas. Moodle funciona con ella activada o desactivada.
3. Haga clic en Crear token, dele un nombre que diga dónde se va a usar la clave (ej.: "ERP Financiero") y elija los permisos. Los paquetes listos ayudan: Solo lectura o Lectura y escritura. Vea Permisos.
4. Copie la clave. Empieza con edp_ y aparece una sola vez. EduPay guarda solo una huella de ella.

Entregue la clave a quien va a hacer la integración como si fuera una contraseña. No va en un sitio web, en una aplicación de celular ni en ningún código que se ejecute en el navegador.

2. Primera llamada#

Guarde la clave en una variable y llame a /me, que responde a cualquier clave y muestra de qué escuela es:

export EDUPAY_KEY="edp_..."

curl https://edupay.estudiosite.com/api/v1/me \
  -H "Authorization: Bearer $EDUPAY_KEY"

{
  "data": {
    "school": { "name": "Colégio Modelo", "country": "BR", "currency": "BRL", "timezone": "America/Sao_Paulo" },
    "token": { "name": "ERP Financeiro", "prefix": "edp_7d2e9f01...", "scopes": ["students:read", "billing:read"], "expires_at": null }
  }
}

Si recibe 401, la clave es incorrecta, está vencida o fue revocada. Si recibe 403 con code igual a api_disabled, la API todavía está desactivada en la escuela.

3. Una consulta real#

Cuotas vencidas, 50 por página:

curl "https://edupay.estudiosite.com/api/v1/installments?status=overdue&limit=50" \
  -H "Authorization: Bearer $EDUPAY_KEY"

La respuesta trae data (la lista) y meta.next_cursor. Para la página siguiente, repita la llamada con cursor= igual a ese valor. Detalles en Errores y límites.

Reglas que valen para toda la API#

• JSON de ida y de vuelta. Las escrituras envían Content-Type: application/json.
• Dinero en centavos, como número entero, siempre con la moneda al lado ("amount": 45000, "currency": "BRL" es R$ 450,00).
• Fecha y hora en ISO 8601, en UTC (2026-11-10T13:00:00Z). Fecha sin hora (vencimiento, nacimiento) en AAAA-MM-DD.
• Errores en application/problem+json, con un code que no cambia entre versiones. Decida por el code, no por el texto.
• Idioma de los mensajes: encabezado Accept-Language con pt-BR, en o es. Sin él, portugués.
• Toda respuesta trae el encabezado X-Request-Id. Informe ese número al soporte cuando necesite ayuda con una llamada.

Probar sin afectar a la escuela#

EduPay no tiene un ambiente de pruebas separado: la clave trabaja con los datos reales de la escuela. Por eso:

• empiece con una clave solo de lectura y verifique todo antes de pedir permiso de escritura;
• antes de grabar, acuerde con la escuela un alumno y un grupo de prueba. La matrícula creada por la API emite cobros reales, como la del panel;
• use external_id e Idempotency-Key desde el primer día (vea Alumnos y matrículas). Así, repetir una solicitud nunca duplica nada.

Próximos pasos#

• Claves de acceso: cambiar la clave sin cortar la integración.
• Alumnos y matrículas: sincronizar sin duplicar.
• Avisos automáticos: saber en el momento que entró un pago.
• Referencia: todas las rutas, con ejemplos.