API REST del plugin
Esta es una referencia para desarrolladores. Si buscas cómo usar Structura en wp-admin, empieza con Recorrido del panel — esta página es para gente que escribe código contra el plugin.
El plugin de WordPress expone endpoints REST bajo el
namespace /structura/v1/channels/. Estos los consume el
SPA de React embebido en wp-admin y son utilizables desde
cualquier código PHP/JS con contexto de autenticación de
WordPress y la capacidad manage_options.
Fuente de verdad: plugin/includes/Api/Rest_Api.php.
Endpoints
| Método | Ruta | Handler | Endpoint Cloud |
|---|---|---|---|
| GET | /channels/connections | channels_list_connections() | channelsListConnections |
| POST | /channels/connections/webhook | channels_save_webhook_connection() | channelsSaveWebhookConnection |
| POST | /channels/connections/credential | channels_save_credential_connection() | channelsSaveCredentialConnection |
| DELETE | /channels/connections/{connection_key} | channels_delete_connection() | channelsDeleteConnection |
| GET | /channels/events | channels_list_events() | channelsListEvents |
| POST | /channels/oauth/init | channels_oauth_init() | channelsOAuthInit |
| GET | /channels/catalog | channels_list_catalog() | channelsListCatalog |
Todas las rutas requieren la capacidad manage_options.
Patrones de Handler
List Connections
Pasa-a-través hacia la nube. Devuelve un array de objetos
ConnectionSummary. Los secretos nunca se incluyen — el
diseño split-doc en Firestore garantiza que la colección
del cliente sea inherentemente segura.
Save Webhook Connection
Sanitiza entradas (integration_id, webhook_url,
display_name, notification_locale, opcional
connection_id para actualizaciones), después reenvía a la
nube. La nube valida la URL vía
WebhookIntegration.validateTarget() antes de cifrar y
persistir.
Save Credential Connection
Sanitiza el mapa clave/valor de la credencial (cada clave y
valor por sanitize_text_field), después reenvía. La forma
de la credencial varía por integración — el plugin no
necesita conocimiento por integración, ya que la nube
valida el esquema.
Delete Connection
Acepta o bien una UUID (conexiones nuevas) o bien una ID de integración heredada (conexiones pre-migración). La operación es idempotente — borrar una conexión inexistente devuelve éxito.
List Events
Desempaqueta la respuesta de la nube y devuelve el array crudo de eventos. El límite por defecto es 25 eventos, los más nuevos primero.
List Catalog
Pasa-a-través devolviendo el marketplace completo con
anotaciones de derechos (canInstall, blocker por
entrada).
OAuth Init
El handler más interesante. Construye la URI de
redirección OAuth a partir de la constante
STRUCTURA_API_BASE:
$cloud_base = rtrim( STRUCTURA_API_BASE, '/' );
$redirect_uri = $cloud_base . '/channelsOAuthCallback';
$result = $this->channels_connections()->init_oauth( $integration_id, $redirect_uri );Esto es necesario porque la función de callback de la nube no conoce su propio origen público en tiempo de ejecución. El plugin construye la URL completa de callback y la pasa a la nube, que la incrusta en el state de OAuth y en la URL de autorización.
Devuelve { authorizeUrl } — el cliente de React
redirige el navegador a esta URL.
Manejo de errores
Todos los handlers siguen el mismo patrón:
- Llamar al método del servicio.
- Si el resultado es un
WP_Error, devolverlo (WordPress lo convierte automáticamente en una respuesta de error REST). - Si no, envolver en
rest_ensure_response()con el código de estado apropiado.
La capa de servicio maneja todos los errores de
comunicación con la nube y los normaliza a instancias de
WP_Error con códigos de error descriptivos.