Plantilla de Pasarela

La Plantilla de Pasarela de WooCommerce proporciona un punto de partida para crear tus propias pasarelas de pago personalizadas para WooCommerce POS. Esta plantilla incluye todo el código y la estructura necesarios para construir una pasarela de pago totalmente funcional.

Características

• Plantilla Completa: Estructura de pasarela lista para usar con todos los métodos requeridos
• Integración POS: Preconfigurada para compatibilidad con WooCommerce POS
• Configuración Automatizada: Personalización de la plantilla basada en scripts
• Mejores Prácticas: Sigue los estándares de codificación de WordPress y WooCommerce
• Extensible: Fácil de modificar y extender para proveedores de pagos específicos

Empezando

Opción 1: Generación Automatizada de Plantillas

La plantilla incluye un script que personaliza automáticamente la plantilla para tu pasarela específica:

1. Clona el Repositorio:

   git clone https://github.com/wcpos/woocommerce-gateway-template.git
   cd woocommerce-gateway-template

2. Ejecuta el Script de Configuración:

   ./create-gateway.sh

3. Sigue las Indicaciones:

   • Introduce el nombre de tu pasarela (por ejemplo, "Mi Pasarela de Pago")
   • Introduce un slug para la pasarela (por ejemplo, "mi-pago")
   • Proporciona una descripción
   • El script generará un plugin personalizado

Opción 2: Uso Manual de la Plantilla

Si prefieres la personalización manual:

1. Descarga la Plantilla:

   • Visita el repositorio de Plantilla de Pasarela
   • Descarga la última versión o clona el repositorio

2. Personaliza la Plantilla:

   • Reemplaza {{GATEWAY_NAME}} con el nombre para mostrar de tu pasarela
   • Reemplaza {{GATEWAY_SLUG}} con el identificador único de tu pasarela
   • Reemplaza {{GATEWAY_DESCRIPTION}} con la descripción de tu pasarela

3. Renombra Archivos:

   • Renombra wcpos-{{GATEWAY_SLUG}}.php para que coincida con el slug de tu pasarela
   • Actualiza los encabezados de archivo y la información del plugin

Estructura de la Plantilla

Archivo Principal del Plugin

El archivo principal del plugin (wcpos-{{GATEWAY_SLUG}}.php) contiene:

• Encabezado del Plugin: Información del plugin de WordPress
• Clase de Pasarela: Clase principal de la pasarela de pago
• Inicialización: Configuración del plugin y hooks
• Integración: Compatibilidad con WooCommerce POS

Componentes Clave

Estructura de la Clase de Pasarela:

class WCPOS_Gateway_{{GATEWAY_CLASS}} extends WC_Payment_Gateway {
    // Configuración de la pasarela
    public function __construct() { }
    
    // Formulario de configuración del administrador
    public function init_form_fields() { }
    
    // Procesar el pago (la lógica principal va aquí)
    public function process_payment( $order_id ) { }
    
    // Métodos específicos de POS
    public function payment_fields() { }
}

Guía de Personalización

Configuración Básica

1. Información de la Pasarela:

   $this->id = 'your_gateway_id';
   $this->title = 'Your Gateway Name';
   $this->description = 'Gateway description for customers';
   $this->method_title = 'Admin title';
   $this->method_description = 'Admin description';

2. Características Soportadas:

   $this->supports = array(
       'products',
       'refunds',
       'subscriptions', // si es aplicable
   );

Procesamiento de Pagos

La lógica principal del pago va en el método process_payment():

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );
    
    // Lógica de procesamiento de pago aquí
    // Ejemplo: Llamadas API, validación, etc.
    
    if ( $payment_successful ) {
        $order->payment_complete();
        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    } else {
        wc_add_notice( 'Payment failed', 'error' );
        return array(
            'result' => 'failure'
        );
    }
}

Configuración del Administrador

Configura la configuración del administrador en init_form_fields():

public function init_form_fields() {
    $this->form_fields = array(
        'enabled' => array(
            'title' => 'Enable/Disable',
            'type' => 'checkbox',
            'label' => 'Enable Your Gateway',
            'default' => 'yes'
        ),
        'api_key' => array(
            'title' => 'API Key',
            'type' => 'text',
            'description' => 'Enter your API key',
            'default' => '',
            'desc_tip' => true,
        ),
        // Agrega más configuraciones según sea necesario
    );
}

Integración POS

Para funcionalidad específica de POS, implementa:

