STELWebhook (Integración STEL Order PHP)

Este proyecto proporciona una solución modular y escalable en PHP para integrar tu sitio web o aplicación con STEL Order.

Incluye un Cliente API para enviar y recibir datos (Productos, Clientes, Pedidos) y un Receptor de Webhooks para recibir notificaciones (vía middleware o polling).

Características

• Modularidad: Estructura limpia separada en Servicios, Controladores y Configuración.
• Cliente API: Clase helper StelApiService para facilitar llamadas GET/POST/PUT.
• Webhook Seguro: Validación mediante Token Secreto.
• Logging: Sistema de registros integrado para depuración.
• Escalable (BBDD): Compatible con MySQL, PostgreSQL, MongoDB, etc. (Ver examples/demo_bbdd.php).
• Sin dependencias pesadas: PHP nativo, fácil de desplegar en cualquier hosting compartido o servidor dedicado.

Requisitos

• PHP 7.4 o superior.
• Extensión cURL activada.
• Acceso a la API de STEL Order (API Key).

Estructura del Proyecto

/
├── config.php          # (Privado) Tus claves API (NO SUBIR AL REPO)
├── config.example.php  # Plantilla de configuración
├── public/
│   └── index.php       # URL pública para recibir Webhooks
├── src/
│   ├── Controllers/    # Lógica de negocio (qué hacer con los datos)
│   └── Services/       # Cliente API y Logger
├── cron/
│   └── poller.php      # Script para Tareas Programadas (si no usas Zapier)
├── logs/               # Archivos de registro
└── examples/           # Ejemplos de uso para desarrolladores

Instalación

1. Clonar el repositorio:

   git clone https://github.com/tu-usuario/STELWebhook.git
   cd STELWebhook
   

2. Configurar:

   • Renombra el archivo config.example.php a config.php.
   • Edita config.php y añade tus credenciales:
     • api_key: Tu API Key de STEL Order.
     • secret_token: Una contraseña segura inventada por ti para proteger el webhook.

3. Probar:

   • Puedes ejecutar el script de ejemplo para verificar la conexión:

     php examples/uso_api.php
     

Uso

1. Conectar y obtener datos (API)

Puedes usar la clase StelApiService en cualquier parte de tu proyecto:

Consulta el Diccionario Completo: Para ver todos los métodos y cómo usarlos, lee el archivo API_REFERENCE.md.

use App\Services\StelApiService;

// Inicializar
$api = new StelApiService('TU_API_KEY', 'URL_BASE', $logger);

// Obtener listado de productos
$productos = $api->getProductos(['limit' => 10]);

// Crear un pedido (o actualizar)
$api->updatePedido($idPedido, ['status' => 'APPROVED']);

Revisa el archivo examples/uso_api.php para ver un código funcional completo.

2. Integración en tu Web (HTML/PHP, WordPress, etc.)

¿Quieres mostrar facturas o pedidos en tu "Área de Cliente"? Es muy fácil.

1. Copia la carpeta src y config.php a tu servidor.
2. En el archivo donde quieras mostrar datos (ej: mis-pedidos.php o header.php), añade:

// 1. Cargar la librería
require_once '/ruta/a/STELWebhook/config.php';
require_once '/ruta/a/STELWebhook/src/Services/LoggerService.php';
require_once '/ruta/a/STELWebhook/src/Services/StelApiService.php';

use App\Services\LoggerService;
use App\Services\StelApiService;

// 2. Iniciar conexión
$config = require '/ruta/a/STELWebhook/config.php';
$logger = new LoggerService($config['logging']['path']);
$stel = new StelApiService($config['stel_api']['api_key'], $config['stel_api']['base_url'], $logger);

// 3. ¡Listo! Pide datos y píntalos
$pedidos = $stel->get('/orders', ['limit' => 5]);

Tienes un ejemplo completo de una página web funcionando en: examples/demo_integracion_web.php

3. Recibir Webhooks

El archivo public/index.php actúa como receptor.

• URL del Webhook: https://tu-dominio.com/stel-webhook/public/index.php
• Seguridad: Debes enviar un header X-Webhook-Secret con el token que definiste en config.php.

Puedes modificar la lógica de recepción en src/Controllers/WebhookController.php.

3. Tareas Programadas (Opcional)

Si prefieres consultar cambios periódicamente en lugar de recibir avisos, configura un Cron Job que ejecute:

php /ruta/al/proyecto/cron/poller.php

Licencia

Este proyecto es de código abierto.