Integración de la tienda Agilix con Allegro

• publicar los productos de la tienda agilix.dog como ofertas en Allegro y actualizar su nombre, descripción, fotos y precio;
• mantener un único stock compartido - una venta en la tienda reduce las unidades de la oferta en Allegro y una venta en Allegro reduce el stock de la tienda, normalmente en menos de un minuto;
• traer los pedidos pagados de Allegro al panel de pedidos de la tienda, para gestionarlos junto con los pedidos realizados en la tienda;
• enviar a Allegro el estado de preparación del pedido y el número de seguimiento del envío.

La aplicación la utiliza únicamente el administrador de la tienda agilix.dog, en los ajustes de la tienda del panel de administración. El administrador conecta a la aplicación una sola cuenta de vendedor de Allegro - aquella desde la que vende la tienda. Los compradores y el resto de usuarios de Agilix no inician sesión en Allegro a través de esta aplicación y no tienen acceso a sus ajustes.

El administrador marca en el producto la casilla "Sincronizar con Allegro" y elige la categoría, los parámetros obligatorios y el precio en Allegro. Al guardar el producto, el servidor de Agilix sube en segundo plano las fotos a Allegro, crea o actualiza la oferta (producto, categoría y parámetros, datos del fabricante y de la persona responsable según el GPSR, precio, unidades, tarifa de envío, condiciones de devolución y reclamación) y la publica.

• Desmarcar la casilla, desactivar el producto o agotar el stock finaliza la oferta; cuando el producto vuelve a estar disponible, la oferta se reactiva.
• Los cambios pasan por una cola de tareas en segundo plano, por lo que la edición en la tienda no espera la respuesta de Allegro.
• Si Allegro rechaza una oferta, el administrador ve junto al producto el código y el mensaje de error de Allegro y puede repetir la sincronización.

• Una vez por minuto, el servidor lee el registro de eventos de pedidos desde el último evento procesado.
• Un pedido entra en la tienda solo cuando está listo para su preparación (READY_FOR_PROCESSING) y no ha sido cancelado; cada pedido se importa exactamente una vez y el stock se reduce en las unidades pedidas.
• Cancelar un pedido en Allegro lo cancela también en la tienda y restablece el stock.
• Cuando el administrador cambia el estado del pedido o envía el paquete, la aplicación actualiza el estado de preparación en Allegro y añade el número de seguimiento.
• Los reembolsos de los pedidos de Allegro se gestionan en el panel de Allegro, fuera de la aplicación.

La aplicación utiliza el flujo estándar OAuth 2.0 (Authorization Code) que ofrece Allegro. No pide a nadie usuario, contraseña, Client ID ni Client Secret.

1. El administrador hace clic en "Conectar con Allegro" en los ajustes de la tienda. El servidor crea un parámetro state firmado, válido durante 15 minutos y vinculado a ese administrador.
2. El navegador pasa a la página de inicio de sesión de Allegro (https://allegro.pl/auth/oauth/authorize), donde el vendedor inicia sesión en su cuenta y da su consentimiento a los permisos de la aplicación.
3. Allegro redirige a la dirección registrada https://api.agilix.dog/allegro/oauth/callback. El servidor comprueba la firma y la validez de state y que el usuario sigue siendo administrador de la tienda, y después intercambia el código por tokens (https://allegro.pl/auth/oauth/token), autenticándose con el Client ID y el Client Secret propios de la aplicación.
4. El servidor lee el usuario de la cuenta conectada y guarda la conexión. El token de actualización se almacena únicamente en el servidor, cifrado con AES-256-GCM. El token de acceso se renueva automáticamente y cada nuevo token de actualización sustituye de inmediato al anterior.

El Client Secret y los tokens nunca llegan al navegador, a la app móvil ni a terceros.

La aplicación trata únicamente los datos necesarios para vender: los datos de las ofertas de la tienda y los datos de los pedidos de Allegro - nombre y apellidos, dirección de entrega o punto de recogida, teléfono, dirección de correo electrónico en el dominio allegromail.pl, datos de facturación, productos pedidos y el mensaje al vendedor.

Los datos de los pedidos se usan exclusivamente para preparar y enviar ese pedido. La tienda no envía a los compradores de Allegro ningún correo electrónico - ni transaccional ni de marketing - y no utiliza sus datos con fines de marketing.

• La aplicación utiliza únicamente su propio Client ID y su propio Client Secret, guardados como secretos del servidor; no los comparte con nadie y nunca pide a los usuarios sus claves.
• Accede a una cuenta de vendedor solo mediante OAuth 2.0, con el consentimiento del vendedor y dentro de los permisos descritos arriba.
• Cada solicitud incluye una cabecera User-Agent fija que identifica la aplicación: Agilix-Sklep/1.0.0 (+https://agilix.dog/).
• La aplicación respeta los límites: consulta el registro de pedidos una vez por minuto, actualiza las ofertas solo tras un cambio en el producto y, tras una respuesta 429, espera el tiempo que indica la cabecera Retry-After.
• No descarga de forma masiva ofertas ni datos de otros vendedores y compradores; usa los datos de la API únicamente para gestionar las ventas de la cuenta conectada.
• Toda la comunicación se realiza solo por HTTPS y los tokens se almacenan cifrados.

El administrador puede hacer clic en "Desconectar" en los ajustes de la tienda en cualquier momento - el servidor elimina entonces los tokens guardados y los vínculos de las ofertas, y la aplicación deja de enviar solicitudes para esa cuenta. El acceso también puede revocarse desde Allegro, en los ajustes de la cuenta; la aplicación marca entonces la conexión como desconectada y se lo muestra al administrador.

Preguntas sobre la aplicación: adam@agilix.dog.