Guía de desarrollador

Publicar extensiones de terceros: id, versionado, revisión, precios, reparto 70/30 y cobro.

En esta página

Cuenta de desarrollador
Identidad: id y publisher
Archivos de una versión
Versionado
Validación y análisis estático
Flujo de revisión
Modo prueba en tu dominio
Kill switch y yank
Límites de recursos
Precios
Reparto 70/30
Cobro de tus pagos
Términos
Véase también

Esta guía explica cómo publicar una extensión de terceros en el marketplace de BloomX desde el portal /admin/developer, cómo se revisa, cómo se cobra y cuánto recibes. El contrato técnico de la extensión (manifest, permisos, handler) está en Extensiones y Crear una extensión.

Cobros opcionales

Publicar gratis no requiere PayPal. Las extensiones de pago solo funcionan si el operador configuró los pagos (Configuración de PayPal); si no, el backend responde 503 payments_not_configured.

Cuenta de desarrollador#

Tu instancia debe tener un dominio con clave Ed25519 registrada (firmado). Un dominio en modo legado recibe 403 signature_required en todas las rutas de dinero y de marketplace (Arquitectura).
Solo el dueño del dominio (nivel de permiso 4) accede al portal, y las acciones sensibles piden step-up reciente (confirmación de identidad). La instancia lo exige antes de firmar la petición; el backend confía solo en lo firmado.
Antes de publicar debes aceptar los términos del desarrollador. Se registra la versión aceptada (PAYMENTS_TERMS_VERSION); si la plataforma publica una versión nueva, debes aceptarla otra vez para seguir enviando versiones.

Identidad: id y publisher#

El id es obligatoriamente dev.<slug-del-dominio>.<nombre>. El slug es el nombre de tu dominio firmado en minúsculas con . convertido en - (acme.com pasa a acme-com). Solo puedes crear ids con tu slug.

El prefijo core- y los nombres reservados son solo de la plataforma; no se pueden usar como nombre.
El publisher es tu dominio. No puedes presentarte como otro editor ni como la plataforma.
Dos dominios distintos pueden producir el mismo slug (a-b.com y a.b.com). La primera submission fija la propiedad del id; el otro dominio recibe 409 extension_id_taken.

manifest.json

{
  "id": "dev.acme-com.resumen-diario",
  "name": "Resumen diario",
  "version": "1.0.0",
  "publisher": "acme.com",
  "permissions": ["READ_EMAIL"],
  "network": { "hosts": ["api.acme.com"] }
}

Archivos de una versión#

Archivo	Qué es
`manifest.json`	Id, nombre, versión, publisher, permisos, `network.hosts`, componentes. Se valida con el mismo esquema que el resto de extensiones.
`server.js`	El handler. Corre en el sandbox, no tiene `require`, `process` ni `eval`.
Icono	Imagen con límite de tamaño y formato validado.
`README`	Descripción que ve el revisor y que alimenta la ficha del catálogo (metadatos).

Versionado#

semver estricto X.Y.Z. Una versión enviada es inmutable: para cambiar algo envías otra.
La versión debe subir respecto a la última publicada.
El changelog es obligatorio en cada versión.
El portal sugiere patch, minor o major y muestra un diff de permisos frente a la versión anterior: pedir permisos nuevos hace que los dominios que la tienen instalada deban aprobarlos otra vez.

Validación y análisis estático#

Antes de enviar a revisión (POST /api/developer/validate desde el portal) se valida el manifest, los tamaños y se ejecuta un análisis estático consultivo. Los hallazgos error bloquean el envío; los warning e info los ve el revisor.

Red: todo host al que llame tu código debe estar declarado en network.hosts. Un comodín * solo se rechaza por demasiado amplio; *.dominio.com cubre subdominios.
Permisos de riesgo alto se señalan al revisor, y algunos permisos están prohibidos para terceros.
Tamaño máximo de server.js, manifest, icono y README (configurables por el operador).
APIs prohibidas: require, process, import, eval, new Function, fs, net, child_process...

El análisis no es la defensa

Es una primera barrera. La defensa real es el sandbox y la lista de hosts impuesta en tiempo de ejecución (sandbox); el sandbox no es una frontera fuerte frente a un atacante decidido, por eso existe la revisión humana.

Flujo de revisión#

