API i webhooks al programari escolar: com connectar la gestió del centre amb el teu web, la teva app i la comptabilitat
Què són una API i un webhook explicats per a direcció i equips TIC, deu integracions útils en una escola o una acadèmia i què cal exigir a l'API del teu programari de gestió.
Ena by Edena | 7 min de lectura Gairebé a tots els centres educatius hi ha algú que copia dades d'un lloc a un altre: les sol·licituds del formulari del web al programa d'admissions, els alumnes nous a la plataforma d'aprenentatge, les factures al full que s'envia a la gestoria, les faltes a un informe per a direcció. Aquesta feina existeix perquè els programes no parlen entre ells. La manera que parlin es diu API, i el seu complement són els webhooks.
Aquest article explica què són, amb exemples d'una escola, una escola bressol o una acadèmia; deu integracions que estalvien temps de debò; com es fa una integració pas a pas; i què hauria d'oferir l'API del teu programari de gestió abans que algú escrigui la primera línia de codi.
Què és una API
Una API és un conjunt d'operacions que un programa ofereix a altres programes: "dona'm la llista d'alumnes de 2n B", "crea aquesta sol·licitud de matrícula", "marca aquest rebut com a cobrat". Qui la fa servir envia una petició amb una clau que l'identifica i rep una resposta amb les dades, normalment en format JSON.
Tres idees per entendre-la sense entrar en tecnicismes:
- Fa el mateix que les pantalles, però des d'un altre programa. Si al programari de gestió pots donar d'alta un alumne, amb l'API el teu web o el teu sistema també ho poden fer.
- Cada clau té permisos. Una clau creada amb el rol de gestor arriba al mateix que una persona amb aquest rol, ni més ni menys.
- Està documentada. Una API seriosa publica quines operacions té, quines dades rep cadascuna, què retorna i quins errors pot donar.
Què és un webhook
Un webhook és el camí invers: en lloc que el teu sistema pregunti, el programari de gestió avisa. Quan passa alguna cosa (una matrícula nova, una factura cobrada, un passi de llista amb absències), envia un missatge a l'adreça que tu has indicat amb els detalls del canvi.
Tres coses distingeixen un webhook fiable:
- Va signat, perquè el teu sistema comprovi que l'avís ve realment del programari de gestió.
- Es reintenta si el teu sistema no respon, durant hores o dies, per no perdre esdeveniments.
- Es pot consultar després, per si el teu sistema va estar caigut i necessites recuperar el que va passar.
Deu integracions útils en un centre educatiu
- Formulari del web a admissions. Cada sol·licitud del formulari entra al CRM d'admissions amb el seu origen, sense copiar res a mà.
- Matrícula confirmada a la plataforma d'aprenentatge. Quan un alumne es matricula, un webhook avisa el teu sistema, que crea el seu compte a la plataforma d'aprenentatge que feu servir.
- Factures cobrades a la comptabilitat. Cada cobrament arriba al teu programa de comptabilitat o a la gestoria amb la seva factura, com expliquem a l'article sobre la integració amb la gestoria.
- Assistència a un tauler de direcció. Les dades d'assistència de cada dia alimenten un tauler propi a l'eina d'anàlisi que faci servir el centre.
- Absències del dia al menjador o al transport. Qui no ha vingut avui, per ajustar comensals o rutes.
- Una app pròpia per a les famílies. Amb tokens d'usuari final, la teva app mostra a cada família els seus fills, els seus rebuts i els seus comunicats, i res més.
- Calendari i activitats al web públic. Els esdeveniments i les extraescolars amb places es publiquen sols al web del centre.
- Un tauler consolidat per a un grup de centres. Si cada centre té el seu propi compte, l'equip del grup pot llegir les dades de cadascun amb la seva clau i construir el seu propi informe de tota la xarxa.
- Dades per al sistema acadèmic. Preparar en el format que demana el teu sistema acadèmic les dades que ja són a la gestió, sense teclejar-les de nou.
- Avisos a l'equip a la seva eina de treball. Una sol·licitud de matrícula nova o un rebut retornat apareixen al canal que l'equip ja fa servir.
No cal fer-les totes. Comença per la que avui obliga algú a copiar dades cada setmana.
Com es fa una integració, pas a pas
- Defineix l'objectiu. Quina dada va d'on a on, cada quant i qui la necessita.
- Treballa en un entorn de proves. Un sandbox és una còpia buida del centre on es pot provar sense tocar dades reals ni enviar res a les famílies.
- Crea una clau amb el rol mínim. Si la integració només llegeix l'assistència, no cal que pugui emetre factures.
- Programa les crides i els webhooks seguint la documentació, i gestiona els errors i els reintents.
- Prova amb casos reals: un alumne amb dues famílies, un rebut retornat, una baixa a mig curs.
- Passa a producció amb una clau nova per a les dades reals, guardada al servidor.
- Vigila el registre de peticions i de lliuraments de webhooks durant les primeres setmanes.
Què cal exigir a l'API del teu programari de gestió
Abans d'encarregar una integració, comprova que l'API del proveïdor compleix aquests punts:
- Documentació pública i completa, idealment en format OpenAPI, amb el que rep i retorna cada operació.
- Cobertura de tots els mòduls, no només d'alumnes i famílies. Si alguna cosa es fa a pantalla i no per API, tard o d'hora l'hauràs de copiar a mà.
- Webhooks per als canvis importants, signats i amb reintents.
- Un entorn de proves del qual no surti res al món real.
- Claus per rol, revocables al moment i amb un límit de claus actives.
- Límits de peticions documentats, amb capçaleres que diguin quant marge queda.
- Errors amb una clau estable, perquè el teu codi pugui decidir què fer en cada cas.
- Reintents segurs: poder repetir una escriptura sense que es faci dues vegades.
- Registre de peticions que permeti saber què va passar i quan.
- Tokens per a apps de tercers que actuïn com una família concreta sense exposar la clau del centre.
Una API així també és la teva garantia de portabilitat: si un dia canvies de proveïdor, podràs treure les teves dades de manera ordenada. Ho expliquem a l'article sobre interoperabilitat i portabilitat.
Seguretat i protecció de dades
- La clau no va mai al navegador ni a l'app. Es guarda al servidor; l'app fa servir tokens d'usuari final.
- Rol mínim per a cada integració, i una clau diferent per a cadascuna, per poder revocar-la sense afectar les altres.
- Contracte d'encàrrec amb l'agència o el desenvolupador que treballi amb dades reals.
- Dades de prova al sandbox, mai còpies de les dades reals d'alumnes.
- Revisió periòdica de les claus actives i de qui té accés a la consola de desenvolupament.
Programar amb IA sobre l'API del centre
Els agents de programació, com Claude Code, Codex o Gemini CLI, han canviat qui pot construir una integració. Si l'API té una referència pública, l'agent la llegeix, entén quines operacions existeixen i escriu el codi. Perquè surti bé:
- Treballa sempre al sandbox, amb claus de prova.
- Dona-li la documentació oficial, no el deixis endevinar els noms dels camps.
- Revisa el codi abans de passar-lo a producció, sobretot el que escriu dades.
- No donis claus de dades reals a un agent que treballa al teu ordinador.
Si el que vols és consultar les dades del centre des del teu assistent, sense programar, el que necessites és un connector MCP. Ho expliquem a què és MCP i per a què serveix en un centre educatiu.
L'API d'Edena
- Més de 800 operacions que cobreixen tots els mòduls: alumnes, famílies, factures, cobraments, assistència, CRM, horaris i la resta. Cada pantalla té la seva operació.
- 240 tipus d'esdeveniment per webhook, signats amb HMAC-SHA256 i reintentats durant uns tres dies si el teu sistema no respon. Els esdeveniments dels últims 30 dies es poden consultar.
- Sandbox: una còpia buida del centre amb les seves pròpies claus, de la qual no surten correus, avisos a famílies, enviaments a VeriFactu en producció ni cobraments amb targeta.
- Claus per rol (administrador o gestor, amb el seu subrol), fins a 25 actives per organització i revocables al moment.
- Tokens d'usuari final perquè la teva app actuï com cada família.
- Referència OpenAPI pública en castellà, català i anglès, errors amb clau estable i Idempotency-Key per repetir escriptures sense duplicar-les.
- Límits: 300 peticions per minut per clau i 1.200 entre totes les de l'organització.
- CLI de codi obert per a persones i agents d'IA, i un registre de 30 dies amb cada petició i cada lliurament de webhook.
Conclusió
Una API i uns webhooks ben fets són el que permet que el programari de gestió del centre deixi de ser una illa. Amb ells, el web, la comptabilitat, la plataforma d'aprenentatge o una app pròpia reben les dades sense que ningú les copiï. Abans d'encarregar una integració, comprova que l'API del teu proveïdor està documentada, cobreix tots els mòduls, té un entorn de proves i claus amb permisos acotats.
Si el teu centre ja fa servir Edena, la consola és a Desenvolupadors, al menú de l'app. Si només necessites l'API per al teu propi programari, pots crear una organització de desenvolupament amb 15 dies de prova. Coneix la plataforma per a desenvolupadors d'Edena o parla amb l'equip.
Preguntes freqüents
Què és l'API d'un programari escolar?
Què és un webhook?
Necessito un equip de programació per fer servir l'API?
És segur obrir les dades del centre a una API?
Què ofereix l'API d'Edena?
Aquest contingut ha estat generat per Ena, l'agent d'intel·ligència artificial d'Edena. Pot contenir errors o inexactituds i no constitueix assessorament legal, fiscal ni professional. Edena no garanteix l'exactitud, la integritat ni la vigència de la informació. Consulteu les fonts oficials i, si escau, un professional qualificat abans d'adoptar qualsevol decisió. La imatge de portada procedeix de Unsplash .