Tango Tiendas para WooCommerce

1. Introducción

Tango Tiendas para WooCommerce es un plugin de WordPress que integra de forma completa y bidireccional tu tienda WooCommerce con Tango Gestión / Tango Punto de Venta a través de la plataforma Tango Tiendas de Axoft.

El plugin permite:

• Sincronizar stock en tiempo real: Los cambios de stock en Tango se reflejan instantáneamente en WooCommerce vía webhooks, con sincronización periódica como respaldo.
• Sincronizar precios en tiempo real: Los cambios de precios en Tango se actualizan automáticamente en WooCommerce.
• Enviar pedidos automáticamente: Los pedidos de WooCommerce se envían a Tango al completar el pago.
• Sincronizar estados de pedidos: Los cambios de estado en Tango (procesado, facturado, rechazado, etc.) se reflejan en WooCommerce.
• Acceder a facturas electrónicas: PDF de factura disponible directamente desde el panel de WooCommerce.
• Importar productos masivamente: Descargar todos los artículos de Tango y crearlos como productos en WooCommerce.
• Detectar productos nuevos: Cada 15 minutos, el plugin verifica si hay artículos nuevos en Tango y los crea automáticamente.
• Mapear productos automáticamente: Vincular productos por código SKU de forma automática o manual.
• Capturar DNI/CUIT en checkout: Campo obligatorio para facturación argentina.

Arquitectura del Plugin

Tango Gestión / Tango Punto de Venta
        |
        v
  Tango Tiendas (tiendas.axoft.com)
        |
        v  API REST + Webhooks
        |
  Plugin WooCommerce (wc-tango-tiendas)
        |
        v
  WooCommerce / WordPress

El plugin se comunica con la API REST de Tango Tiendas ubicada en https://tiendas.axoft.com/api/Aperture/ utilizando un Access Token para autenticación.

Compatibilidad

2. Requisitos del Sistema

Requisitos de Software

Requisitos de Servidor

Requisitos de Red

• Puerto 443 (HTTPS) saliente abierto hacia tiendas.axoft.com
• Si se usan webhooks: el servidor debe ser accesible desde Internet para recibir notificaciones POST de Tango
• Certificado SSL válido en tu sitio WordPress (para la URL del webhook)

3. Instalación

Método 1: Subir ZIP desde el panel de WordPress

1. Descargue el archivo ZIP del plugin.
2. En el panel de WordPress, vaya a Plugins > Añadir nuevo > Subir plugin.
3. Seleccione el archivo ZIP y haga clic en Instalar ahora.
4. Una vez instalado, haga clic en Activar plugin.

Método 2: Subir manualmente por FTP/SFTP

1. Descomprima el archivo ZIP del plugin.
2. Suba la carpeta wc-tango-tiendas al directorio /wp-content/plugins/ de su instalación de WordPress.
3. En el panel de WordPress, vaya a Plugins y active Tango Tiendas para WooCommerce.

Método 3: Clonar desde repositorio (desarrollo)

cd /ruta-a-wordpress/wp-content/plugins/
git clone <url-del-repositorio> wc-tango-tiendas

Luego active el plugin desde el panel de WordPress.

Qué sucede al activar el plugin

Al activar el plugin por primera vez, se ejecutan automáticamente las siguientes acciones:

1. Creación de tablas de base de datos: Se crean 4 tablas personalizadas:
   • {prefix}_tango_sync_log — Registro de eventos de sincronización
   • {prefix}_tango_product_map — Mapeo entre productos WC y artículos Tango
   • {prefix}_tango_order_map — Mapeo entre pedidos WC y órdenes Tango
   • {prefix}_tango_sync_history — Historial de cambios por producto
2. Configuración de opciones por defecto (integración habilitada: No, sincronizar stock/precios/pedidos: Sí, lista de precios: 1, condición de venta: 1, intervalo cron: 5 minutos)
3. Programación de tareas cron: Stock cada 5 min (configurable), estados de pedidos cada 5 min, limpieza de logs diaria, detección de productos nuevos cada 15 min
4. Flush de rewrite rules para el endpoint del webhook.

Qué sucede al desactivar el plugin

• Se eliminan todas las tareas cron programadas.
• Se ejecuta flush de rewrite rules.
• Las tablas de base de datos y las opciones NO se eliminan, para preservar los datos si se reactiva el plugin.

