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

  1. Qué es una extensión
  2. Quién hace qué
  3. Requisitos
  4. Paso 1: crear la extensión
  5. Paso 2: el manifiesto extension.toml
  6. Paso 3: programar la página
  7. Paso 4: probarla sin firmar
  8. Paso 5: su certificado de editor
  9. Paso 6: firmar y empaquetar
  10. Paso 7: elegir cómo distribuirla
  11. Instalación por el administrador
  12. Versiones y actualizaciones
  13. Seguridad: qué garantiza la firma
  14. Para la autoridad de la plataforma
  15. Mensajes de verificación
  16. Referencia del formato .ipdeplug
  17. Entorno de desarrollo recomendado
  18. Desarrollar con ayuda de inteligencia artificial
  19. 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

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:

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:

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:

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:

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.

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:

  1. revisa el manifiesto;
  2. calcula el SHA-256 de cada archivo;
  3. firma la lista con su clave y escribe META/;
  4. 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:

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:

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

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:

Buenas prácticas:

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:

  1. que la solicitud esté firmada con la clave que trae, es decir, que el solicitante posee la privada;
  2. que la clave raíz sea la de esta plataforma;
  3. que el id no lo use ya otro editor con otra clave (--reemplazar sólo si es la misma organización que perdió su clave);
  4. 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:

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": "…"}
]}

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/

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:

El ciclo de trabajo, desde la terminal integrada de VS Code (Ctrl+ñ):

  1. Edite paquete/web/index.html.
  2. Corra python ipdeplug.py probar . y recargue el banco de pruebas en el navegador.
  3. Mire el registro de mensajes del banco y la consola del navegador (F12).
  4. 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:

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:

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.