Ogma Router — Manual para crear integraciones y acciones

Versión: 1.0
Fecha: 6 de julio de 2026
Proyecto: Ogma Router
Plugin: /home/creandot/public_html/wp-content/plugins/ogma-router

---

1. Objetivo

Este documento explica cómo añadir a Ogma:

1. Una nueva integración con un sistema externo.

2. Una o varias acciones que utilicen esa integración.

3. Un comando conversacional como:

::lubrand create demo

La arquitectura debe permitir que una integración tenga muchas acciones futuras sin duplicar configuración, autenticación, manejo HTTP, permisos ni auditoría.

---

2. Conceptos principales

2.1. Integración

Una integración representa la conexión de Ogma con un sistema externo.

Ejemplos:

perfex
lubrand
supportboard
email_intelligence

Una integración se encarga de:

• Estado activo o desactivado.

• URL base.

• Autenticación.

• Credenciales.

• Cliente HTTP.

• Prueba de conexión.

• Normalización de respuestas.

• Manejo de errores.

• Capacidades disponibles.

• Auditoría técnica.

La integración no debe contener el flujo conversacional completo.

Ejemplo:

Integración:
lubrand

Capacidades:
locations.create
locations.read
locations.update
locations.create_demo
qr.read
qr.regenerate

---

2.2. Función de Ogma

En la arquitectura actual, una función es la unidad que Ogma registra, muestra en permisos y relaciona con un comando.

Ejemplo:

Function key:
lubrand

Command code:
lubrand

Handler:
OGMA_Lubrand_Function

El usuario la invoca con:

::lubrand

La tabla de funciones determina:

function_key
name
description
type
handler
status
risk_level
requires_permission
requires_session
command_code

Los permisos actuales de Ogma se asignan principalmente a nivel de función.

---

2.3. Acción

Una acción es una operación concreta dentro de una función o integración.

Ejemplos:

lubrand.locations.create_demo
lubrand.locations.update
lubrand.locations.list
lubrand.qr.regenerate

En el estado actual de Ogma no existe todavía un catálogo genérico e independiente de acciones equivalente al registro de funciones.

Por lo tanto, el patrón recomendado es:

Comando
    ↓
Función de Ogma
    ↓
Despachador de acciones
    ↓
Clase de acción
    ↓
Cliente de integración
    ↓
API externa

Ejemplo:

::lubrand create demo
    ↓
OGMA_Lubrand_Function
    ↓
OGMA_Lubrand_Create_Demo_Action
    ↓
OGMA_Lubrand_Client
    ↓
POST /locations

---

2.4. Comando

El comando es solamente una forma explícita de solicitar una función o acción.

El prefijo predeterminado es:

::

Es configurable desde Ogma.

El parser separa:

Comando:
lubrand

Argumentos:
create demo

No se debe colocar toda la lógica de negocio en el parser ni en el router principal.

---

3. Arquitectura general

El flujo actual de Ogma es:

Webhook o consola
    ↓
OGMA_Inbound_Controller
    ↓
Normalización del mensaje
    ↓
OGMA_Router
    ↓
OGMA_Command_Parser
    ↓
OGMA_Function_Registry
    ↓
OGMA_Permission_Manager
    ↓
Función registrada
    ↓
Integración o servicio
    ↓
OGMA_Response
    ↓
Support Board, WhatsApp o consola

Cuando existe una sesión activa:

Mensaje normal
    ↓
Sesión activa del usuario
    ↓
Función propietaria de la sesión

Los siguientes comandos globales permanecen disponibles durante una sesión:

::help
::functions
::status
::close

---

4. Principios obligatorios

4.1. Separación de responsabilidades

La función conversa con el usuario.

La acción valida y ejecuta una operación.

El cliente de integración habla con la API externa.

La interfaz administrativa configura la integración.

El router únicamente enruta, valida permisos y mantiene sesiones.

---

4.2. No duplicar credenciales

Las credenciales pertenecen a Ogma.

