1. Integración WooCommerce <> MetaKocka
1.1. Establecer conexión con WooCommerce
1.2. Añadir conexión en MetaKocka
2. Sincronización de productos (WooCommerce → MetaKocka)
2.1. Variaciones de producto (color, talla, longitud)
2.2. Descripción adicional de producto
2.3. Sincronización de precios
3. Configuración de prefijo para pedidos
4. Soporte para ventas adicionales (Up-Sell)
5. Asignación de números de lote
6. Opciones adicionales para la transferencia de pedidos
6.1. Mapeo de campos específicos para el país
6.2. Mapeo del número de identificación fiscal de la empresa
6.3. Parámetros adicionales en el nombre del comprador/receptor
6.4. Estado predeterminado de los instrumentos de pago
6.5. Soporte para Irlanda del Norte
7. Revisión de pedidos
8. Actualización de existencias de productos
9. Revisión de producto y stock
10. Errores frecuentes y resolución
10.1. Error de transferencia – Error parse respond
10.2. Error de prueba de conexión
10.3. Error de sincronización de variantes de producto
1. Integración WooCommerce <> MetaKocka
La integración de la tienda online publicada en la plataforma WooCommerce con MetaKocka permite:
Transferencia automática de pedidos con todos los datos del cliente (destinatario, pagador, método de pago, descuentos y artículos solicitados).
Sincronización de productos (los productos pueden transferirse desde la tienda online a MetaKocka con todos los datos ya introducidos en la tienda, siempre que tengan asignado un código SKU).
Sincronización automática de existencias desde MetaKocka hacia la tienda online. Es importante, antes de activar esta función, tener las existencias correctamente configuradas en la tienda online.
Las facturas generadas automáticamente a partir de los pedidos transferidos se validan ante FURS para los medios de pago legalmente definidos. Además, al despachar la mercancía, el stock se reduce de forma correspondiente en MetaKocka y se actualiza en la tienda online (si está configurado así).
1.1 Establecer conexión con la tienda WooCommerce
Para establecer la conexión con la tienda WooCommerce, es necesario obtener la siguiente información directamente desde la tienda:
Dirección URL de la tienda online (por ejemplo:
www.mitienda.com)Consumer Key
Consumer Secret
Los pasos para obtener estos datos se detallan a continuación:
En las versiones más recientes de WooCommerce, el procedimiento para generar la clave API es algo diferente.
Copia los datos obtenidos anteriormente — los necesitarás para añadir la conexión en MetaKocka.
1.2. Después de iniciar sesión en MetaKocka, en Configuración/Enlaces, añade una nueva conexión como se muestra en la imagen siguiente:
Selecciona "WooCommerce" y haz clic en "Añadir".
Pega los datos obtenidos de WooCommerce — Consumer Key y Consumer Secret, URL — y guarda. Haz clic en "Probar conexión" (Test connection); deberías recibir una confirmación de que la integración se ha realizado correctamente.
ChatGPT Plus
Para el módulo de gestión de pedidos, selecciona Pedidos de venta (Sales Orders), pero si solo necesitas la creación de facturas, selecciona Factura (Invoice).
Selecciona "Transferencia automática de pedidos" (Automatic order transfer) si quieres que todos los pedidos recibidos en WooCommerce se transfieran automáticamente a MetaKocka; si es necesario realizar una edición manual en WooCommerce, deja esta opción sin marcar.
Si se requiere la transferencia manual, selecciona cuántos días hacia atrás se deben recopilar los pedidos y haz clic en Importar pedidos (Import orders).
2. Sincronización de productos (WooCommerce → MetaKocka)
Puedes transferir los productos desde la tienda online a MetaKocka de forma automática.
Para poder transferir productos y pedidos, los productos en la tienda online deben tener códigos SKU únicos.
En caso de que haya muchos productos sin código SKU asignado, esto se puede resolver en la tienda WooCommerce utilizando el plugin SKU Regenerator, que permite asignar códigos SKU automáticamente o copiar códigos existentes.
2.1 Variaciones de producto (p. ej., color, talla, longitud)
Si en la tienda online vendes productos con variantes (diferentes colores, tallas, etc.), es necesario asignar un código SKU a cada variante de producto, el cual debe coincidir con el código de producto en MetaKocka.
Un ejemplo de este procedimiento se muestra en las imágenes de referencia.
En este caso, el pedido con variantes de producto se copiará correctamente a MetaKocka con las variantes correspondientes.
Si deseas transferir todas las variantes de producto desde la tienda online a MetaKocka, podrías recibir el siguiente error:
org.codehaus.jackson.map.JsonMappingException: Can not construct instance of com.metakocka.MetaKockaMain.server.GenericWebShop.WooCommerce.WooCVariations, problem: no suitable creator method found to deserialize from JSON Number
at [Source: java.io.StringReader@552621b8; line: 1, column: 9343] (through reference chain: com.metakocka.MetaKockaMain.server.GenericWebShop.WooCommerce.WooCItem["variations"])
En ese caso, es necesario habilitar la versión de API v1 en la sección "Configuraciones adicionales" (Additional Settings).
2.2 Descripción adicional del producto
Si deseas transferir descripciones adicionales de los productos desde la tienda online, es posible hacerlo mediante etiquetas meta_data incluidas en los resultados de la llamada REST de pedidos.
Para ello, es necesario activar funcionalidad adicional en la configuración.
Documentación relacionada: https://metakocka.freshdesk.com/a/solutions/articles/3000077086
Ejemplo:
En el producto "Torbica", queremos añadir dos descripciones adicionales.
En este caso, debes activar la opción "productExtraDescription" en la interfaz de MetaKocka (puedes contactar con el servicio de atención al cliente para recibir ayuda).
La respuesta en formato JSON de la llamada REST al pedido debe contener los datos como valores adicionales en meta_data:
3. Configuración de prefijo para pedidos
En caso de gestionar varias tiendas online, puedes consultar el método para establecer un prefijo delante del número de pedido en el siguiente artículo:
https://www.tychesoftwares.com/how-to-add-prefix-or-suffix-to-woocommerce-order-number/
En la construcción JSON del pedido existen dos campos que identifican un pedido:
"Id" → Número utilizado internamente para detectar pedidos duplicados o para modificar datos del pedido en la tienda WooCommerce.
"number" → Etiqueta que se muestra en todos los lugares de MetaKocka o en el módulo de Gestión de Pedidos.
Consideraciones importantes:
El campo "Id" nunca cambia, ya que únicamente puede aumentar.
El campo "number" se puede modificar libremente (por ejemplo, de
"1001"a"SLO-1001") sin riesgo de crear pedidos duplicados.Esta funcionalidad solo es válida para las tiendas online añadidas a MetaKocka a partir del 01/01/2018.
Si la tienda fue añadida antes de esa fecha, es necesario contactar con el soporte de MetaKocka para verificar el estado mediante el parámetro "useInternalIdForOrderId".
4. Soporte para Up-Sell
Si al momento de la compra ofreces un producto adicional mediante Up-Sell, es importante garantizar lo siguiente:
El Up-Sell debe estar limitado en el tiempo, por ejemplo, 12 horas. Durante ese tiempo, el pedido no debe ser despachado, ya que debe esperar la posible adición del artículo en Up-Sell.
El pedido no debe recibir el estado "processing" inmediatamente, ya que esto provocaría que pase directamente a "despachado" (dispatched). En su lugar, debe asignarse un estado transitorio, por ejemplo, "waiting-upsell", para asegurar que el cambio posterior a "processing" sea posible dentro del plazo establecido.
En caso de cambiar el estado del pedido, es obligatorio realizar la actualización mediante un webhoo
5. Asignación de números de lote
En el caso de registrar números de lote en MetaKocka (por ejemplo, en la venta de productos alimenticios), si la tienda online no admite la introducción de números de lote, MetaKocka asignará automáticamente los números de lote al transferir los pedidos.
Procedimiento de asignación automática:
- El número de lote se asigna automáticamente solo en el caso de transferencia del pedido a factura.
- El producto debe estar marcado como artículo con seguimiento de número de lote.
- La factura debe tener un almacén asignado automáticamente según la configuración de la empresa.
- En el almacén asignado a las facturas, para el producto con número de lote, se verifica si existe stock disponible. Si existe, se asigna el número de lote con mayor cantidad disponible en ese almacén.
Si el producto no tiene un número de lote asignado, se mostrará un error al transferir los pedidos, y el pedido no será transferido.
Ejemplo de error:
3952 - Janez Novak: Product 56 - m2 - La pomada castaño de Indias 100 ml debe tener asignado un número de lote.
6. Opciones adicionales para la transferencia de pedidos desde la tienda online a MetaKocka
6.1 Mapeo de campos específicos para el país
En algunos países, ciertas etiquetas adicionales en las direcciones (principalmente provincias) son importantes.
Por ello, a continuación se indican las reglas para escribir direcciones en WooCommerce con el fin de que se copien correctamente a las direcciones en MetaKocka.
| Pais | Dirección etiqueta | Datos esperados en formato JSON |
| Rumanía | Judet | {billing / shipping}.state |
| Localitate | {billing / shipping}.city | |
| Italia | Province code | {billing / shipping}.state |
Mapeo de campos para España para su uso en el programa Address Editor
Para verificar direcciones correctas en la aplicación Address Editor, las direcciones deben transmitirse de una forma específica.
A continuación se muestra un ejemplo de una solicitud JSON desde WooCommerce (que contiene solo los campos importantes).
Los nombres de los campos deben coincidir exactamente con los del ejemplo mostrado y ser idénticos a los de los metadata del documento (no de socio, productos, etc.).
En el ejemplo siguiente, la dirección del comprador se configuraría como:
"Street 1, BL:12 SC:D ET:4 AP:17" o, para el receptor: "Street 2, BL:12_2 SC:D_2 ET:4_2 AP:17_2".
WooCommerce dispone de diferentes versiones de la interfaz API (actualmente la más reciente es v3).
MetaKocka trabaja por defecto con la interfaz v1. Si los desarrolladores actualizan la interfaz de WooCommerce, deben tener en cuenta lo siguiente:
Actualizar normalmente a la versión v1.
Actualizar a la versión v3, pero en Configuraciones adicionales (Additional Settings) de esa tienda online activar "API version" → "V2".
Nota: el ajuste debe prepararse en las siguientes partes de la interfaz de WooCommerce:
Activación del webhook y llamada a MetaKocka (se envía el JSON completo del pedido).
Devolución de pedidos mediante llamada API /orders.
En el campo "address_2" se debe añadir el número de la casa.
Esto se puede hacer de la siguiente manera:
- En la tienda WooCommerce, separar la interfaz de usuario de forma que el cliente pueda introducir por separado la calle y el número de la casa.
- El número de la casa debe registrarse en el campo "address_2" del comprador/receptor en la respuesta JSON de WooCommerce.
- En MetaKocka, para cada tienda de España , activar la opción "Agrupar datos de direcciones como una sola dirección" (Group data from addresses as one address).
6.2. Mapeo del número de identificación fiscal de la empresa
En caso de habilitar la emisión de facturas a empresas y, en consecuencia, añadir el campo para introducir el número de identificación fiscal, estos datos pueden transferirse fácilmente a MetaKocka a través de la propiedad "meta_data" en el JSON.
Reglas aplicables:
buyer_tax_id / receiver_tax_id → número de identificación fiscal del comprador (o receptor).
Si este valor está presente, el socio se clasifica automáticamente como "empresa" y "contribuyente" (taxpayer).
buyer_tax_payer / receiver_tax_payer → si contiene el valor
"false", en MetaKocka la empresa se marca como no contribuyente (non-taxpayer).Si el valor no está presente, la empresa se marcará automáticamente como contribuyente, siguiendo la lógica del punto anterior.
Nota: La configuración debe prepararse en las siguientes partes de la interfaz de WooCommerce:
Activar webhook y realizar la llamada a MetaKocka (se envía el JSON completo del pedido).
Devolver pedidos mediante llamada API /orders.
Importante: MetaKocka utiliza por defecto la interfaz REST v1.
En caso de añadir estas etiquetas solo a la interfaz v2, será necesario modificar la configuración en:
Configuraciones adicionales → Tiendas online,
Seleccionar la tienda,
Buscar el campo "API Version" y configurarlo en "V2".
| [{ "id": 24777, "parent_id": 0, "status": "completed", "order_key": "wc_order_5b1e09c34a158", "number": "25386", ........... "billing": { ........... "first_name": "Gabriela", "last_name": "Birz", "country": "RO", }, "shipping": { ............. "first_name": "Gabriela", "last_name": "Birz", }, ............. "meta_data": [{ "key": "buyer_tax_id", "value": "SI100200300" }, { "key": "buyer_tax_payer", "value": "true" }, { "key": "receiver_tax_id", "value": "SI100200300" }, { "key": "receiver_tax_payer", "value": "false" } ] } }] |
6.3. Parámetros adicionales en el nombre del comprador/receptor
Si en los metadatos se encuentra la etiqueta "_billing_comp" o "_shipping_comp", únicamente ese valor se antepondrá al nombre del comprador o receptor.
Ejemplo:
En el caso mostrado más abajo, el comprador aparecerá como: "BillComp, Name1 Surname1", Mientras que el receptor aparecerá como: "ShippComp, Name2 Surname".
6.4. Estado predeterminado de los instrumentos de pago
Cuando se recibe un pedido en WooCommerce, según el instrumento de pago utilizado, debe asignarse el siguiente estado:
| Label | Payment instrument | Initial status |
| paypal | PayPal | Pending - an order has been made, however has not been paid yet. Processing - payment has been made |
| bacs | Direct bank transfer | On hold |
| cheque | Check payments | On hold |
| cod | Cash on delivery | Processing |
6.5. Soporte para Irlanda del Norte
Si realizas ventas en el territorio de Irlanda del Norte, debes indicar una etiqueta especial para este país, de forma que se apliquen todas las reglas relacionadas con OSS (como la numeración separada).
Aun así, deberás asegurarte de que las tarifas de impuestos en tu tienda estén configuradas correctamente.
En la respuesta de la llamada API, la tienda online debe proporcionar uno de los siguientes nombres para el país:
United Kingdom (UK) - Northern Ireland
XI
7. Revisión de pedidos
En primer lugar, es necesario construir la URL adecuada para obtener la lista de pedidos.
La estructura es la siguiente:
[basic URL of the online store] + /wp-json/wc/v1/orders?per_page=1&order=desc.
Ejemplo: https://mystore.com/wp-json/wc/v1/orders?per_page=1&order=desc
Si la tienda online soporta HTTPS, se debe utilizar Autenticación Básica (Basic Authentication).
En caso contrario, se emplea OAuth. Las imágenes de referencia muestran ambos casos. Al final, el resultado debe ser un JSON con los pedidos listados.
Enlaces útiles:
8. Actualización de stock de productos
Tipo de petición: POST
Ejemplo de llamada: http://[moja trgovina]/wp-json/wc/v1/products/batch
Contenido del cuerpo de la solicitud
(3982 debe ser el ID del producto en la tienda online):
Respuesta:
Se devuelve la información del producto, que contiene:
9. Revisión de producto y stock
Tipo de petición: POST
Ejemplo de llamada:
Contenido: Sin contenido (empty body).
Respuesta:
Se devuelve la información del producto, que contiene el campo:
10. Descripción de errores frecuentes
10.1. Error de transferencia – Error parse respond
Mensaje de error:
Este tipo de error aparece cuando el reloj cambia de hora de verano (DST) a hora estándar, o viceversa.
Al cambiar a hora de verano (DST): es necesario ajustar la hora a UTC +2 (antes estaba en +1).
Al cambiar a hora estándar: es necesario ajustar la hora a UTC +1 (antes estaba en +2).
10.2. Error de prueba de conexión
En caso de una conexión exitosa, al hacer clic en el botón "Probar conexión" (Connection test) se recibirá una confirmación.
En caso de cualquier problema o error, se recomienda utilizar herramientas/programas para probar la conexión, como Postman.
Dado que cada configuración de WooCommerce es independiente, pueden ocurrir problemas de comunicación entre MetaKocka y WooCommerce.
En caso de incidencia, se recomienda realizar una prueba inicial para verificar la validez de la configuración de la interfaz en WooCommerce, utilizando el programa Postman.
10.3. Error de sincronización de variantes de producto
Si existen variantes de producto y se desea transferir todas ellas desde la tienda online a MetaKocka, puede aparecer el siguiente error:
En este caso, es necesario activar la versión de API v1 en la sección "Configuraciones adicionales" (Additional settings).