4. Configuración en Tango Gestión (Lado Tango)

Antes de configurar el plugin en WooCommerce, debe configurar Tango Tiendas desde su sistema Tango Gestión.

Paso 1: Asociar empresa en Nexo

1. Abra Tango Gestión.
2. Acceda al wizard de Nexo > Tiendas.
3. Asocie la empresa que desea vincular con WooCommerce.
4. Siga los pasos del asistente para completar la asociación.

Paso 2: Obtener el Access Token

1. Dentro de Tango Gestión, vaya a Tango Tiendas > API.
2. En la sección de API, presione el botón "Obtener" para generar un Access Token.
3. Copie el token generado. Lo necesitará para la configuración en WordPress.

Paso 3: Verificar licencia

• Tipo Full: La licencia Full es necesaria para todas las funcionalidades del plugin.
• Vigente: Verificar que la suscripción esté activa.
• Módulo de Tesorería: Debe estar habilitado para el procesamiento de pagos en pedidos.

Paso 4: Verificar artículos habilitados

1. En Tango Gestión, verifique que los artículos que desea sincronizar estén habilitados (no deshabilitados/dados de baja).
2. Cada artículo debe tener un código SKU asignado (campo SKUCode en la API).
3. Verifique que los artículos tengan precios asignados en la lista de precios que utilizará.
4. Verifique que los artículos tengan stock registrado en el depósito que configurará.

5. Configuración en WooCommerce (Lado WordPress)

Acceder al panel del plugin

Una vez activado el plugin, aparecerá un nuevo ítem en el menú lateral de WordPress: Tango Tiendas. El menú contiene 4 secciones: Configuración, Productos, Pedidos y Registro.

Paso 1: Ingresar el Access Token

1. Vaya a Tango Tiendas > Configuración.
2. En la sección Conexión, pegue el Access Token obtenido de Tango Gestión en el campo correspondiente.
3. El campo es de tipo password (oculto). Puede hacer clic en el icono de ojo para mostrar/ocultar el token.

Paso 2: Probar la conexión

1. Haga clic en el botón "Probar conexión".
2. El plugin enviará una solicitud al endpoint POST /api/Aperture/dummy de Tango para validar el token.
3. Si la conexión es exitosa, verá un mensaje verde: "Conexión exitosa. Token válido."

Errores comunes al probar conexión

• Token inválido: Verifique que copió correctamente el Access Token desde Tango.
• Error de conexión: El servidor no puede conectarse a tiendas.axoft.com. Verifique firewall y TLS.
• HTTP 401/403: El token ha expirado o fue revocado. Genere uno nuevo desde Tango.

Paso 3: Activar la integración

1. Active el toggle "Habilitar integración".
2. Haga clic en "Guardar configuración" al final de la página.

Paso 4: Activar sincronizaciones

Dashboard de estado

En la parte superior de la página de Configuración se muestra un dashboard con 4 tarjetas de estado: Estado de conexión, Productos vinculados, Pedidos sincronizados y Última sincronización.

6. Configuración del Webhook

Los webhooks permiten que Tango envíe notificaciones en tiempo real a tu WooCommerce cada vez que cambia un stock, un precio o el estado de un pedido. Sin webhooks, la sincronización solo ocurre por cron (cada N minutos).

Paso 1: Obtener la URL del Webhook

1. En Tango Tiendas > Configuración, busque la sección "Webhook (Notificaciones en tiempo real)".
2. Copie la URL que aparece ahi. El formato es:

https://tudominio.com/wp-json/wc-tango/v1/webhook?secret=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

La URL incluye automáticamente un parámetro secret que es un token único generado al activar el plugin.

Paso 2: Configurar en Tango Tiendas

1. Acceda a la consola de Tango Tiendas (web).
2. Vaya a API > Notificaciones.
3. Marque el checkbox para habilitar las notificaciones.
4. Pegue la URL del webhook copiada en el paso anterior.
5. Guarde la configuración.

Tipos de notificaciones

Formato del payload del webhook

{
    "Topic": "StockProductUpdate",
    "Resource": "id-del-recurso",
    "Message": "Mensaje descriptivo"
}

Procesamiento asíncrono