public function payment_fields() {
    // Formulario de pago personalizado para POS
    if ( is_admin() && isset( $_GET['page'] ) && $_GET['page'] === 'wc-pos' ) {
        // Campos de pago específicos de POS
        echo '<div class="pos-payment-fields">';
        // Tu interfaz personalizada para POS
        echo '</div>';
    } else {
        // Campos estándar de pago en la web
        parent::payment_fields();
    }
}

Mejores Prácticas de Desarrollo

Estándares de Código

• Normas de Codificación de WordPress: Sigue los estándares de codificación PHP de WordPress
• Directrices de WooCommerce: Adhiérete a las prácticas de desarrollo de WooCommerce
• Seguridad: Sanitiza entradas, valida datos, utiliza nonces
• Internacionalización: Haz que las cadenas sean traducibles utilizando __() y _e()

Manejo de Errores

// Manejo adecuado de errores
try {
    $result = $this->process_api_call( $data );
    if ( is_wp_error( $result ) ) {
        throw new Exception( $result->get_error_message() );
    }
} catch ( Exception $e ) {
    $order->add_order_note( 'Payment failed: ' . $e->getMessage() );
    wc_add_notice( 'Payment processing error', 'error' );
    return array( 'result' => 'failure' );
}

Registro

// Agrega registro para depuración
if ( $this->debug ) {
    $this->log( 'Payment processing started for order ' . $order_id );
}

private function log( $message ) {
    if ( empty( $this->logger ) ) {
        $this->logger = wc_get_logger();
    }
    $this->logger->info( $message, array( 'source' => $this->id ) );
}

Pruebas de Tu Pasarela

Entorno de Desarrollo

1. Modo de Prueba: Siempre implementa un modo de prueba/sandbox
2. Registro de Depuración: Incluye un registro completo para solucionar problemas
3. Escenarios de Error: Prueba diversas condiciones de fallos
4. Pruebas de POS: Prueba específicamente en el entorno POS

Casos de Prueba

• Pagos Exitosos: Verifica que los pedidos se completen correctamente
• Pagos Fallidos: Asegúrate de que el manejo de errores sea adecuado
• Reembolsos: Prueba la funcionalidad de reembolsos si se admite
• Casos Límite: Prueba con varios montos y configuraciones de pedidos

Despliegue

Empaquetado del Plugin

1. Eliminar Archivos de Desarrollo: Limpia los archivos de prueba y las herramientas de desarrollo
2. Control de Versiones: Actualiza los números de versión en el encabezado del plugin
3. Documentación: Incluye un README con instrucciones de instalación
4. Paquete Zip: Crea un archivo zip instalable

Distribución

• Versiones de GitHub: Utiliza versiones de GitHub para la gestión de versiones
• Directorio de Plugins de WordPress: Considera enviarlo a WordPress.org
• Distribución Privada: Aloja en tus propios servidores si es necesario

Características Avanzadas

Webhooks

Para actualizaciones de pago en tiempo real:

public function handle_webhook() {
    $payload = file_get_contents( 'php://input' );
    $data = json_decode( $payload, true );
    
    // Verifica la firma del webhook
    if ( $this->verify_webhook_signature( $payload ) ) {
        $this->process_webhook_data( $data );
    }
}

Soporte para Suscripciones

Para pagos recurrentes:

// Agrega soporte para suscripciones
$this->supports[] = 'subscriptions';
$this->supports[] = 'subscription_cancellation';
$this->supports[] = 'subscription_suspension';

Multi-divisa

Para pagos internacionales:

public function get_supported_currencies() {
    return array( 'USD', 'EUR', 'GBP', 'CAD' );
}

Recursos

Documentación

• API de Pasarela de Pago de WooCommerce
• Desarrollo de Plugins de WordPress
• Documentación de WooCommerce POS

Repositorio de Plantilla

• GitHub: woocommerce-gateway-template
• Problemas: Informa sobre problemas de la plantilla o solicita funciones
• Contribuciones: Envía mejoras mediante solicitudes de extracción

Obtener Ayuda

Para soporte de desarrollo:

• Visita el repositorio de GitHub para problemas específicos de la plantilla
• Consulta la documentación para desarrolladores de WooCommerce para preguntas sobre la API
• Únete a la comunidad de desarrolladores de WooCommerce para guía general

Ejemplos de Pasarelas

Estudia estas pasarelas personalizadas existentes para ejemplos de implementación:

• Stripe Terminal: Ejemplo de integración de hardware
• SumUp Terminal: Integración de terminal basada en API
• Email Invoice: Pasarela simple basada en correo electrónico
• Web Checkout: Pasarela de integración web

---