No deben copiarse innecesariamente en:

• Funciones.

• Acciones.

• JavaScript.

• Mensajes de WhatsApp.

• Logs.

• Metadatos de sesión.

• Archivos .env de otros servicios.

Cuando un backend local necesite las credenciales, debe obtenerlas mediante un endpoint interno service-config, protegido con:

X-Ogma-Service-Token: [TOKEN INTERNO]

---

4.3. Nunca registrar secretos en logs

No registrar:

Bearer tokens
API keys
Contraseñas
Service-config tokens
Payloads con credenciales
Respuestas que devuelvan secretos

Los eventos de auditoría pueden guardar:

integration_key
action_key
status
HTTP status
duración
identificador externo
error_code
usuario
sesión
fecha

---

4.4. Las acciones de escritura requieren confirmación

Una acción que crea, modifica, elimina, envía o publica información debe mostrar una vista previa antes de ejecutarse.

Ejemplos:

Crear location
Editar cliente
Enviar campaña
Cerrar ticket
Eliminar registro
Crear tarea

La confirmación debe mostrar cada campo en una línea independiente.

---

4.5. Ejecuciones idempotentes

Repetir accidentalmente una solicitud no debe crear duplicados silenciosos.

Cada acción debe definir:

Idempotency key
External unique key
Duplicate behavior
Retry behavior

Ejemplo para Lubrand:

code:
lubrand-panka-bistro-miraflores

Si ese código ya existe, Ogma debe informar el conflicto. No debe generar automáticamente:

lubrand-panka-bistro-miraflores-2

salvo que exista una decisión explícita del usuario.

---

5. Estructura recomendada de archivos

Para una integración llamada lubrand:

includes/
├── integrations/
│   └── lubrand/
│       ├── class-ogma-lubrand-client.php
│       └── class-ogma-lubrand-normalizer.php
│
├── functions/
│   └── lubrand/
│       └── class-ogma-lubrand-function.php
│
├── actions/
│   └── lubrand/
│       ├── class-ogma-lubrand-create-demo-action.php
│       ├── class-ogma-lubrand-update-location-action.php
│       └── class-ogma-lubrand-list-locations-action.php
│
├── core/
│   ├── class-ogma-settings.php
│   ├── class-ogma-function-registry.php
│   └── class-ogma-action-detector.php
│
├── api/
│   └── class-ogma-service-config-controller.php
│
├── admin/pages/
│   └── page-integrations.php
│
└── install/
    └── class-ogma-activator.php

La carpeta includes/actions/ es la convención recomendada para las nuevas integraciones con muchas operaciones.

Todavía no representa un registro global de acciones; inicialmente las clases serán despachadas por la función principal de la integración.

---

6. Crear una integración

Paso 1. Definir el contrato

Antes de escribir código, documentar:

Integration key:
lubrand

Nombre:
Lubrand

Proveedor:
Lubrand

Base URL:
https://luvrand.com/wp-json/lubrand/v1

Autenticación:
Bearer token

Estado inicial:
disabled

Capacidades iniciales:
locations.create_demo

Timeout:
20 segundos

También debe definirse:

Qué endpoint prueba la conexión
Qué respuestas se consideran exitosas
Qué errores puede devolver
Qué campos contienen secretos
Qué identificadores son únicos
Qué acciones modifican información

---

Paso 2. Registrar las opciones

Archivo:

includes/core/class-ogma-settings.php

Todas las opciones de integraciones deben usar:

OGMA_Settings::OPTION_GROUP_INTEGRATIONS

No deben mezclarse con el grupo general de ajustes del router.

Ejemplo:

register_setting(
    self::OPTION_GROUP_INTEGRATIONS,
    'ogma_lubrand_status',
    array(
        'type'              => 'string',
        'sanitize_callback' => array(
            __CLASS__,
            'sanitize_integration_status',
        ),
        'default'           => 'disabled',
    )
);