El plugin procesa las notificaciones de forma asíncrona usando Action Scheduler (incluido con WooCommerce 3.5+): el webhook recibe la notificación y responde inmediatamente con HTTP 200 OK, luego se programa una tarea en segundo plano. Si Action Scheduler no está disponible, el procesamiento se realiza de forma síncrona.

Endpoint REST del webhook

• URL: https://tudominio.com/wp-json/wc-tango/v1/webhook
• Método: POST
• Content-Type: application/json
• Autenticación: Vía parámetro secret o header X-Tango-Webhook-Secret

7. Configuración de Parámetros de Tango

En la sección "Configuración de Tango" de la página de ajustes, debe configurar los parámetros que el plugin usará para comunicarse con Tango. Cada campo tiene un botón "Cargar desde Tango" que consulta la API y muestra las opciones disponibles.

7.1 Depósito (Warehouse)

El depósito determina de qué almacén se toma el stock para sincronizar con WooCommerce.

• Haga clic en "Cargar desde Tango" para ver la lista de depósitos disponibles.
• Múltiples depósitos: Puede ingresar varios códigos separados por coma (ej: 1,2,3). El stock se sumará de todos los depósitos indicados.
• Dejar vacío: Si deja el campo vacío, se tomará el stock de TODOS los depósitos.

Endpoint API: GET /api/Aperture/Warehouse

7.2 Lista de Precios

La lista de precios determina qué precios se sincronizan con WooCommerce. Valor por defecto: 1.

Endpoint API: GET /api/Aperture/PriceList

7.3 Condición de Venta

La condición de venta se envía con cada pedido a Tango. Determina las condiciones de pago. Valor por defecto: 1.

Valores comunes: 1 = Contado, 2 = Cuenta Corriente 30 días, 3 = Cuenta Corriente 60 días.

Endpoint API: GET /api/Aperture/SaleCondition

7.4 Talonario (Counterfoil)

El talonario determina qué serie de comprobantes se usa al generar pedidos en Tango. Valor 0 = usar el talonario predeterminado configurado en Tango.

Endpoint API: GET /api/Aperture/Counterfoil?voucher=PED

8. Importación de Productos

El plugin ofrece dos mecanismos para traer productos de Tango a WooCommerce: importación masiva inicial y detección automática de productos nuevos.

8.1 Importación Masiva Inicial

1. Vaya a Tango Tiendas > Productos.
2. Haga clic en el botón "Importar productos de Tango".
3. El proceso se ejecuta en dos fases:
   • Fase 1 — Descarga de datos: El plugin consulta la API para obtener todos los artículos, precios y stock. Filtra los que ya existen en WooCommerce por SKU.
   • Fase 2 — Creación por lotes: El navegador procesa lotes de 20 productos con una barra de progreso.

Datos importados de cada producto

8.2 Detección Automática de Productos Nuevos

Si la opción "Importar productos nuevos automáticamente" está activada en Configuración, cada 15 minutos el cron consulta la API usando el parámetro updatedDate con la fecha del último chequeo (con 5 minutos de buffer) y crea automáticamente los productos nuevos.

8.3 Protección contra duplicados

• Antes de la importación, carga TODOS los SKUs existentes en WooCommerce en una sola consulta SQL.
• Antes de crear cada producto, verifica nuevamente con wc_get_product_id_by_sku().
• Si encuentra un producto existente con el mismo SKU, solo crea el mapeo (no duplica el producto).

8.4 Protección contra importaciones concurrentes

Se usa un transient de WordPress como lock (wc_tango_product_import_lock) con expiración de 1 hora. Si intenta iniciar una importación mientras otra está en curso, se muestra un mensaje de error.

9. Mapeo de Productos

El mapeo es la vinculación entre un producto de WooCommerce y un artículo de Tango. Sin mapeo, el plugin no puede sincronizar stock ni precios para ese producto.

9.1 Mapeo Automático Masivo

1. Vaya a Tango Tiendas > Configuración o Tango Tiendas > Productos.
2. Haga clic en "Ejecutar mapeo automático".
3. El plugin descarga todos los artículos de Tango y los compara con SKUs de WooCommerce buscando coincidencia por: SKUCode, AlternativeCode o BarCode.
4. Los nuevos mapeos se insertan en lotes de 200 (batch insert).

9.2 Mapeo Manual (desde el producto)

1. En el meta box "Tango Tiendas - Sincronización", encuentre la sección "Mapeo manual".
2. Ingrese el código SKU de Tango en el campo de texto.
3. Haga clic en "Vincular".