Estados

draft -> in_review -> changes_requested -> (editar) -> in_review
                  -> approved -> published -> yanked
                  -> rejected

draft: editable. Puedes retirar (withdraw) un envío pendiente.
in_review: lo evalúa el revisor, un administrador de la plataforma, con diff de código, análisis y permisos.
changes_requested: edita y vuelve a enviar. rejected: cierra esa versión; puedes enviar una nueva con número mayor.
approved: aún no es visible; tú decides cuándo publicar (published).
Cada versión se re-revisa, también las que solo cambian un patch. Recibes un correo en cada decisión (al dueño del dominio).

Cualquier otra transición se rechaza: la máquina de estados es cerrada.

Modo prueba en tu dominio#

Mientras una extensión no está aprobada y publicada existe como extensión privada: solo tu dominio puede instalarla y ejecutarla (test-install). Nada sin aprobar llega a otros dominios. Tú no pagas por usar tu propia extensión de pago en tu dominio.

Kill switch y yank#

Puedes retirar (yank) una versión o extensión, y la plataforma puede suspenderla. Una extensión yanked o suspended no se ejecuta para nadie, ni siquiera para ti, de inmediato. Si falta el registro de la extensión de tercero, el sistema falla cerrado (no se ejecuta).

Límites de recursos#

El código de terceros corre con límites más estrictos que el de la plataforma:

Memoria del Worker reducida (48 MB de heap viejo), contexto de 2 MiB y resultado de 1 MiB.
Timeout duro de 10 s aunque el manifest pida más; 2 ejecuciones simultáneas por extensión; 30 ejecuciones por minuto por (dominio, extensión).
Presupuestos pequeños de llamadas de red y de IA por ejecución; red solo a network.hosts y sin redirecciones automáticas.

Precios#

Modelo	Detalle
Gratis	Sin cobro ni PayPal.
Pago único	Un cobro por dominio; el derecho no caduca.
Suscripción	Mensual y/o anual, con prueba gratuita de 0 a 30 días.

Los precios se validan entre un mínimo y un máximo definidos por el operador (PAYMENTS_MIN_PRICE_CENTS / PAYMENTS_MAX_PRICE_CENTS), siempre en USD y en centavos enteros.
Los planes de PayPal son inmutables: cambiar el precio crea un plan nuevo. El suscriptor actual conserva su precio hasta que apruebe el nuevo (Guía de facturación).

Reparto 70/30#

Recibes el 70 % del precio bruto; la plataforma, el 30 %. El porcentaje es configurable en el backend (PAYMENTS_DEVELOPER_SHARE_BPS, 7000 = 70 %). La comisión de PayPal la asume la plataforma (sale de su parte, no de la tuya).

Redondeo en centavos enteros

desarrollador = floor(bruto * 70%)
plataforma    = bruto - desarrollador   (el resto del redondeo es de la plataforma)

ejemplo: bruto 999 -> desarrollador 699, plataforma 300

En un reembolso la parte del desarrollador se revierte de forma proporcional (también con floor).

Cobro de tus pagos#

Vincula tu cuenta de PayPal (vincular). Sin cuenta vinculada tu saldo simplemente se acumula.
Retención de 14 días (PAYMENTS_HOLD_DAYS): hasta entonces el saldo está *retenido*; luego, *disponible*.
Hay un mínimo de pago y un máximo por pago (PAYMENTS_PAYOUT_MIN_CENTS / PAYMENTS_PAYOUT_MAX_CENTS); el resto se paga en el siguiente ciclo.
Si los reembolsos dejan el saldo negativo, se compensa con tus ventas siguientes antes de volver a pagarte.
Ves saldo, ventas y pagos en Guía de facturación.

Disponibilidad de PayPal

PayPal Payouts y Subscriptions pueden no estar disponibles para ciertas cuentas o países. Verifícalo con PayPal antes de depender de ellos (Configuración).

Términos#

Aceptas los términos vigentes desde el portal (/api/developer/terms). El software registra la versión aceptada, pero no sustituye a unos términos legales redactados por la plataforma ni resuelve tus obligaciones tributarias.

Véase también#

Guía de facturación para quien compra y para el cobro.
Configuración de PayPal para el operador.
Seguridad de pagos y marketplace: modelo de amenazas.