register_setting(
    self::OPTION_GROUP_INTEGRATIONS,
    'ogma_lubrand_base_url',
    array(
        'type'              => 'string',
        'sanitize_callback' => 'esc_url_raw',
        'default'           => '',
    )
);

register_setting(
    self::OPTION_GROUP_INTEGRATIONS,
    'ogma_lubrand_auth_token',
    array(
        'type'              => 'string',
        'sanitize_callback' => array(
            __CLASS__,
            'sanitize_lubrand_token',
        ),
        'default'           => '',
    )
);

register_setting(
    self::OPTION_GROUP_INTEGRATIONS,
    'ogma_lubrand_demo_brand_id',
    array(
        'type'              => 'integer',
        'sanitize_callback' => 'absint',
        'default'           => 1,
    )
);

---

Paso 3. Proteger el token en el formulario

Cuando el formulario muestre:

********

el sanitizador debe conservar el token existente.

Ejemplo:

public static function sanitize_lubrand_token(
    $value
): string {
    $value = trim( (string) $value );

    if ( $value === '********' ) {
        return trim(
            (string) get_option(
                'ogma_lubrand_auth_token',
                ''
            )
        );
    }

    return sanitize_text_field( $value );
}

No mostrar el token real después de haber sido guardado.

---

Paso 4. Crear un método de configuración normalizada

En OGMA_Settings:

public static function get_lubrand_config(): array {
    $status = self::sanitize_integration_status(
        get_option(
            'ogma_lubrand_status',
            'disabled'
        )
    );

    return array(
        'enabled' => $status === 'active',
        'status'  => $status,
        'base_url' => rtrim(
            trim(
                (string) get_option(
                    'ogma_lubrand_base_url',
                    ''
                )
            ),
            '/'
        ),
        'auth_token' => trim(
            (string) get_option(
                'ogma_lubrand_auth_token',
                ''
            )
        ),
        'demo_brand_id' => absint(
            get_option(
                'ogma_lubrand_demo_brand_id',
                1
            )
        ),
    );
}

Las funciones y acciones no deben consultar opciones individuales repetidamente.

Deben usar:

OGMA_Settings::get_lubrand_config();

---

Paso 5. Añadir valores predeterminados

Archivo:

includes/install/class-ogma-activator.php

Añadir las opciones sin sobrescribir instalaciones existentes:

$defaults = array(
    'ogma_lubrand_status'        => 'disabled',
    'ogma_lubrand_base_url'      =>
        'https://luvrand.com/wp-json/lubrand/v1',
    'ogma_lubrand_auth_token'    => '',
    'ogma_lubrand_demo_brand_id' => 1,
);

foreach ( $defaults as $option => $value ) {
    if ( get_option( $option, null ) === null ) {
        add_option( $option, $value );
    }
}

La activación debe ser idempotente.

Activar o actualizar el plugin nunca debe borrar una configuración existente.

---

Paso 6. Añadir la interfaz administrativa

Archivo:

includes/admin/pages/page-integrations.php

Agregar una sección:

Lubrand

Estado:
Active / Disabled

Base URL:
[...]

Bearer token:
********

Demo Brand ID:
1

Test connection:
[Button]

Reglas:

• Usar el grupo ogma_router_integrations.

• Mostrar el token enmascarado.

• No imprimir el token en HTML oculto.

• No enviar el token al navegador mediante JavaScript.

• Validar manage_options.

• Usar nonce para acciones administrativas.

• Mostrar errores de conexión sin exponer respuestas sensibles.

---

Paso 7. Registrar la integración en el catálogo

Ogma ya posee una tabla de integraciones con:

integration_key
name
provider
status
settings_json
created_at
updated_at

Debe existir una fila:

integration_key:
lubrand

name:
Lubrand

provider:
lubrand

status:
configured o active

settings_json debe contener únicamente metadatos no sensibles:

{
  "capabilities": [
    "locations.create_demo"
  ],
  "auth_type": "bearer",
  "api_type": "wordpress-rest"
}

No guardar el token dentro de settings_json.