9.3 Mapeo de Variaciones

Para productos variables, edite el producto variable. En cada variación encontrará los campos SKU Tango y Código Variante Tango. Complete los campos y guarde; el mapeo se crea automáticamente para cada variación.

9.4 Tabla de mapeo

El mapeo se almacena en la tabla {prefix}_tango_product_map:

10. Sincronización de Stock

La sincronización de stock fluye de Tango a WooCommerce (unidireccional). Hay dos mecanismos que trabajan en conjunto:

10.1 Sincronización en Tiempo Real (Webhook)

1. Se modifica stock en Tango Gestión.
2. Tango Tiendas detecta el cambio y envía una notificación StockProductUpdate al webhook.
3. El plugin recibe la notificación y responde HTTP 200 inmediatamente.
4. Se programa una tarea asíncrona (Action Scheduler).
5. La tarea consulta GET /api/Aperture/Stock?id={resource_id} para obtener el stock actualizado.
6. Se busca y actualiza el producto en WooCommerce por SKU.

10.2 Sincronización Periódica (Cron)

El cron wc_tango_sync_stock_cron se ejecuta cada N minutos (configurable, defecto: 5). Descarga TODO el stock con auto-paginación, filtra por depósito(s) configurado(s), agrega stock por SKU, y aplica las actualizaciones en lotes de 200 usando SQL directo.

10.3 Cálculo del Stock Disponible

Stock disponible = Cantidad física (Quantity) - Cantidad comprometida (EngagedQuantity)

El resultado siempre se redondea hacia abajo y nunca es negativo (mínimo 0).

10.4 Múltiples Depósitos

Si configura múltiples códigos de depósito separados por coma (ej: 1,2,3), el plugin suma el stock disponible de todos los depósitos para cada SKU. Si el campo de depósito está vacío, se usa el stock de TODOS los depósitos.

10.5 Optimizaciones de rendimiento

• Consultas batch: Todo se carga en consultas SQL únicas (no N+1).
• SQL directo: Las actualizaciones usan SQL directo en lugar de cargar objetos WC_Product completos (50x más rápido).
• Comparación de cambios: Solo se actualizan los productos cuyo stock realmente cambió.
• Lock con transient: Previene ejecuciones concurrentes (lock de 10 minutos).
• Solo background: La sincronización periódica solo se ejecuta en contextos de cron, WP-CLI o AJAX (nunca bloquea un request de visitante).

11. Sincronización de Precios

La sincronización de precios fluye de Tango a WooCommerce (unidireccional). Funciona de forma similar al stock.

11.1 Lógica de Precios

Al actualizar un precio, el plugin maneja tres escenarios:

• Escenario 1 — Sin precio de oferta: Se actualiza _regular_price y _price con el nuevo precio de Tango.
• Escenario 2 — Precio de oferta menor al nuevo precio regular: Se actualiza _regular_price y se mantiene el _sale_price existente.
• Escenario 3 — Precio de oferta mayor o igual al nuevo precio regular: Se actualiza _regular_price y se elimina el _sale_price (ya no tiene sentido una oferta >= regular).

11.2 Sincronización Periódica

Se ejecuta junto con la de stock (mismo cron wc_tango_sync_stock_cron). Consulta GET /api/Aperture/Price?filter={price_list} con auto-paginación, y aplica actualizaciones con tolerancia de $0.01.

11.3 Metadata actualizada

• _regular_price: Precio regular del producto
• _price: Precio efectivo (puede ser regular o de oferta)
• _sale_price: Se elimina si es >= al nuevo precio regular
• wc_product_meta_lookup.min_price y max_price: Actualizados para queries de WC

12. Sincronización de Pedidos

La sincronización de pedidos es bidireccional: los pedidos se envían de WooCommerce a Tango, y los cambios de estado fluyen de Tango a WooCommerce.

12.1 Cuándo se envía un pedido

12.2 Estructura del Pedido enviado a Tango

El pedido se envía al endpoint POST /api/Aperture/order. Ejemplo de estructura:

{
    "Date": "2024-01-15T10:30:00",
    "Total": 15000.00,
    "TotalDiscount": 500.00,
    "PaidTotal": 15000.00,
    "SaleConditionCode": 1,
    "OrderID": "123",
    "WarehouseCode": "1",
    "Customer": { ... },
    "OrderItems": [ ... ],
    "Shipping": { ... },
    "CashPayments": [ ... ]
}

