Estructura del Changelog
Cada versión se organiza en secciones para facilitar la lectura:- Added: nuevos recursos y funcionalidades.
- Changed: cambios en recursos existentes.
- Fixed: correcciones de bugs.
- Removed: recursos o funcionalidades eliminados.
- Deprecated: recursos o funcionalidades obsoletos y que serán eliminados en futuras versiones.
- Security: actualizaciones relacionadas con la seguridad.
- Performance: mejoras de rendimiento.
- Documentation: actualizaciones en la documentación.
- Notes: notas adicionales sobre la versión, como enlaces a pull requests, issues o detalles técnicos.
- Contributors: lista de colaboradores que contribuyeron a la versión, con enlaces a sus perfiles.
- Other: otros cambios que no encajan en las categorías anteriores.
Added
- Reglas avanzadas de cupones (
rules): soporte paraSINGLE_USE_PER_CUSTOMER(uso único por cliente),MIN_ORDER_AMOUNT(monto mínimo en centavos),AFFILIATE_ONLY(código o lista de códigos de afiliados),MIN_ITEMS_QUANTITYyPAYMENT_METHOD(pasarela/método específico).
- Nuevos límites de cantidad (
9999): máximo destock(productos),useLimit(cupones) yMIN_ITEMS_QUANTITYaumentado de999a9999(alineado al tope de precio de9999).
Added
- Paginación por cursor en todos los endpoints de listado:
GET /stores,GET /stores/:storeId/categories,GET /stores/:storeId/products,GET /stores/:storeId/coupons,GET /stores/:storeId/affiliates,GET /stores/:storeId/paymentsyGET /stores/:storeId/payments/filter. - Parámetro
cursor(string) para avanzar en la lista usandonextCursorde la respuesta anterior. - Parámetros
sortBy(campo) yorder(asc/desc) para ordenación en los endpoints con cursor. - Las respuestas incluyen
nextCursoryhasMoreen modo offset, permitiendo migración sin empezar desde cero. - Rastreo de clics de afiliados: endpoints públicos
POST /stores/:storeId/clicks(registra clic conref) yPOST /stores/:storeId/clicks/verify(valida origen y marca el script instalado). Validación de laOrigincontrastore.trackingDomain. - Campos de tracking en la tienda:
trackingDomain,scriptInstalledyscriptInstalledAtdevueltos porGET /stores/:storeIdy actualizables víaPUT /stores/:storeId(STORE_UPDATE). - Nueva sección Afiliados en la referencia de la API:
GET/POST /stores/:storeId/affiliatesyPUT/DELETE /stores/:storeId/affiliates/:affiliateId, concommissionRules(DEFAULT/PRODUCT/CATEGORY/COUPON, menorpositionvence) ystatistics=trueparastatistics/metrics. GET /stores/:storeId/payments/:paymentId: pago completo con productos (precio, stock, categorías) ymetadata(cupón enmetadata.items[].coupon).- Toggle de activar/desactivar gateway de pago (Mercado Pago y Asaas) directamente en la tarjeta, sin necesidad de volver a registrar las credenciales.
- Nueva ruta de reactivación en el backend:
POST /user/gatewayconactive: truey sin credenciales reactiva la gateway usando las claves ya guardadas. - Tarjeta colapsable de “Recebimento líquido por gateway” en el editor de producto, agrupada por gateway (Mercado Pago/Asaas), con previsión de tasa y valor neto por método.
- Indicador “Receita Bruta” junto a “Receita Líquida” en el dashboard.
- Botón “Atualizar dados” en el dashboard (ícono de refresh junto al selector de tienda) que recarga tiendas, pagos, categorías, productos y cupones en paralelo, con spinner de ~450ms.
- Realtime: actualización automática periódica en tiendas (60s), categorías, productos y cupones (30s).
- Logos reales de las gateways en
public/images/gateways/(Mercado Pago y Asaas) usados en los formularios del dashboard. - Asaas agregada a los tipos de los SDKs (
sdk-node-browser-bunysdk-java-kotlin): nuevas opcionesASAAS(gateway) yASAAS_ORDER_PIX/ASAAS_ORDER_CARD/ASAAS_ORDER_BOLETOenPaymentCreateGateway. - Parcelamiento en la tarjeta en el checkout (Asaas y Mercado Pago): selector de parcelas limitado al
maxInstallmentsconfigurado por el lojista en el form del gateway (por defecto1, máximo12). - Tabla de tasa por rango de parcelas (
installmentFees) en el form del gateway: cada rangode X hasta Y parcelastienepercent+fixedpropios, con hasta 12 rangos; validada en el front end (resaltado rojo por línea) y en el back end (solapamiento,min > max, límite). GET /stores/:storeId/feesahora exponemaxInstallmentsyinstallmentFeespor gateway, permitiendo al checkout mostrar las parcelas disponibles y las tasas reales (valores y porcentajes) configuradas.- Reautenticación step-up (código por e-mail, reutilizando el flujo 2FA) para acciones sensibles del dashboard, como ver credenciales de gateway y cambiar contraseña.
- Documentación de paginación en
limitations.mdxactualizada con sección dedicada a cursor. - El enlace de afiliado pasó a usar el
trackingDomainde la tienda (fallback para el dominio de la tienda), permitiendo rastreo en dominio externo. - Todos los endpoints
DELETEahora usan soft delete (deletedAt): el registro desaparece de los listados, pero se preserva en la base de datos (nunca más eliminación física). - Desactivar una gateway ahora preserva las credenciales registradas, permitiendo reactivar sin volver a escribir las claves (antes borraba las credenciales).
- Botón de gateway renombrado de “Remover” a “Desactivar” reflejando el nuevo comportamiento.
MetricCarddel dashboard con altura y alineación uniformes (h-full min-h-[92px],mt-autopara el trend), grid de 6 columnas para soportar el nuevo card de Receita Bruta.- Imágenes de las gateways reorganizadas de
public/images/banner/apublic/images/gateways/, con nombres normalizados (mp.jpg→mercadopago.jpg,assas.png→asaas.png). - Logos de las gateways en el card de recebimento del producto con redondeo medio (
rounded-md). - Sesiones más estables: tolerancia de 90s de gracia en
AUTH2y cambio de IP ya no destruye la sesión (solo la marca como sospechosa para reautenticación). - Precio cobrado en pago con tarjeta ahora usa el rango de parcelas de
installmentCount(installmentFees) en vez de la tasa plana defees.card, persistiendometadata.gateway.card.installmentCounten el pago — el valor cobrado pasa a coincidir con el mostrado en el checkout. - El número de parcelas elegido es el que vale en todas las gateways: la API valida el
installmentCountcontra elmaxInstallmentsde la tienda y rechaza por encima del límite (nuevos códigos400 INVALID_INSTALLMENT_COUNTy400 MAX_INSTALLMENTS_EXCEEDED, sinmessage— patrón de la ruta). - Las gateways de tarjeta (Asaas y Mercado Pago) aplican el
installmentCountelegido en todos los flujos: la Asaas divide el total igualmente en las N× (inclusive en la factura hospedada, antes solo en la tarjeta tokenizada) y el Mercado Pago limita el checkout al número elegido (max_installments).
- Error de hidratación de React causado por
<button>dentro de<button>en los encabezados de las tarjetas de gateway (el switch ahora es hermano del botón de expandir, no hijo). - Métodos de pago duplicados en la tarjeta de “Recebimento líquido” (aliases PIX/BANK_TRANSFER, CARD/CREDIT_CARD, BOLETO/TICKET) ahora deduplicados por label.
- Tasa menor que 1 centavo (ej.: 0,99% de R 0,01” en vez de desaparecer/quedar en cero.
- Reactivación de gateway sin credenciales registradas ahora devuelve error claro (
GATEWAY_NOT_FOUND/GATEWAY_NO_CREDENTIALS). - Checkout tarjeta: cada opción de parcela calculaba el valor con la tasa de la selección actual (y no de su propio rango), mostrando valores erróneos al alternar 1x/2x/… — corregido para
totalForInstallments(n)con el rango den. - Checkout 500:
ReferenceError: Cannot access 'discountAmount' before initializational aplicar cupón (declaración movida antes detotalForInstallments). - Rangos de parcelas duplicados/solapados ahora bloqueados al guardar la gateway (
400 INVALID_DATAen el back end + resaltado rojo en el form). - Step-up: mensajes de error nunca más muestran códigos crudos (
TOO_MANY_REQUESTSetc.) — fallback amigable en español.
- Changelog actualizado con el nuevo flujo de activar/desactivar gateways, tarjeta de recebimento líquido, botón de actualizar en el dashboard y organización de los logos.
api-reference/payment/post.mdxcon la tabla completa de gateways/métodos (<PROVEDOR>_ORDER_<MÉTODO>), ejemplos para Asaas (PIX) y documentación de las respuestas (QR code,init_point/invoiceUrl,pixQrCode).api-reference/payment/filter.mdxconASAASen el parámetro de filtrogateway(EFI_BANKmarcado como legado).api-reference/store/fees.mdxaclarando que las tasas retornadas son las definidas por el lojista (no el costo cobrado por la gateway), conforme configurado en el dashboard.api-reference/store/fees.mdxactualizado con los nuevos camposmaxInstallmentsyinstallmentFees(rangos de parcelas) por gateway.api-reference/payment/post.mdxdocumentando el parcelamiento en la tarjeta víametadata.gateway.card.installmentCount(límitemaxInstallments, tasa por rango aplicada sobre el total y persistencia delinstallmentCounten el pago), con ejemplo de tarjeta parcelada en 6x.api-reference/payment/post.mdxactualizado con el comportamiento final del parcelamiento: elegido vale en Asaas (factura hospedada y tokenizado) y Mercado Pago (limitado al elegido), rechazo por encima del límite y nuevos códigosINVALID_INSTALLMENT_COUNT/MAX_INSTALLMENTS_EXCEEDED(tabla de errores).- Changelog actualizado con la validación de parcelas, aplicación en las dos gateways y cobertura de tests (unitarios de
ASAAS_SERVICE/MERCADOPAGO_SERVICE+ rutas). - Repos de SDK actualizados con Asaas (SDK Node/Browser/Bun: tipos
PaymentGateway/PaymentCreateGateway+ camposinit_point,pixQrCode,copyPastePix; SDK Java: enums + README corregido). - README del SDK Java: valor desactualizado
MERCADOPAGO_SERVICE_PIXcorregido paraMERCADOPAGO_ORDER_PIX.
- @sebastianjnuwu - Sebastian Jn.
Added
- Servicio centralizado
SendPushen la API para unificar el envío de notificaciones Firebase. - Soporte a envío de push con
token,tokens,url,route,typeydataen el mismo payload. - Apertura automática del pago específico al hacer clic en la notificación, usando
paymentIden el flujo del dashboard. - Nuevo control de bono de renovación en la suscripción: al contratar un nuevo plan, el usuario puede recibir los días restantes como bono, con límite máximo de 7 días.
- Ajuste en el seed de la API para activar solo la suscripción estándar definida en
SEED_ACTIVE_PLAN, sin recrear usuario o tienda. - Mejoras visuales en la tarjeta de suscripción del dashboard, con íconos en los campos de plan, vencimiento y status.
- Soporte al campo opcional
metadata(JSON) en el modelo de categorías de la API. - Persistencia y retorno de
metadataen los flujos de creación, edición y consulta de categorías (POST,PUT,GETyGET por ID). - Campo de metadata en formato JSON en el panel de categorías (Sitio) para crear y editar usando editor Monaco, con validación de sintaxis en tiempo real.
- Nuevo sistema automático de reversión de stock y cupón cuando los pagos no se concluyen.
- Función utility
revertPaymentAllocation()para revertir atómamente la asignación de stock y useLimit de cupones. - Integración de reversión automática en el flujo de expiración de pagos (después de 24h sin confirmación).
- Integración de reversión automática en el webhook de Mercado Pago para status:
REJECTED,CANCELLED,REFUNDED,CHARGED_BACK. - Nuevo endpoint privado de filtros para pagos:
GET /stores/:storeId/payments/filter. - Soporte a filtros combinables por campos del pago:
id,uuid,status,name,email,cpf,price,coupon,gateway,shipment, etc, paginación y ordenación. - Soporte a filtros de metadata con camino anidado (dot notation), por ejemplo:
metadataKey=items.0.product.sold&metadataValue=19. - Nuevas rutas autenticadas de push token en la API:
POST /user/push-token(registro) yDELETE /user/push-token(remoción). - Nuevo flujo de bienvenida vía Firebase en el registro de token: al registrar un token válido, el sistema envía una notificación inicial de confirmación.
- Persistencia de tokens en
user.metadata.pushTokenscon actualización del caché Redis del usuario tras cambios.
- Flujo de suscripción actualizado para disparar notificación push y e-mail de plan activado con el mismo patrón de contexto.
- Push de pago actualizado para abrir directamente la pestaña de pagos y enfocar el pago correspondiente.
- Service worker del sitio ajustado para respetar
url,routeyhashal abrir notificaciones. - Frontend de Firebase ajustado para redirigir notificaciones en foreground con el mismo comportamiento del service worker.
- Lógica de suscripción actualizada para calcular días bono con base en el vencimiento actual de la suscripción activa.
- Tarjeta de suscripción del dashboard simplificada para mostrar solo el status basado en el vencimiento.
- Flujo de categorías en el frontend actualizado para enviar payload con
metadatajunto a los demás campos. - Cliente de API del sitio para categorías actualizado para aceptar
metadataopcional en creación y actualización. - Clave de caché de categorías mantenida en el patrón original (
stores:{storeId}:categories) tras ajustes en el rollout. - Flujo de expiración de pago (
paymentQueue) ahora revierte stock y cupón antes de marcar comoEXPIRED. - Webhook de Mercado Pago ahora detecta automáticamente fallos de pago y revierte las asignaciones correspondientes.
- Controller de filtros de pagos ajustado para tratar metadata anidada con mayor consistencia.
- Lógica de filtro de metadata consolidada para evitar sobrescritura entre criterios (
metadataKey,metadataValue). - Navegación de la documentación actualizada para incluir la nueva página
api-reference/payment/filteren la sección de Pagos. - Ajuste de nomenclatura y formateo para mantener consistencia con otras páginas de API.
- Lógica de registro de push token actualizada para evitar duplicidad, mantener hasta 3 tokens por usuario y priorizar los tokens más recientes.
- Service Worker de notificaciones del sitio revisado para soportar mejor payloads Firebase en background y visualización más completa (title/body/icon/image/badge).
- Agregado tratamiento de clic en notificación en el Service Worker para enfocar ventana existente o abrir la URL enviada en el payload.
- Corrección del clic en notificaciones para evitar apertura genérica de la página inicial cuando existe destino específico.
- Normalización automática de campos del payload de push para evitar envío de valores no soportados por FCM.
- Corrección crítica: stock y cupones NO se revertían cuando los pagos fallaban, resultando en inconsistencia de datos.
- Implementación de reversión transaccional para garantizar consistencia incluso en fallos parciales.
- Ajustes en el flujo de visualización de push en background para reducir casos en que la notificación no aparecía correctamente en algunos payloads.
- Changelog actualizado con la refactorización del flujo de push y la integración de apertura directa del pago vía notificación.
- Referencia de la API de categorías actualizada para incluir el campo
metadataen los endpoints:api-reference/category/postapi-reference/category/putapi-reference/category/getapi-reference/category/get-by-id
- Ejemplos de request/response de categoría revisados para reflejar payload y retorno con
metadata. - Documentación de límites de productos y cupones actualizada para reflejar comportamiento de reversión en pagos no aprobados.
- Changelog actualizado con las mejoras de notificaciones push (API + Sitio) implementadas en esta fecha.
- @sebastianjnuwu - Sebastian Jn.
Added
- Actualización de los models User y Store para soportar URLs de webhook (API)
- Refactorización del upload de imágenes para usar blob server interno y actualización de los componentes relacionados (Sitio)
- Mejora de la gestión de webhooks con mejor control de estado y feedback al usuario (Sitio)
- Nueva estructura de documentación para Webhooks: sección propia, endpoints GET/POST/DELETE documentados por separado.
- Documentación de payload cifrado y ejemplo de descifrado en el tutorial.
- Revisión del job de expiración de planes (
billing.job.js) para garantizar compatibilidad con la estructura actual de suscripciones basada enUserSubscriptionHistory. - Validación de la lógica de suscripción activa usando
getPrimarySubscriptiony verificación de los criterios de expiración y notificaciones. - Función minimalista para setear plan del usuario (
setUserPlan). - Refactorización del helper
ACTIVE_SUBSCRIPTIONpara lógica directa y enxuta. - Validación y documentación de los códigos de error del endpoint de creación de tienda.
- Ajuste en el frontend: tratamiento de errores en el modal de creación de tienda ahora impide feedback de éxito indebido.
- Soporte a múltiples métodos de pago vía Mercado Pago: PIX y Tarjeta de Crédito (
MERCADOPAGO_SERVICE_PIX,MERCADOPAGO_SERVICE_CARD). - Campo
feeAppliedToen las credenciales del gateway para definir en qué métodos de pago se aplica la tasa (ej.: solo tarjeta, solo pix, o ambos). - Estructura estándar de respuesta de pago con objetos
serviceypaymentseparados. - Registro del campo
gatewayMethoden los metadatos internos del pago para trazabilidad. - Changelog actualizado para documentar los nuevos schedulers automáticos (UserDelete, Billing) y la traducción de todos los mensajes de scheduler/fila a inglés.
- Opción para configurar tasa (%) repasada al cliente al usar gateways de pago (frontend y backend).
- Campo
feePercentageahora puede definirse por gateway y guardarse en las credenciales cifradas. - Aplicación automática de la tasa en el valor final del pago, tanto en la API pública como en la admin.
- Registro de los campos
gatewayFeePercentageygatewayFeeAmounten los metadatos del pago. - IDs y htmlFor de los campos del modal de gateways ahora siguen el patrón
gateway-TIPO-campopara compatibilidad y accesibilidad. - Mensajes de validación de las gateways mostrados en portugués, tanto en frontend como backend.
- Aba dedicada Changelog en la navegación principal de la documentación.
- Estructura inicial para registro continuo de versiones y cambios.
- Copiar el ID de usuario en el modal del perfil para facilitar la integración con otras herramientas.
- Soporte a ordenación de categorías con campo
positionen el backend. - Nuevo endpoint privado
PUT /stores/:storeId/categories/reorderpara guardar el orden por lista de IDs. - Acciones de panel para organizar categorías con
Mover para cimayMover para baixo. - Soporte a ordenación de productos, cupones y tiendas con campo
positionen el backend. - Nuevos endpoints privados
PUT /stores/:storeId/products/reorder,PUT /stores/:storeId/coupons/reorderyPUT /stores/reorder. - Acciones de panel para organizar productos, cupones y tiendas con
Mover para cimayMover para baixo.
- Ajuste en el package.json de la API y del Sitio para nueva versión 15.03.2026
- Ajuste en el control de sesión y logging de errores en los controllers de autenticación (API)
- Navegación de la documentación reorganizada: webhooks ya no aparecen en tiendas, sino en grupo propio.
- Tutorial de webhooks revisado para alinearse con la API real y el formato cifrado.
- Ajuste en los ejemplos y explicaciones para reflejar la implementación real del backend.
- Documentación del flujo de suscripción y expiración revisada vía IA.
- Refactorización de los schedulers y filas: nombres de jobs y filas estandarizados para evitar conflictos y garantizar procesamiento correcto.
- Limpieza automática de jobs concluidos y fallidos ahora es estándar en todas las filas (removeOnComplete/removeOnFail).
- Actualización de los métodos de programación para usar solo las opciones esenciales, centralizando la configuración de limpieza en el core de la fila.
- Actualización del webhook de suscripción para usar la nueva firma de
ACTIVE_SUBSCRIPTION. - Estandarización de los retornos de status y códigos de error en el backend de tiendas.
- Lógica de cálculo de tasa (
feePercentage) ahora considerafeeAppliedTo— la tasa solo se aplica si el método de pago está listado. - Respuesta de la API de pago reestructurada: ahora retorna
{ service, payment }en vez de datos planos. - Pagos gratuitos ahora retornan
service.type: "FREE_PAYMENT"para consistencia con los demás flujos. - Gateway de tarjeta migrado a Checkout Pro de Mercado Pago con exclusión de métodos no deseados vía
excluded_payment_typesyexcluded_payment_methods. - Estructura de los metadatos de pago en la API admin ahora es idéntica a la pública para tasas de gateway.
- Validación mejorada para garantizar que
feePercentagesea respetado y aplicado correctamente. - Dashboard de pagos ahora muestra los pagos más recientes por defecto, incluso en la opción “Todos”.
- Ajuste en los checkboxes de métodos de pago para garantizar compatibilidad con el backend y scripts de validación.
- Ajuste de navegación para separar actualizaciones de la aba de tutoriales.
- Mejora en el agrupamiento de la documentación para facilitar descubrimiento de cambios recientes.
GET /stores/:storeId/categoriesahora retorna categorías en el orden deposition.GET /stores/:storeId/categories/:categoryIdy respuestas de creación/edición de categoría ahora incluyenposition.GET /stores,GET /stores/:storeId/productsyGET /stores/:storeId/couponsahora retornan datos en el orden deposition.- Respuestas de creación/edición y detalles de productos, cupones y tiendas ahora incluyen
position.
- Corrección de logging de error y ajuste en el skip de recuperación de sesión en los controllers de autenticación (API)
- E-mails de expiración y expiración de plan revisados y corregidos, ahora enviados con nuevo diseño estandarizado.
- Corrección del job de expiración para procesar suscripciones ya vencidas, no solo activas.
- Actualización directa del metadata del histórico de suscripción, sin dependencia de función externa.
- Corrección del switch/case de errores en el modal de creación de tienda para garantizar UX correcta.
- Ajuste de clases Tailwind para evitar warnings de build.
- Corrección de bug donde
MERCADOPAGO_SERVICEno retornaba el resultado de axios por ausencia dereturn. - Corrección de bug donde
value.gatewayera sobrescrito congatewayType, haciendo que el servicio siempre cayera en el flujoUNSUPPORTED_PAYMENT_TYPE. - Corrección del campo
gatewayguardado en la base para usar el enum correcto de Prisma (MERCADOPAGO) en vez del método completo. - Eliminación de
default_payment_method_id: "credit_card"que causaba errorinvalid default_payment_method_iden la API de Mercado Pago. - Corrección de error de reasignación de variable (
finalPrice) en el controller de pago admin. - Ajustes para garantizar consistencia entre API pública y admin en la lógica de tasas.
- Corrección de error
TypeError: Cannot read properties of undefined (reading 'split')al guardar gateways sin id en los inputs. - Chequeo extra para ignorar elementos sin id en el script de gateways.
- Aplicación de optional chaining (
?.) para evitar errores de acceso a propiedades indefinidas. - Chequeo de lint/type en API y site para garantizar ausencia de errores críticos.
- Corrección de links rotos relacionados con tutoriales de integración.
- Corrección de inconsistencias en la nomenclatura de versiones anteriores.
- Corrección de formateo en secciones de changelog anteriores.
- Errores de rutas que eran privadas y ahora son públicas.
- Eliminado campo/mención de webhooks de la respuesta de tienda en la documentación.
- Archivo antiguo de webhooks dentro de stores eliminado.
- Actualización de versión y dependencias en los paquetes (API y Sitio)
- Nueva página de referencia para el endpoint
POST /stores/:storeId/paymentscon ejemplos de solicitud, snippets cURL y respuestas documentadas para PIX, Tarjeta y pago gratuito. - Actualización de la documentación para incluir el changelog e instrucciones de uso.
- Nuevos tutoriales de integración agregados a la documentación, como Mercado Pago, EFI Bank (apenas las abas).
- Documentación de la API de categorías actualizada con el campo
position. - Nueva página de la API para reordenación:
api-reference/category/reorder. - Documentación de la API de productos, cupones y tiendas actualizada con el campo
position. - Nuevas páginas de reordenación:
api-reference/product/reorder,api-reference/coupon/reorderyapi-reference/store/reorder.
- Esta es la versión inicial del changelog, y las versiones anteriores se están documentando retroactivamente.
- Las versiones anteriores se están revisando para garantizar que todos los cambios significativos sean registrados.
- El changelog se actualizará regularmente con cada nueva versión lanzada, y las versiones anteriores se revisarán para garantizar que todos los cambios significativos sean registrados.
- @sebastianjnuwu - Sebastian Jn.