integration_key es único, por lo que la instalación debe hacer un upsert y no crear duplicados.

---

Paso 8. Crear el cliente de integración

Archivo:

includes/integrations/lubrand/class-ogma-lubrand-client.php

Responsabilidades:

Leer la configuración normalizada
Validar si la integración está activa
Construir URLs
Añadir autenticación
Ejecutar solicitudes HTTP
Decodificar JSON
Normalizar errores
Aplicar timeout
No registrar secretos

Contrato recomendado:

class OGMA_Lubrand_Client {

    public function is_configured(): bool;

    public function test_connection(): array;

    public function create_location(
        array $payload
    ): array;

    private function request(
        string $method,
        string $path,
        array $body = array()
    ): array;
}

Respuesta normalizada:

array(
    'ok'          => true,
    'http_status' => 201,
    'data'        => array(),
    'error_code'  => '',
    'message'     => '',
);

En caso de error:

array(
    'ok'          => false,
    'http_status' => 409,
    'data'        => array(),
    'error_code'  => 'location_code_exists',
    'message'     => 'Ya existe un location con ese código.',
);

---

Paso 9. Ejecutar HTTP de forma segura

Ejemplo conceptual:

$response = wp_remote_request(
    $url,
    array(
        'method'  => $method,
        'timeout' => 20,
        'headers' => array(
            'Authorization' =>
                'Bearer ' . $config['auth_token'],
            'Content-Type' =>
                'application/json',
            'Accept' =>
                'application/json',
        ),
        'body' => wp_json_encode( $body ),
    )
);

Validar:

WP_Error
HTTP status
Body vacío
JSON inválido
Respuesta inesperada
Timeout
Error 401
Error 403
Error 404
Error 409
Error 422
Error 429
Error 500+

Nunca devolver directamente al usuario todo el body técnico de una API.

---

Paso 10. Cargar las clases

Archivo principal:

ogma-router.php

Agregar:

includes/integrations/lubrand/class-ogma-lubrand-client.php
includes/functions/lubrand/class-ogma-lubrand-function.php
includes/actions/lubrand/class-ogma-lubrand-create-demo-action.php

El orden debe ser:

Cliente
Acción
Función
Router

Las dependencias deben estar cargadas antes de instanciar la función.

---

Paso 11. Service-config opcional

Solo es necesario cuando un servicio backend separado necesita utilizar la integración.

Endpoint sugerido:

GET /wp-json/ogma-router/v1/service-config/lubrand
X-Ogma-Service-Token: [TOKEN INTERNO]

Respuesta:

{
  "enabled": true,
  "status": "active",
  "base_url": "https://luvrand.com/wp-json/lubrand/v1",
  "auth_token": "[TOKEN]",
  "demo_brand_id": 1
}

Este endpoint:

• Es exclusivamente server-to-server.

• No debe consumirse desde JavaScript.

• No debe aparecer en respuestas de WhatsApp.

• Debe reutilizar el permission_check existente.

• Debe usar comparación segura del token.

• No debe escribir credenciales en logs.

Si Ogma PHP llama directamente a Lubrand, este endpoint no es necesario para esa acción.

---

7. Crear una función para la integración

Paso 1. Definir la función

Para agrupar todas las acciones de Lubrand:

Function key:
lubrand

Command code:
lubrand

Handler:
OGMA_Lubrand_Function

Risk level:
medium

Requires permission:
yes

Requires session:
no

Aunque la función no requiera una sesión permanente, algunas acciones sí pueden abrir sesiones temporales de captura y confirmación.

---

Paso 2. Crear el archivo

includes/functions/lubrand/class-ogma-lubrand-function.php

La interfaz actual de funciones recibe el contexto y devuelve un OGMA_Response.

Estructura mínima:

class OGMA_Lubrand_Function
    implements OGMA_Function_Interface {

    public function handle(
        array $context
    ): OGMA_Response {
        $args = trim(
            (string) (
                $context['args'] ?? ''
            )
        );

        $active_session =
            $context['active_session']
            ?? null;

        if ( is_array( $active_session ) ) {
            return $this->handle_session(
                $context,
                $active_session
            );
        }

        return $this->dispatch(
            $args,
            $context
        );
    }
}