Datos del Cliente

Items del Pedido

12.3 Mapeo de Provincias Argentinas

12.4 Sincronización de Estados (Tango -> WooCommerce)

12.5 Reenvío de Pedidos

Desde la página de Pedidos del plugin o desde el meta box del pedido, haga clic en "Reenviar". Esto elimina el mapeo existente y reenvía el pedido a Tango.

13. Campo DNI/CUIT en el Checkout

El plugin agrega automáticamente un campo obligatorio de DNI / CUIT al checkout de WooCommerce, necesario para la facturación electrónica argentina.

Características del campo

Validación

• DNI: 7 a 8 dígitos (ej: 12345678)
• CUIT: 11 dígitos, con o sin guiones (ej: 20-12345678-9 o 20123456789)

Almacenamiento

• Se guarda como meta del pedido: _billing_dni
• Si el cliente está logueado, también se guarda como meta del usuario: billing_dni
• En pedidos futuros del mismo cliente, el campo se prellenará automáticamente.

Detección del tipo de documento

• 11 dígitos → Tipo 80 (CUIT)
• 7-8 dígitos → Tipo 96 (DNI)
• Sin documento → Tipo 99 (Sin identificar)

14. Facturación Electrónica

El plugin integra el acceso a facturas electrónicas generadas en Tango.

14.1 Recepción de Facturas

1. Vía webhook OrderBilled: Cuando Tango factura un pedido, el plugin consulta GET /api/Aperture/Invoices?orderId=X, almacena el número de factura y la URL del PDF, agrega una nota al pedido y actualiza el estado a "Completado".
2. Vía webhook InvoiceFile: Cuando el PDF está disponible, consulta la API de Invoices y almacena la URL del PDF.
3. Vía polling periódico: El cron de estados también verifica si hay datos de factura disponibles.

14.2 Acceso a la Factura desde el Panel

Abra el pedido en WooCommerce. En el meta box "Tango Tiendas" encontrará el ID de Tango, fecha de envío, número de factura y el botón "Factura Tango" que abre un modal con información detallada y link para descargar el PDF.

15. Panel de Administración

El plugin agrega un menú principal "Tango Tiendas" con 4 subpáginas en la barra lateral de WordPress.

15.1 Página de Configuración

Ruta: Tango Tiendas > Configuración | Slug: wc-tango-tiendas

Secciones: Dashboard de estado, Conexión, Webhook, Sincronización, Configuración de Tango, Mapeo de productos, Avanzado (modo depuración), Botón Guardar.

15.2 Página de Productos

Ruta: Tango Tiendas > Productos | Slug: wc-tango-products

Barra de herramientas con botones para importar, mapear, sincronizar stock y precios. Tabla páginada (50 por página) con ID, nombre, SKU Tango, código, variante, stock, precio y fechas de sincronización.

15.3 Página de Pedidos

Ruta: Tango Tiendas > Pedidos | Slug: wc-tango-orders

Tabla con los últimos 50 pedidos sincronizados: número de pedido, ID Tango, estado Tango (con badge de color), estado WC, factura (número + link PDF), última sincronización y botón reenviar.

15.4 Página de Registro de Actividad

Ruta: Tango Tiendas > Registro | Slug: wc-tango-logs

Filtros por tipo (Stock, Precios, Pedidos, Webhooks, Facturas) y por estado. Tabla páginada con ID, fecha, tipo, dirección, entidad, estado y mensaje. Botón "Limpiar registros" para eliminar todos los registros.

16. Meta Box en Productos

Al editar un producto en WooCommerce, el plugin agrega un meta box en la columna lateral: "Tango Tiendas - Sincronización".

Estado: No Vinculado

Si el producto no tiene SKU de Tango asignado, el meta box muestra una advertencia, el botón "Mapear automáticamente" (si el producto tiene SKU de WC) y un campo de mapeo manual con botón "Vincular".

Estado: Vinculado

Si el producto está vinculado a Tango, el meta box muestra: badge "Conectado a Tango", SKU Tango, stock y precio actuales (con indicadores de color), fechas de última sincronización y botón "Sincronizar ahora" para forzar una actualización.

