Saltar a contenido

Convoca SDK

Guía para desarrollar extensiones del ecosistema Convoca sin leer el código.

Arquitectura

Convoca es una plataforma: core provee la infraestructura (registro de módulos, utilidades, licencias, logs, rate limiter) y los plugins (members, enroll, gateway, shifts, publisher, assistant) son módulos registrados. Las extensiones externas se registran igual.

┌─────────────────────────────────────────────┐
│  Tu extensión (plugin independiente)        │
│  ┌───────────────────────────────────────┐  │
│  │  convoca_register_module (filtro)     │  │
│  └──────────────┬────────────────────────┘  │
└─────────────────┼───────────────────────────┘
                  ▼
┌─────────────────────────────────────────────┐
│  Convoca Core (Module_Registry)             │
│  - valida core_min / features / capabilities│
│  - llama al bootstrap                       │
│  - expone Utils, Logger, License_Manager    │
└─────────────────────────────────────────────┘

Registro de módulo

// En tu plugin principal:
add_filter( 'convoca_register_module', 'mi_ext_register' );

function mi_ext_register() {
    if ( ! class_exists( 'Convoca\\Core\\Module_Registry' ) ) {
        return array(); // core no activo — funcionas como plugin normal
    }
    return array(
        'mi-extension' => array(
            'name'         => __( 'Mi Extensión', 'mi-extension' ),
            'version'      => '1.0.0',
            'core_min'     => '2.1.0',
            'features'     => array(),      // features PRO requeridas
            'capabilities' => array(),      // capacidades requeridas
            'bootstrap'    => 'mi_ext_bootstrap',
        ),
    );
}

El core valida el contrato y llama bootstrap solo si es compatible.

API disponible para extensiones

Recurso Acceso
\Convoca\Core\Utils:: 34 helpers: DNI, fechas, rate limit, locks, notices, PDF
\Convoca\Core\Features:: detectar plugins activos (is_members_active(), etc.)
\Convoca\Core\Logger:: logging unificado
\Convoca\Core\License_Manager:: licencias y features PRO
\Convoca\Core\Module_Registry:: registro de módulos

Patrones recomendados

CPT

add_action( 'init', function () {
    register_post_type( 'mi_cpt', array(
        'label' => __( 'Mi CPT', 'mi-extension' ),
        'public' => true,
        'supports' => array( 'title', 'editor' ),
    ) );
} );

Shortcode

add_shortcode( 'mi_shortcode', function ( $atts ) {
    $atts = shortcode_atts( array( 'x' => '' ), $atts );
    return '<div>' . esc_html( $atts['x'] ) . '</div>';
} );

REST endpoint

add_action( 'rest_api_init', function () {
    register_rest_route( 'mi-extension/v1', '/dato', array(
        'methods'             => 'GET',
        'permission_callback' => '__return_true',
        'callback'            => function () {
            return rest_ensure_response( array( 'ok' => true ) );
        },
    ) );
} );

Hook público

do_action( 'mi_extension_hecho', $dato, $extra );
// Documentar en HOOKS: nombre, args, @since

Plugin de ejemplo

Hello Convoca — plantilla completa y funcional:

Convenciones

  1. Prefijos: mi_extension_* en funciones, mi-extension/ en namespaces REST
  2. Namespaces: register_rest_route( 'mi-extension/v1', ... )
  3. Escaping: nunca imprimir sin esc_html()/esc_attr()
  4. Sanitización: sanitize_text_field() en entradas
  5. Nonces: wp_verify_nonce() en POST admin
  6. Versiones: sincronizar header, constante y Stable tag

API congelada

La API pública v3.0 está congelada — los hooks, REST endpoints y shortcodes no cambian sin deprecación. El CI verifica la congelación en cada push. Referencia: docs/openapi.yaml (OpenAPI) y docs/hooks-inventario.md del repo convoca-health-check.