---

Paso 3. Registrar la función

La función debe registrarse en dos lugares:

Código

En:

includes/core/class-ogma-function-registry.php

Relacionar:

function_key:
lubrand

handler:
OGMA_Lubrand_Function

Base de datos

En:

includes/install/class-ogma-activator.php

Añadir una fila idempotente:

array(
    'function_key'        => 'lubrand',
    'name'                => 'Lubrand',
    'description'         =>
        'Creates and manages Lubrand locations, demos and QR resources.',
    'type'                => 'integration',
    'handler'             =>
        'OGMA_Lubrand_Function',
    'status'              => 'active',
    'risk_level'          => 'medium',
    'requires_permission' => 1,
    'requires_session'    => 0,
    'command_code'        => 'lubrand',
)

La función aparecerá en:

Ogma → Functions
Ogma → Users & Numbers → Function permissions
::functions
::help

---

8. Crear acciones

8.1. Convención de nombres

Usar claves jerárquicas:

<integración>.<recurso>.<operación>

Ejemplos:

lubrand.locations.create_demo
lubrand.locations.create
lubrand.locations.update
lubrand.locations.list
lubrand.qr.get
lubrand.qr.regenerate

No usar claves ambiguas como:

create
run
demo
location_action

---

8.2. Contrato de una acción

Toda acción debe definir:

Action key
Nombre
Descripción
Integración
Capacidad requerida
Nivel de riesgo
Requiere confirmación
Campos obligatorios
Campos opcionales
Regla de idempotencia
Resultado esperado
Eventos de auditoría

Ejemplo:

Action key:
lubrand.locations.create_demo

Integración:
lubrand

Nivel de riesgo:
medium

Confirmación:
required

Campo obligatorio:
name

Campos opcionales:
google_maps_url
tripadvisor_url

Idempotencia:
location code

Resultado:
location y dos QR

---

8.3. Clase de acción recomendada

Archivo:

includes/actions/lubrand/class-ogma-lubrand-create-demo-action.php

Contrato recomendado:

class OGMA_Lubrand_Create_Demo_Action {

    public function key(): string {
        return 'lubrand.locations.create_demo';
    }

    public function risk_level(): string {
        return 'medium';
    }

    public function requires_confirmation(): bool {
        return true;
    }

    public function prepare(
        array $input,
        array $context
    ): array;

    public function execute(
        array $prepared,
        array $context
    ): array;
}

Este contrato es una convención para nuevas acciones. Todavía no existe como interfaz global obligatoria en Ogma.

---

8.4. Despachar la acción desde la función

La función interpreta:

::lubrand create demo

Como:

Action:
lubrand.locations.create_demo

Ejemplo conceptual:

private function dispatch(
    string $args,
    array $context
): OGMA_Response {
    $normalized = strtolower( trim( $args ) );

    if (
        preg_match(
            '/^(create|crear)\s+demo$/u',
            $normalized
        )
    ) {
        return $this->start_create_demo(
            $context
        );
    }

    if (
        preg_match(
            '/^(help|ayuda)$/u',
            $normalized
        )
    ) {
        return $this->help();
    }

    return $this->help(
        'lubrand_command_not_recognized'
    );
}

Debe aceptar español e inglés cuando corresponda:

::lubrand create demo
::lubrand crear demo

---

9. Acciones con varios pasos

Para acciones conversacionales se debe usar OGMA_Session_Manager.

Una sesión activa captura los siguientes mensajes normales del usuario y los dirige a la misma función.

Flujo recomendado

::lubrand create demo
    ↓
Solicitar nombre
    ↓
Guardar borrador
    ↓
Solicitar enlaces opcionales
    ↓
Mostrar confirmación
    ↓
Confirmar o cancelar
    ↓