También incluye una sección colapsable "Historial de cambios" con los últimos 15 cambios del producto, mostrando tipo (Stock/Precio), fuente (webhook/cron), valores anterior y nuevo, y tiempo relativo.

Campos en la sección de Inventario

• _tango_sku_code: Código de artículo en Tango Gestión.
• _tango_product_code: Código de publicación en Tango Tiendas (opcional).

Al guardar el producto, estos campos actualizan automáticamente la tabla de mapeo.

17. Meta Box en Pedidos

Al editar un pedido en WooCommerce, el plugin agrega un meta box en la columna lateral: "Tango Tiendas".

Pedido Enviado a Tango

Muestra: badge verde "Enviado a Tango", ID Tango, fecha de envío, número de factura (si existe), botón "Factura Tango" (abre el modal con link al PDF) y botón "Reenviar".

Pedido No Enviado

Si el pedido no fue enviado a Tango, muestra un icono de información, texto explicativo y el botón "Enviar a Tango" para envío manual.

Compatibilidad HPOS

El meta box es compatible con High-Performance Order Storage de WooCommerce. Detecta automáticamente si HPOS está habilitado y usa la pantalla de edición correcta.

18. Registro de Actividad (Logs)

Tipos de eventos registrados

Estados

Limpieza automática

El cron diario wc_tango_cleanup_logs_cron realiza dos tareas de limpieza:

1. Por cantidad: Si hay más de 10,000 registros, elimina los más antiguos para mantener solo los 10,000 más recientes.
2. Por antigüedad: Elimina registros con más de 30 días.

19. Modo Depuración

Activar modo depuración

1. Vaya a Tango Tiendas > Configuración > Avanzado.
2. Active el toggle "Modo depuración".
3. Guarde la configuración.

Qué se registra en modo depuración

Con el modo depuración activado, el plugin registra información detallada en WooCommerce > Estado > Registros (fuente: wc-tango-tiendas):

• Cada solicitud a la API: URL y método (GET/POST)
• Cada respuesta de la API: Código HTTP y body (primeros 2000 caracteres)
• Operaciones internas detalladas
• Decisiones de lógica (por qué un pedido no se envió, por qué un stock no se actualizó, etc.)

20. Tablas de Base de Datos

El plugin crea 4 tablas personalizadas al activarse. Todas usan el prefijo de tabla de WordPress (típicamente wp_).

20.1 {prefix}_tango_sync_log

CREATE TABLE {prefix}_tango_sync_log (
    id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
    type varchar(50) NOT NULL DEFAULT '',
    direction varchar(20) NOT NULL DEFAULT '',
    entity_id varchar(100) NOT NULL DEFAULT '',
    status varchar(20) NOT NULL DEFAULT '',
    message text,
    request_data longtext,
    response_data longtext,
    created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY type_idx (type),
    KEY status_idx (status),
    KEY created_at_idx (created_at)
);

20.2 {prefix}_tango_product_map

CREATE TABLE {prefix}_tango_product_map (
    id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
    wc_product_id bigint(20) unsigned NOT NULL,
    tango_sku_code varchar(100) NOT NULL DEFAULT '',
    tango_product_code varchar(100) NOT NULL DEFAULT '',
    tango_variant_code varchar(100) DEFAULT '',
    last_stock_sync datetime DEFAULT NULL,
    last_price_sync datetime DEFAULT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY wc_product_idx (wc_product_id),
    KEY tango_sku_idx (tango_sku_code)
);

20.3 {prefix}_tango_order_map

CREATE TABLE {prefix}_tango_order_map (
    id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
    wc_order_id bigint(20) unsigned NOT NULL,
    tango_order_id varchar(100) NOT NULL DEFAULT '',
    tango_status varchar(50) DEFAULT '',
    tango_invoice_number varchar(100) DEFAULT '',
    tango_invoice_url text,
    last_sync datetime DEFAULT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY wc_order_idx (wc_order_id),
    KEY tango_order_idx (tango_order_id),
    KEY tango_status_idx (tango_status)
);

20.4 {prefix}_tango_sync_history

CREATE TABLE {prefix}_tango_sync_history (
    id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
    wc_product_id bigint(20) unsigned NOT NULL,
    field varchar(20) NOT NULL DEFAULT '',
    old_value varchar(100) DEFAULT '',
    new_value varchar(100) DEFAULT '',
    source varchar(20) NOT NULL DEFAULT 'webhook',
    created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY product_idx (wc_product_id),
    KEY created_at_idx (created_at)
);

