El SDK se podrá descargar pronto.
Guía para desarrolladores de extensiones
Cómo crear una extensión para el geoportal, firmarla con su propio certificado de editor y elegir cómo distribuirla. Una extensión es suya: usted la escribe, decide su licencia y su precio, y la publica donde quiera. La plataforma aporta la interfaz donde se abre, la verificación de la firma y, si usted lo pide, un lugar en su catálogo de extensiones con el enlace donde se adquiere.
El equipo del geoportal no desarrolla las extensiones de terceros. Tampoco las aloja ni las cobra, salvo que usted elija el catálogo y su extensión sea gratuita.
Contenido
- Qué es una extensión
- Quién hace qué
- Requisitos
- Paso 1: crear la extensión
- Paso 2: el manifiesto
extension.toml - Paso 3: programar la página
- Paso 4: probarla sin firmar
- Paso 5: su certificado de editor
- Paso 6: firmar y empaquetar
- Paso 7: elegir cómo distribuirla
- Instalación por el administrador
- Versiones y actualizaciones
- Seguridad: qué garantiza la firma
- Para la autoridad de la plataforma
- Mensajes de verificación
- Referencia del formato
.ipdeplug - Entorno de desarrollo recomendado
- Desarrollar con ayuda de inteligencia artificial
- Licencia del SDK
1. Qué es una extensión
Una extensión es un paquete firmado .ipdeplug: un ZIP con su código, un manifiesto (extension.toml) y
una carpeta META/ con la firma. El geoportal la abre en un marco aislado del panel Extensiones. Desde
ese marco sólo puede pedir a la interfaz lo que declara su manifiesto:
| Permiso | Qué puede hacer la extensión |
|---|---|
mapa.ir |
centrar el mapa en un punto (todas lo tienen) |
capas.leer |
ver la lista de capas del catálogo y del mapa, y leer sus datos en GeoJSON (WGS 84) |
capas.agregar |
añadir una capa propia al mapa; queda en el Historial como cualquier capa subida |
descargas |
guardar en el equipo del usuario un archivo que la extensión genera |
Una extensión no ve la sesión, las cookies ni el resto de la página. Tampoco ve los datos de capas que no pidió.
2. Quién hace qué
| Quién | Qué hace | Qué guarda |
|---|---|---|
| Editor (usted, su empresa o su equipo) | escribe la extensión, la firma y la distribuye | su clave privada de editor; no la entrega a nadie |
| Autoridad de la plataforma | comprueba quién es el editor y firma su certificado con la clave raíz | la clave raíz, fuera de línea |
| Administrador de cada instalación | instala, habilita o quita extensiones; verifica la firma al instalar | nada secreto |
| Usuarios del geoportal | usan las extensiones habilitadas | — |
3. Requisitos
- Python 3.11 o posterior. Con 3.9 o 3.10 hace falta también
pip install tomli. - El paquete
cryptography:pip install cryptography. - El SDK:
ipdeplug.pyyraiz_publica.txt, en la misma carpeta. Se descargan desde el panel Extensiones del geoportal (se anunciará pronto). - Un navegador para el banco de pruebas.
- Un editor de código: recomendamos Visual Studio Code (sección 17).
Todas las órdenes tienen ayuda: python ipdeplug.py --help o python ipdeplug.py ORDEN --help.
4. Paso 1: crear la extensión
python ipdeplug.py crear mi_extension --nombre "Mi extensión" --plantilla capas
Hay dos plantillas:
pagina: una página que centra el mapa en unas coordenadas. Es el mínimo.capas: lee una capa, calcula sus centroides, los añade al mapa y los descarga en CSV. Usa los cuatro permisos.
Resultado: un proyecto listo para abrir en su editor.
mi_extension/ abra esta carpeta en VS Code (code mi_extension)
AGENTS.md reglas del puente para asistentes de IA; CLAUDE.md la importa
CLAUDE.md
.vscode/extensions.json extensiones recomendadas del editor
.gitignore deja fuera la clave del editor y los paquetes generados
LEEME.md
paquete/ lo único que se firma y se distribuye
extension.toml el manifiesto
web/index.html la página que se abre en el geoportal
Las órdenes aceptan el proyecto (mi_extension) o la carpeta paquete. En paquete/ va sólo lo que irá
en el paquete: la firma cubre cada archivo y la verificación rechaza cualquier archivo añadido después.
empaquetar se niega a firmar si encuentra ahí .git, __pycache__, node_modules o archivos del sistema.
El control de versiones (git) va en la carpeta del proyecto. Para el editor y la IA, vea las secciones
17 y 18.
5. Paso 2: el manifiesto extension.toml
id = "mi_extension" # letras, números, - y _; no se puede cambiar después
nombre = "Mi extensión"
version = "1.0.0" # X.Y.Z; súbala en cada entrega
descripcion = "Qué hace, en una frase."
editor = "su_id_de_editor" # opcional; si lo pone, debe ser el de su certificado
nivel = "opcional" # las de terceros, siempre "opcional"
requiere = [] # ids de otras extensiones que deben estar habilitadas
permisos = ["mapa.ir", "capas.leer"]
[distribucion]
modo = "catalogo" # catalogo | independiente | privada
licencia = "MIT" # la que usted elija: MIT, Apache-2.0, GPL-3.0-or-later, EUPL-1.2, Propietaria…
precio = "gratuita" # gratuita | pago | suscripcion | consultar
url = "https://su-sitio.com/mi_extension" # dónde los usuarios la adquieren o descargan
soporte = "soporte@su-sitio.com" # opcional: correo o https://
[[instalar]]
accion = "mensaje"
texto = "Instalando Mi extensión"
[[habilitar]]
accion = "copiar"
desde = "web"
hacia = "{interfaz}/extensiones/mi_extension"
[[deshabilitar]]
accion = "borrar"
ruta = "{interfaz}/extensiones/mi_extension"
[[desinstalar]]
accion = "mensaje"
texto = "Mi extensión retirada"
[distribucion] es obligatoria. La sección 10 explica cada modo.
url es obligatoria salvo en el modo privada y debe empezar por https://.
Acciones. Al instalar se ejecuta [[instalar]] y luego [[habilitar]]. Pasos posibles:
| Paso | Campos | Uso |
|---|---|---|
copiar |
desde, hacia |
publicar la página: copiar web a {interfaz}/extensiones/<id> |
borrar |
ruta |
retirarla al deshabilitar |
mensaje |
texto |
dejar constancia en el resultado |
sql |
archivo |
ejecutar un .sql en la base de la plataforma (sólo en la edición con servidor) |
orden |
linea |
desactivado en la plataforma; no lo use |
No se admiten rutas absolutas ni ... Un paso sql tiene todos los permisos sobre la base: el administrador
lo revisará antes de instalar, y es razonable que lo rechace si no lo necesita.
python ipdeplug.py validar mi_extension revisa el manifiesto sin firmar.
6. Paso 3: programar la página
La página es un solo web/index.html autocontenido. En el geoportal se abre en un marco
sandbox="allow-scripts", así que:
- no ve los demás archivos del paquete: el CSS y el JavaScript van en línea, y las imágenes como
data:; - puede cargar bibliotecas desde un CDN con CORS (
cdnjs.cloudflare.com,cdn.jsdelivr.net,unpkg.com); - no tiene
localStorage, cookies ni ventanas emergentes, y no puede descargar archivos por sí misma (para eso está el permisodescargas); - se adapta al tema claro u oscuro con
prefers-color-scheme.
Las plantillas traen el cliente del puente (pedir y el objeto ipde). Cada pedido lleva un número, y la
interfaz contesta con el mismo número o con ipde.error:
const capas = await ipde.capas(); // [{id, titulo, grupo, geometria, enMapa, elementos}]
const fc = await ipde.datos(capas[0].id); // FeatureCollection en WGS 84
await ipde.agregarCapa('Resultado', fc); // {id, elementos}
await ipde.descargar('resultado.csv', texto, 'text/csv');
ipde.ir(-79.52, 8.98, 14); // lon, lat, zoom (sin respuesta)
Los mensajes son estos:
| Envía la extensión | Permiso | Responde la interfaz |
|---|---|---|
{tipo:'ipde.ir', lon, lat, zoom} |
mapa.ir |
— (centra el mapa y pone un marcador) |
{tipo:'ipde.capas?', pedido} |
capas.leer |
{tipo:'ipde.capas', pedido, capas:[…]} |
{tipo:'ipde.datos?', pedido, id} |
capas.leer |
{tipo:'ipde.datos', pedido, id, fc} |
{tipo:'ipde.capa', pedido, titulo, fc} |
capas.agregar |
{tipo:'ipde.capa.ok', pedido, id, elementos} |
{tipo:'ipde.descargar', pedido, nombre, texto, tipoMime} |
descargas |
{tipo:'ipde.descargar.ok', pedido} |
{tipo:'ipde.tamano', grande} |
— | — (amplía o reduce el marco) |
Si falta el permiso, o algo sale mal, la respuesta es {tipo:'ipde.error', pedido, error}.
Límites:
- una capa añadida tiene hasta 100 000 elementos, con geometrías en grados;
- un archivo descargado pesa hasta 50 MB;
- el paquete descomprimido pesa hasta 50 MB.
Las capas que sólo se sirven como imagen (WMS) no tienen datos: ipde.datos? responde con un error.
7. Paso 4: probarla sin firmar
python ipdeplug.py probar mi_extension
Abre un banco de pruebas en el navegador. Su página corre en el mismo marco aislado que en el geoportal. El banco responde a los mensajes con dos capas de ejemplo, aplica los permisos del manifiesto y anota cada mensaje: así se ve enseguida un permiso que falta. No hace falta certificado para probar.
8. Paso 5: su certificado de editor
Para que la plataforma instale su extensión, el paquete debe estar firmado con una clave cuyo certificado haya firmado la autoridad de la plataforma. Se pide una sola vez por editor, no por extensión.
1. Cree su clave y la solicitud (en su equipo):
python ipdeplug.py editor-solicitar --id su_empresa --nombre "Su Empresa S.A." --correo dev@su-empresa.com --sitio https://su-empresa.com
Se crea la carpeta editor_su_empresa/ con dos archivos:
publisher_private.pem: su clave privada. No la envíe, no la suba a un repositorio y haga una copia de seguridad cifrada. Quien la tenga puede firmar en su nombre.solicitud.json: lleva su identificador, su nombre, su clave pública y una prueba de que posee la clave privada. No contiene nada secreto.
2. Envíe solicitud.json al administrador de la plataforma. Puede acompañarla de una propuesta desde el
formulario Sugerencias: elija Función nueva → Extensión propia (plugin) e indique la dirección donde se
adquirirá.
3. Reciba publisher.cert.json y guárdelo en la misma carpeta, junto a la clave privada. El certificado
dura lo que decida la autoridad: dos años por omisión.
- Si vence: sus paquetes dejan de instalarse. Pida otro certificado antes de esa fecha (puede usar la misma
clave: envíe de nuevo su
solicitud.json) y vuelva a firmar. - Si pierde la clave o se la roban: avise de inmediato a la plataforma, cree una clave nueva en otra carpeta y pida un certificado nuevo.
9. Paso 6: firmar y empaquetar
python ipdeplug.py empaquetar mi_extension --editor editor_su_empresa -o mi_extension-1.0.0.ipdeplug
empaquetar hace cuatro cosas:
- revisa el manifiesto;
- calcula el SHA-256 de cada archivo;
- firma la lista con su clave y escribe
META/; - crea el ZIP.
Al final muestra el SHA-256 del paquete. Publíquelo junto a la descarga para que se pueda comprobar.
Compruebe el resultado como lo hará la plataforma:
python ipdeplug.py verificar mi_extension-1.0.0.ipdeplug
Después de firmar, no toque la carpeta: cualquier cambio, aunque sea un espacio, invalida la firma. Para corregir algo, edite, suba la versión y vuelva a empaquetar.
10. Paso 7: elegir cómo distribuirla
La distribución se declara en [distribucion] y queda firmada dentro del paquete. El panel Extensiones la
muestra con la licencia, el precio y un botón Adquirir o Sitio que lleva a su url.
modo |
Para qué | Qué hace la plataforma | url |
|---|---|---|---|
catalogo |
que cualquier institución que use la plataforma la encuentre | la anuncia en el catálogo con su nombre, licencia, precio y enlace. Si es gratuita y usted lo pide, puede alojar el .ipdeplug para instalarla con un clic |
obligatoria |
independiente |
venderla o entregarla usted, en su sitio, su tienda o por contrato | nada más que verificar la firma cuando un administrador la instale | obligatoria |
privada |
uso interno de su organización o de un cliente concreto | nada más que verificar la firma | opcional |
Licencia. Usted la elige y es suya:
- una libre: MIT, Apache-2.0, GPL-3.0-or-later o EUPL-1.2;
- o
Propietaria, con sus propias condiciones en su sitio.
Si el paquete lleva bibliotecas de terceros, respete sus licencias e incluya sus avisos.
Precio. Puede ser gratuita, pago, suscripcion o consultar. La plataforma no cobra ni procesa pagos:
la venta y las licencias de uso ocurren en su sitio. Si quiere limitar el uso a quien pagó, hágalo en su propio
servicio (por ejemplo, con una clave de licencia que la extensión compruebe contra su servidor).
Para entrar en el catálogo, genere la ficha y envíela al administrador con el paquete:
python ipdeplug.py ficha mi_extension-1.0.0.ipdeplug -o ficha.json
La ficha resume el paquete verificado: id, versión, editor, licencia, precio, permisos, url y SHA-256. El
administrador la añade al archivo extensiones/indice.json del sitio. Si la plataforma no aloja el paquete,
la ficha va sin archivo y el catálogo sólo muestra el enlace a su sitio.
11. Instalación por el administrador
El administrador descarga el .ipdeplug desde donde usted lo distribuya y lo instala:
- en el geoportal: Administrar → Extensiones → Instalar .ipdeplug. El navegador verifica la firma, el certificado y cada archivo antes de guardarla;
- en la edición con servidor:
consola extension instalar mi_extension-1.0.0.ipdeplug, o desde la consola web.
Si algo no cuadra, el paquete se rechaza con uno de los mensajes de la sección 15, y el intento queda en la auditoría.
12. Versiones y actualizaciones
- Suba
versionen cada entrega:1.0.1para correcciones,1.1.0para funciones nuevas y2.0.0para cambios que rompen. - Instalar una versión nueva reemplaza la anterior. La auditoría guarda de qué versión a cuál se pasó.
- Si cambia los
permisos, avíselo en sus notas de versión: el administrador verá los permisos nuevos en el panel. - El
idno cambia nunca. Con otroidsería otra extensión.
13. Seguridad: qué garantiza la firma
La firma garantiza quién hizo el paquete y que nadie lo cambió después. No garantiza que la extensión sea correcta ni inocua. Por eso la plataforma añade varias barreras:
- la página corre aislada y sólo recibe lo que declaran sus permisos;
- los pasos
ordenestán desactivados, y lossqllos revisa el administrador; - un certificado vencido, o no firmado por la raíz de la plataforma, se rechaza.
Buenas prácticas:
- pida sólo los permisos que use;
- no envíe datos de capas a servidores externos sin decirlo en su descripción y en su sitio;
- escape todo texto que venga de las capas antes de insertarlo como HTML;
- custodie su clave privada.
14. Para la autoridad de la plataforma
Emitir un certificado. Primero compruebe la identidad del solicitante por un canal propio: correo de su dominio, contrato o llamada. Después:
python ipdeplug.py editor-emitir solicitud.json --raiz CARPETA_DE_LA_RAIZ --anios 2 --registro consola/firma/editores -o salida
La orden hace cuatro comprobaciones antes de firmar:
- que la solicitud esté firmada con la clave que trae, es decir, que el solicitante posee la privada;
- que la clave raíz sea la de esta plataforma;
- que el
idno lo use ya otro editor con otra clave (--reemplazarsólo si es la misma organización que perdió su clave); - que el nombre no tenga saltos de línea.
Devuelva salida/publisher.cert.json al editor. La copia en --registro es el inventario de editores.
La clave raíz (root_private.pem) se guarda fuera de línea y fuera de todo repositorio, y se usa sólo para
emitir certificados. Si se compromete, hay que generar otra raíz y recompilar la consola y el geoportal con la
nueva clave pública. Todos los certificados y paquetes anteriores dejan de valer.
Retirar a un editor. No hay lista de revocación: un certificado vale hasta su fecha de vencimiento. Por eso conviene emitirlos por uno o dos años. Ante un caso grave:
- quite sus paquetes del catálogo;
- avise a los administradores para que los desinstalen;
- no le renueve el certificado.
El catálogo es el archivo extensiones/indice.json del sitio:
{"paquetes": [
{"archivo": "conversor.ipdeplug", "id": "conversor", "nombre": "Conversor de coordenadas", "descripcion": "…"},
{"id": "mi_extension", "nombre": "Mi extensión", "version": "1.0.0", "descripcion": "…", "editor": "Su Empresa S.A.",
"licencia": "Propietaria", "precio": "pago", "url": "https://su-empresa.com/mi_extension", "sha256": "…"}
]}
- Con
archivo(sólo extensiones gratuitas alojadas por la plataforma), el administrador la instala con un clic. - Sin
archivo, el catálogo enlaza a laurldel editor.
15. Mensajes de verificación
| Mensaje | Qué significa |
|---|---|
SIN FIRMAR: falta META/… |
el paquete no se firmó o se le quitó META/ |
el certificado del editor no está firmado por la raíz de esta plataforma |
certificado de otra plataforma, de prueba o falsificado |
el certificado del editor venció el … |
pida un certificado nuevo y vuelva a firmar |
la firma del paquete no valida con la clave del editor |
se alteró META/hashes.json o se firmó con otra clave |
«archivo» fue modificado después de firmar |
se cambió un archivo tras empaquetar |
archivo no declarado en la firma / falta un archivo declarado |
se añadió o se quitó un archivo |
id del manifiesto ≠ firma / versión del manifiesto ≠ firma |
se editó extension.toml después de firmar |
el manifiesto declara otro editor |
editor en extension.toml no es el del certificado |
entrada de ZIP inválida |
rutas absolutas o con .. (se rechazan para no escribir fuera de la carpeta) |
16. Referencia del formato .ipdeplug
clave raíz --firma--> META/publisher.cert.json (certificado del editor)
clave del editor --firma--> META/hashes.json (bytes crudos del archivo)
META/hashes.json --cubre--> SHA-256 de cada archivo fuera de META/
- ECDSA P-256 con SHA-256. Las firmas van en DER y las claves públicas en SPKI DER, ambas en base64.
- Lo que firma el certificado son los bytes UTF-8 de
publisher_id\nname\npubkey\nissued\nexpires, no el JSON. META/hashes.jsonesjson.dumps({"alg":"SHA-256","files":{…}}, indent=2, sort_keys=True, ensure_ascii=False), sin salto de línea final.META/signature.jsonllevaalg,publisher_id,plugin_id,version,signed_atysig.- El ZIP lleva una carpeta raíz
<id>/.extension.tomles TOML:idyversiondeben coincidir conplugin_idyversionde la firma. ipdeplug.py,consola firmary el panel Extensiones producen y verifican exactamente lo mismo.
17. Entorno de desarrollo recomendado
Recomendamos Visual Studio Code (VS Code). Es gratuito y funciona en Windows, macOS y Linux, y edita HTML,
JavaScript, Python y TOML en un mismo sitio. Al abrir el proyecto (code mi_extension) propone instalar las
extensiones que trae .vscode/extensions.json:
| Extensión de VS Code | Para qué |
|---|---|
Python (ms-python.python) |
ejecutar ipdeplug.py y depurarlo |
Even Better TOML (tamasfe.even-better-toml) |
colores y errores al editar extension.toml |
ESLint (dbaeumer.vscode-eslint) |
errores de JavaScript mientras escribe |
Prettier (esbenp.prettier-vscode) |
formato uniforme del código |
Claude Code (anthropic.claude-code) |
asistente de IA dentro del editor (sección 18) |
Alternativas válidas:
- VSCodium: el mismo editor, compilado sin telemetría y 100 % libre.
- WebStorm o PyCharm, de JetBrains, si ya los usa.
- Cualquier editor de texto: el SDK sólo necesita Python y un navegador.
El ciclo de trabajo, desde la terminal integrada de VS Code (Ctrl+ñ):
- Edite
paquete/web/index.html. - Corra
python ipdeplug.py probar .y recargue el banco de pruebas en el navegador. - Mire el registro de mensajes del banco y la consola del navegador (F12).
- Cuando funcione, haga un commit con git y, para entregar,
empaquetar.
18. Desarrollar con ayuda de inteligencia artificial
Un asistente de IA acelera mucho una extensión: escribe la página, conecta el puente, propone pruebas y explica
errores. El proyecto ya viene preparado para eso. AGENTS.md describe al asistente:
- la estructura del proyecto y el marco aislado;
- los mensajes y permisos del puente;
- las reglas de seguridad y las órdenes del SDK.
CLAUDE.md importa ese archivo para Claude Code. GitHub Copilot, Cursor y otros asistentes leen AGENTS.md
directamente.
Con Claude Code (en la terminal o con la extensión de VS Code), abra el proyecto y pida lo que necesita en lenguaje natural. Por ejemplo:
Quiero que la extensión calcule el área de cada polígono de la capa elegida en hectáreas,
la muestre en una tabla ordenable y permita descargarla en CSV. Usa sólo los permisos necesarios
y pruébala con «python ipdeplug.py probar .».
El banco de pruebas dice «NEGADO: falta el permiso capas.agregar». Explica por qué y corrígelo.
Revisa paquete/web/index.html buscando textos de las capas que se inserten como HTML sin escapar.
Buenas prácticas:
- Pida cambios pequeños y pruébelos en el banco después de cada uno, antes de pedir el siguiente.
- Revise lo que propone. Usted firma el paquete y responde por él; la IA no.
- Nunca le dé su clave privada (
publisher_private.pem)..gitignorela deja fuera del repositorio yAGENTS.mdle prohíbe leerla. Firme usted mismo conempaquetar. - Pida que declare lo que envía fuera. Si la extensión llama a un servicio externo, que lo diga en la descripción y en su sitio.
- Tenga en cuenta las licencias del código que la IA reutilice: si copia una biblioteca, incluya su aviso de licencia.
- Actualice
AGENTS.mdcuando su extensión crezca (reglas propias, servicios que usa): es la memoria del proyecto para el asistente.
19. Licencia del SDK
El SDK (ipdeplug.py, las plantillas, el código del puente que se copia en web/index.html y AGENTS.md) se
distribuye con la licencia MIT. Puede usarlo, modificarlo e incluirlo en extensiones de cualquier licencia,
también privativas y comerciales, sin tener que publicar su código.
El núcleo de la plataforma tiene otra licencia, con copyleft: quien lo modifique debe compartir sus cambios. Pero las extensiones que sólo usan la interfaz de extensiones (el manifiesto y los mensajes del puente) quedan expresamente fuera de esa obligación.