Ejecutar API
    ↓
Cerrar sesión

---

9.1. Abrir sesión

Ejemplo conceptual:

$session_id = $sessions->open_session(
    $user_channel,
    'lubrand',
    'Create Lubrand demo',
    'Collect and confirm the demo location data.'
);

---

9.2. Guardar metadatos

Guardar únicamente información necesaria para continuar el flujo:

$sessions->update_session_metadata(
    $session_id,
    array(
        'mode' => 'lubrand_create_demo',
        'step' => 'awaiting_name',
        'action_key' =>
            'lubrand.locations.create_demo',
        'draft' => array(),
    )
);

No guardar:

Bearer token
Credenciales
Headers HTTP
Respuestas completas sensibles

---

9.3. Estados sugeridos

awaiting_name
awaiting_optional_links
awaiting_confirmation
executing
completed
cancelled
failed

---

9.4. Cancelación

Aceptar:

cancelar
cancel
no
salir
::close

La sesión debe cerrarse y auditarse.

Respuesta:

Creación de demo cancelada.

No se creó ningún location.

---

10. Confirmaciones

10.1. Presentación vertical

Ejemplo:

CREAR DEMO EN LUBRAND

Nombre:
Panka Bistro Miraflores

Código:
lubrand-panka-bistro-miraflores

Dirección:
Panka Bistro Miraflores

Google Maps:
No agregado

TripAdvisor:
No agregado

Mesas:
2

Estado:
Activo

Opciones:

1. Confirmar
2. Cancelar

También aceptar:

confirmar
confirm
sí
si
cancelar
cancel

---

10.2. No ejecutar antes de confirmar

La llamada externa debe ocurrir únicamente después de recibir una confirmación válida.

Antes de confirmar solamente se puede:

Validar
Normalizar
Preparar payload
Mostrar vista previa
Guardar borrador temporal

---

10.3. Edición antes de confirmar

Cuando sea necesario, permitir cambios como:

cambiar nombre a Panka Bistro San Isidro
agregar google maps https://...
quitar tripadvisor

Después de editar, Ogma debe volver a mostrar la vista previa completa.

---

11. Permisos

El modelo actual controla permisos a nivel de función:

can_view
can_execute
can_manage
requires_challenge
status

Para la primera versión:

Function permission:
lubrand

Permite:
ejecutar las acciones habilitadas de Lubrand

Las acciones sensibles deben añadir validaciones internas.

Ejemplo:

lubrand.locations.list:
can_execute

lubrand.locations.create_demo:
can_execute

lubrand.locations.delete:
can_manage + confirmación reforzada

Hasta que exista un catálogo formal de permisos por acción, la función debe validar:

Rol de Ogma
can_execute
can_manage
Integración activa
Capacidad habilitada
Contexto del usuario

No se debe asumir que tener acceso a ::lubrand permite automáticamente cualquier acción futura.

---

12. Auditoría

Cada acción debe generar eventos diferenciados.

Ejemplo para create_demo:

lubrand_create_demo_started
lubrand_create_demo_name_collected
lubrand_create_demo_optional_links_collected
lubrand_create_demo_confirmation_requested
lubrand_create_demo_cancelled
lubrand_create_demo_executed
lubrand_create_demo_failed

Campos recomendados:

OGMA_Audit_Service::record(
    array(
        'wp_user_id' =>
            $context['user_channel']['wp_user_id']
            ?? null,
        'user_channel_id' =>
            $context['user_channel']['id']
            ?? null,
        'inbound_message_id' =>
            $context['inbound_message_id']
            ?? null,
        'master_session_id' =>
            $session_id,
        'function_key' =>
            'lubrand',
        'action' =>
            'lubrand_create_demo_executed',
        'risk_level' =>
            'medium',
        'status' =>
            'success',
        'channel' =>
            $context['normalized']['channel']
            ?? '',
        'metadata' => array(
            'action_key' =>
                'lubrand.locations.create_demo',
            'location_id' =>
                $location_id,
            'location_code' =>
                $location_code,
        ),
    )
);