21. Tareas Cron Automatizadas

El plugin registra 4 tareas cron recurrentes en WordPress.

22. Recomendaciones de Servidor

22.1 Cron real del servidor

El plugin muestra una advertencia si WP-Cron nativo está habilitado. Se recomienda deshabilitar WP-Cron y usar un cron real del servidor.

Cómo configurar:

1. Edite wp-config.php y agregue:

define( 'DISABLE_WP_CRON', true );

2. Configure un cron del servidor que ejecute WP-Cron cada minuto:

* * * * * cd /ruta/a/wordpress && php wp-cron.php > /dev/null 2>&1
# O usando wget:
* * * * * wget -q -O - https://tudominio.com/wp-cron.php > /dev/null 2>&1

22.2 TLS 1.2

El servidor debe soportar TLS 1.2 o superior. Verifique con:

openssl s_client -connect tiendas.axoft.com:443 -tls1_2

22.3 Timeouts

Para catálogos grandes (10,000+ SKUs), asegúrese de: max_execution_time >= 300 y memory_limit >= 256M en PHP. El plugin establece internamente @set_time_limit(300) y usa @ignore_user_abort(true) para sincronizaciones masivas.

22.4 Certificado SSL

Su sitio WordPress debe tener un certificado SSL válido (HTTPS) para recibir webhooks de Tango (Tango solo envía a URLs HTTPS). Las llamadas a la API usan sslverify => true por seguridad.

23. API de Tango Tiendas — Referencia

23.1 URL Base

https://tiendas.axoft.com/api/Aperture/

23.2 Autenticación

Todas las solicitudes incluyen el header:

accesstoken: {tu_access_token}

23.3 Endpoints utilizados por el plugin

23.4 Paginación

La API de Tango usa paginación con los parámetros pageSize (máximo 500 en el plugin) y pageNumber (1-indexed). La respuesta incluye Paging.MoreData. El plugin implementa auto-paginación con límite de seguridad de 20 páginas (10,000 registros max).

23.5 Manejo de errores

• Error de red: WP_Error de WordPress (timeout, DNS, etc.)
• Error HTTP: Código de estado 4xx/5xx
• Error de lógica: Campo isOk: false en la respuesta
• Error de JSON: Respuesta que no se puede decodificar como JSON

El timeout por defecto para solicitudes a la API es de 30 segundos.

24. Seguridad

24.1 Almacenamiento del Access Token

El Access Token se almacena en la tabla wp_options de WordPress, protegido por la seguridad nativa de WordPress y la base de datos.

24.2 Webhook Secret

• Se genera automáticamente al activar el plugin usando wp_generate_password(32, false).
• Se verifica en cada notificación recibida.
• Se puede regenerar desactivando y reactivando el plugin (debe actualizar la URL en Tango).

24.3 Nonces AJAX

Todas las solicitudes AJAX del panel de administración incluyen y verifican un nonce de WordPress (wc_tango_admin) usando wp_create_nonce() y check_ajax_referer().

24.4 Permisos

Solo usuarios con el capability manage_woocommerce pueden acceder al panel del plugin. Todos los handlers AJAX verifican permisos con current_user_can('manage_woocommerce').

24.5 Sanitización de datos

Todos los datos de entrada se sanitizan con funciones nativas de WordPress: sanitize_text_field(), absint(), esc_html(), esc_url(). Las consultas SQL usan $wpdb->prepare() para prevenir inyección SQL.

24.6 Protección de archivos

Todos los archivos PHP del plugin incluyen if ( ! defined( 'ABSPATH' ) ) { exit; } para prevenir acceso directo. Los directorios incluyen archivos index.php vacíos para prevenir directory listing.

25. Solución de Problemas y FAQ

25.1 Problemas de conexión

Soluciones:

1. Verifique que el Access Token sea correcto (cópielo nuevamente desde Tango).
2. Verifique que el servidor puede conectarse a tiendas.axoft.com (puerto 443).
3. Verifique que PHP tenga cURL habilitado.
4. Verifique que el servidor soporte TLS 1.2.
5. Revise si hay un firewall bloqueando conexiones salientes.

Soluciones: El token puede haber expirado (genere uno nuevo desde Tango Tiendas), verifique que la licencia esté vigente y asegúrese de que no haya espacios en blanco al inicio o final del token.

25.2 Problemas de sincronización

1. Verifique que "Sincronizar stock" esté activado en Configuración.
2. Verifique que la integración esté habilitada.
3. Verifique que los productos estén mapeados (Tango Tiendas > Productos).
4. Verifique que el depósito configurado sea correcto.
5. Revise los logs en Tango Tiendas > Registro.
6. Active el modo depuración para ver detalles.

1. Verifique que "Sincronizar pedidos" esté activado.
2. Verifique que todos los productos del pedido tengan SKU de Tango asignado.
3. El pedido debe estar en estado on-hold, processing o completed.
4. Revise las notas del pedido para ver si hay errores.
5. Intente reenviar el pedido desde el meta box.

25.3 Problemas de webhook

1. Verifique que la URL del webhook esté correctamente configurada en Tango Tiendas.
2. Verifique que su sitio sea accesible desde Internet (no localhost).
3. Verifique que tenga certificado SSL válido (HTTPS).
4. Verifique que la API REST de WordPress funcione (/wp-json/ debe responder).
5. Revise si algún plugin de seguridad (Wordfence, Sucuri, etc.) está bloqueando las solicitudes POST.

Pruebe la URL del webhook manualmente con cURL:

curl -X POST https://tudominio.com/wp-json/wc-tango/v1/webhook?secret=TU_SECRETO \
  -H "Content-Type: application/json" \
  -d '{"Topic":"test","Resource":"","Message":"test"}'
# Debería responder {"status":"ok"} o {"status":"disabled"}

25.4 Problemas de importación

1. Haga clic en "Reiniciar estado" en el panel de importación.
2. Verifique que el servidor tenga suficiente memoria y tiempo de ejecución.
3. Si el problema persiste, elimine manualmente el transient wc_tango_product_import_lock de wp_options.

25.5 FAQ

26. Referencia Técnica para Desarrolladores

26.1 Constantes

26.2 Clase Principal

// Obtener la instancia del plugin
$tango = wc_tango_tiendas();

// Acceder a los componentes
$tango->api;             // WC_Tango_API_Client
$tango->webhook;         // WC_Tango_Webhook_Handler
$tango->stock_sync;      // WC_Tango_Stock_Sync
$tango->price_sync;      // WC_Tango_Price_Sync
$tango->order_sync;      // WC_Tango_Order_Sync
$tango->product_import;  // WC_Tango_Product_Import
$tango->checkout;        // WC_Tango_Checkout
$tango->logger;          // WC_Tango_Logger

// Verificar si la integración está activa
WC_Tango_Tiendas::is_active(); // true/false

// Obtener una configuración
WC_Tango_Tiendas::get_setting( 'warehouse_code' );

26.3 Opciones de WordPress (wp_options)

26.4 Meta datos de Productos

26.5 Meta datos de Pedidos

26.6 Hooks de WordPress

Actions del plugin

Hooks de WooCommerce que el plugin escucha

26.7 Endpoints REST registrados

26.8 Transients utilizados

26.9 Estructura del Plugin

wc-tango-tiendas/
├── wc-tango-tiendas.php               # Archivo principal, clase singleton
├── index.php                          # Protección de directorio
├── assets/
│   ├── css/
│   │   └── admin.css                  # Estilos del panel de administración
│   └── js/
│       └── admin.js                   # JavaScript del panel de administración
├── includes/
│   ├── class-wc-tango-logger.php      # Sistema de logging
│   ├── class-wc-tango-api-client.php  # Cliente API REST
│   ├── class-wc-tango-webhook-handler.php
│   ├── class-wc-tango-stock-sync.php
│   ├── class-wc-tango-price-sync.php
│   ├── class-wc-tango-order-sync.php
│   ├── class-wc-tango-product-import.php
│   ├── class-wc-tango-checkout.php
│   └── admin/
│       ├── class-wc-tango-admin.php
│       └── views/
│           ├── settings-page.php
│           ├── products-page.php
│           ├── orders-page.php
│           └── logs-page.php
└── languages/                         # Traducciones

26.10 Declaración de compatibilidad HPOS

add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables', __FILE__, true
        );
    }
});