No colocar en metadata:

auth_token
Authorization header
Cookies
Contraseñas
Payloads sensibles completos

---

13. Respuestas

Las funciones deben devolver OGMA_Response.

Ejemplo:

return OGMA_Response::reply(
    $message,
    'lubrand_demo_created'
);

El código de respuesta debe ser estable y apto para:

WhatsApp
Support Board
Consola web
Pruebas automatizadas
Auditoría

No usar el texto visible como único indicador del resultado.

---

14. Acción de lenguaje natural

Ogma posee OGMA_Action_Detector para interpretar solicitudes sin prefijo.

Ejemplo futuro:

Créame una demo de Lubrand para Panka Bistro

El detector puede proponer:

lubrand.locations.create_demo

Pero debe implementarse en este orden:

1. Cliente de integración
2. Acción
3. Comando explícito
4. Sesión y confirmación
5. Pruebas
6. Detección por lenguaje natural

Nunca comenzar por la detección natural.

El comando explícito debe funcionar primero:

::lubrand create demo

---

15. Ejemplo completo: Lubrand create demo

Entrada

::lubrand create demo

Ogma

¿Cuál es el nombre del local para la demo?

Usuario

Panka Bistro Miraflores

Datos automáticos

name:
Panka Bistro Miraflores

code:
lubrand-panka-bistro-miraflores

address:
Panka Bistro Miraflores

brand_id:
1

tables_count:
2

status:
1

Ogma

Si quieres agregar Google Maps o TripAdvisor, copia los links ahora.

También puedes decir “no gracias” para ignorarlos.

Usuario

no gracias

Confirmación

CREAR DEMO EN LUBRAND

Nombre:
Panka Bistro Miraflores

Código:
lubrand-panka-bistro-miraflores

Dirección:
Panka Bistro Miraflores

Google Maps:
No agregado

TripAdvisor:
No agregado

Mesas:
2

Estado:
Activo

1. Confirmar
2. Cancelar

Ejecución

La acción prepara:

{
  "name": "Panka Bistro Miraflores",
  "code": "lubrand-panka-bistro-miraflores",
  "address": "Panka Bistro Miraflores",
  "google_maps_url": "",
  "tripadvisor_url": ""
}

La integración ejecuta:

POST /locations
Authorization: Bearer [REDACTED]
Content-Type: application/json

Respuesta

DEMO CREADA CORRECTAMENTE

Local:
Panka Bistro Miraflores

MESA 1

QR:
[QR o URL de la Mesa 1]

MESA 2

QR:
[QR o URL de la Mesa 2]

Información secundaria:

Código:
lubrand-panka-bistro-miraflores

Location ID:
123

Enlace Mesa 1:
[...]

Enlace Mesa 2:
[...]

---

16. Manejo de errores

Integración desactivada

La integración Lubrand no está activa.

Un administrador debe configurarla en:
Ogma → Integrations

Token ausente

La integración Lubrand está incompleta.

Falta configurar la autenticación.

No autorizado

No tienes permiso para crear demos en Lubrand.

Código duplicado

No se creó la demo.

Ya existe un location con el código:
lubrand-panka-bistro-miraflores

Timeout

Lubrand no respondió dentro del tiempo esperado.

No se pudo confirmar la creación del location.

Ante un timeout no se debe afirmar automáticamente que el registro no fue creado. Debe existir una verificación posterior por código antes de reintentar.

Respuesta inválida

Lubrand respondió, pero Ogma no pudo validar el resultado.

La operación quedó registrada para revisión.

Creación parcial

Si Lubrand crea el location pero no devuelve los dos QR:

El location fue creado, pero la respuesta no incluyó todos los QR esperados.

Location ID:
123

QR encontrados:
1 de 2

No ocultar una ejecución parcial.

---

17. Prueba de conexión

La prueba debe comprobar:

Integración activa
URL válida
Token presente
Resolución DNS
Conexión HTTPS
Autenticación
Respuesta JSON válida
Acceso al recurso esperado

Respuesta administrativa:

LUBRAND CONNECTION TEST

Status:
Connected

HTTP:
200

Base URL:
https://luvrand.com/wp-json/lubrand/v1

Authentication:
Accepted

Capabilities:
locations.create_demo

Nunca mostrar el token.

---

18. Checklist de implementación

Integración

• Definir integration_key.

• Definir URL base.

• Definir autenticación.

• Registrar opciones.

• Crear sanitizadores.

• Enmascarar secretos.

• Añadir valores predeterminados.

• Añadir interfaz administrativa.

• Registrar fila en integrations.

• Crear cliente HTTP.

• Crear prueba de conexión.

• Añadir auditoría.

• Cargar clases en ogma-router.php.

• Añadir service-config solo cuando sea necesario.

Función

• Crear handler.

• Implementar OGMA_Function_Interface.

• Registrar handler en el registry.

• Sembrar fila en functions.

• Definir command_code.

• Definir riesgo.

• Definir permisos.

• Añadir ayuda.

• Verificar aparición en ::functions.

Acción

• Definir action_key.

• Definir campos obligatorios.

• Definir campos opcionales.

• Definir normalización.

• Definir idempotencia.

• Definir confirmación.

• Definir estados de sesión.

• Definir ejecución.

• Definir respuesta normalizada.

• Definir eventos de auditoría.

• Definir errores y recuperación.

• Añadir detección natural únicamente al final.

---

19. Checklist de pruebas

Código

PHP lint
Carga de clases
Activación idempotente
Actualización sin pérdida de opciones
Sin warnings ni notices

Configuración

Guardar estado
Guardar URL
Guardar token
Conservar token al mostrar ********
No borrar otras integraciones al guardar

Seguridad

Token ausente en logs
Token ausente en HTML
Token ausente en respuestas
Nonce administrativo
manage_options
Service-config protegido

Permisos

Usuario sin permiso
Usuario con can_view
Usuario con can_execute
Usuario con can_manage
Usuario bloqueado
Integración desactivada

Conversación

Comando sin argumentos
Nombre válido
Nombre vacío
Enlaces opcionales
No gracias
Confirmar
Cancelar
::close
Sesión expirada
Comando nuevo durante sesión activa

API

200
201
400
401
403
404
409
422
429
500
Timeout
JSON inválido
Body vacío
Respuesta parcial

Idempotencia

Código existente
Doble confirmación
Reenvío del mismo webhook
Timeout con creación remota exitosa
Reintento después de error

Canales

Consola web
Support Board
WhatsApp
Respuesta con dos QR
Links clicables
Presentación vertical

---

20. Criterio de cierre

Una integración se considera lista cuando:

Puede configurarse desde Ogma
Puede activarse y desactivarse
Puede probar su conexión
No expone credenciales
Tiene cliente normalizado
Tiene auditoría
Puede ser reutilizada por varias acciones

Una acción se considera lista cuando:

Tiene una clave estable
Tiene permisos
Valida entradas
Usa confirmación cuando escribe
Es idempotente
Usa el cliente de la integración
Maneja errores
Cierra correctamente su sesión
Devuelve una respuesta estructurada
Genera auditoría
Funciona con comando explícito

---

21. Regla arquitectónica final

No implementar:

::lubrand create demo
    ↓
Llamada HTTP escrita directamente dentro del router

Implementar:

::lubrand create demo
    ↓
OGMA_Lubrand_Function
    ↓
OGMA_Lubrand_Create_Demo_Action
    ↓
OGMA_Lubrand_Client
    ↓
Lubrand API

Esto permitirá añadir posteriormente:

::lubrand locations
::lubrand location 123
::lubrand update location 123
::lubrand regenerate qr 123 table 2
::lubrand create campaign
::lubrand campaign status 45

sin volver a implementar configuración, autenticación, conexión, normalización, auditoría ni manejo general de errores.