Aprende a planificar, diseñar y construir una aplicación web para gestionar disputas en un marketplace: intake de casos, evidencia, flujos, roles, pista de auditoría, integraciones e informes.
Una app de disputas no es solo un “formulario de soporte con un estado”. Es el sistema que decide cómo se mueven el dinero, los artículos y la confianza en tu marketplace cuando algo falla. Antes de dibujar pantallas o tablas, define claramente el espacio del problema; de lo contrario acabarás con una herramienta fácil de usar pero difícil de aplicar.
Empieza listando los tipos de disputa que realmente necesitas gestionar y cómo difieren. Categorías comunes incluyen:
Cada tipo suele requerir evidencia distinta, ventanas temporales y resultados (reembolso, reemplazo, reembolso parcial, reversión de pago al vendedor). Trata el tipo de disputa como un motor del flujo de trabajo, no solo como una etiqueta.
El manejo de disputas suele competir entre rapidez, consistencia y prevención de pérdidas. Escribe qué significa el éxito en tu contexto:
Estos objetivos influyen en todo, desde qué datos recolectas hasta qué acciones automatizas.
La mayoría de marketplaces tienen más que “soporte al cliente”. Usuarios típicos incluyen compradores, vendedores, agentes de soporte, admins y finanzas/riesgos. Cada grupo necesita una vista distinta:
Una v1 sólida suele centrarse en: crear un caso, recopilar evidencia, mensajería, seguimiento de plazos y registrar una decisión con pista de auditoría.
Lanzamientos posteriores pueden añadir: reglas de reembolso automáticas, señales de fraude, analíticas avanzadas e integraciones más profundas. Mantener el alcance ajustado al principio evita un sistema “hacerlo todo” en el que nadie confía.
Si vas rápido, ayuda prototipar el flujo de extremo a extremo antes de comprometerte con todo el desarrollo. Por ejemplo, algunos equipos usan Koder.ai (una plataforma de vibe-coding) para generar rápidamente un panel admin en React + backend Go/PostgreSQL a partir de una especificación por chat, y luego exportan el código fuente una vez que los estados de caso y permisos están bien definidos.
Una app de disputas triunfa o fracasa según si refleja cómo se mueven realmente las disputas en tu marketplace. Empieza mapeando el recorrido actual de extremo a extremo y convierte ese mapa en un pequeño conjunto de estados y reglas que el sistema pueda aplicar.
Escribe la “ruta feliz” como una línea de tiempo: intake → recopilación de evidencia → revisión → decisión → pago/reembolso. Para cada paso, anota:
Esto será la columna vertebral para automatizaciones, recordatorios e informes.
Mantén los estados mutuamente excluyentes y fáciles de entender. Una base práctica:
Para cada estado, define criterios de entrada, transiciones permitidas y campos requeridos antes de avanzar. Esto evita casos bloqueados y resultados inconsistentes.
Asocia plazos a los estados (p. ej., el vendedor tiene 72 horas para aportar tracking). Añade recordatorios automáticos y decide qué pasa cuando se agota el tiempo: cierre automático, decisión por defecto o escalado a revisión manual.
Modela los resultados por separado de los estados para poder rastrear lo que ocurrió: reembolso, reembolso parcial, reemplazo, liberar fondos, restricción/baneo de cuenta o crédito de cortesía.
Las disputas se complican. Incluye rutas para tracking faltante, envíos divididos, pruebas de entrega de bienes digitales y pedidos con múltiples artículos (decisiones a nivel de artículo vs a nivel de pedido). Diseñar estas ramas desde el principio evita manejos ad-hoc que rompen la consistencia.
Una app de disputas tiene éxito si el modelo de datos responde a las preguntas del mundo real: “¿Qué pasó?”, “¿Cuál es la prueba?”, “¿Qué decidimos?” y “¿Podemos mostrar una pista de auditoría más tarde?”. Empieza nombrando un pequeño conjunto de entidades centrales y sé estricto sobre lo que puede cambiar.
Como mínimo, modela:
Mantén “Disputa” enfocado: debe referenciar el pedido/pago, almacenar estado, plazos y punteros a evidencia y decisiones.
Trata todo lo que debe ser defendible más tarde como append-only:
Permite ediciones solo por conveniencia operativa:
Esta división es más sencilla con una tabla de pista de auditoría (registro de eventos) más campos “snapshot” actuales en el caso.
Define validaciones estrictas desde temprano:
Planifica el almacenamiento de evidencia: tipos de archivo permitidos, límites de tamaño, escaneo antivirus y reglas de retención (p. ej., auto-eliminar tras X meses si la política lo permite). Guarda metadatos del archivo (hash, uploader, timestamp) y almacena el blob en object storage.
Usa un esquema consistente y legible para IDs de caso (p. ej., DSP-2025-000123). Indexa campos buscables como ID de pedido, ID de comprador/vendedor, estado, motivo, rango de importe y fechas clave para que los agentes encuentren casos rápido desde la cola.
Las disputas implican múltiples partes y datos de alto riesgo. Un modelo de roles claro reduce errores, acelera decisiones y ayuda a cumplir requisitos.
Empieza con un conjunto pequeño y explícito de roles y mapea las acciones, no solo las pantallas:
Usa permisos de menor privilegio por defecto y añade acceso “romper vidrio” solo para emergencias auditadas.
Para el personal, soporta SSO (SAML/OIDC) cuando sea posible para que el acceso siga el ciclo de vida de RR. HH. Requiere MFA para roles privilegiados (supervisor, finanzas, admin) y para cualquier acción que cambie dinero o una decisión final.
El control de sesiones importa: tokens de corta duración para herramientas staff, refresh ligados a dispositivo cuando sea posible y cierre automático en estaciones compartidas.
Separa los “hechos del caso” de los campos sensibles. Aplica permisos por campo para:
Redacta por defecto en la UI y en logs. Si alguien necesita acceso, registra el motivo.
Mantén un registro de auditoría inmutable para acciones sensibles: cambios de decisión, reembolsos, retenciones de pago, eliminación de evidencia, cambios de permisos. Incluye timestamp, actor, valores viejo/nuevo y origen (API/UI).
Para la evidencia, define reglas de consentimiento y compartición: qué puede ver la otra parte, qué permanece interno (por ejemplo, señales de fraude) y qué debe redactarse parcialmente antes de compartirse.
Una herramienta de disputas vive o muere por velocidad: qué tan rápido un agente puede triagear un caso, entender qué pasó y tomar una acción segura. La UI debe dejar claro “qué necesita atención ahora”, manteniendo los datos sensibles y las decisiones irreversibles difíciles de activar por accidente.
Tu lista de casos debe comportarse como una consola de operaciones, no como una tabla genérica. Incluye filtros que reflejen cómo trabaja el equipo: estado, motivo, importe, edad/SLA, vendedor y puntuación de riesgo. Añade vistas guardadas (p. ej., “Nuevos de alto valor”, “Atrasados”, “A la espera del comprador”) para que los agentes no reconstruyan filtros cada día.
Haz que las filas sean fáciles de escanear: ID de caso, chip de estado, días abierto, importe, parte (comprador/vendedor), indicador de riesgo y próximo plazo. Mantén el orden predecible (por defecto por urgencia/SLA). Las acciones masivas son útiles, pero limítalas a operaciones seguras como asignar/quitar o añadir etiquetas.
La página de detalle debe responder tres preguntas en segundos:
Un diseño práctico es una línea de tiempo en el centro (eventos, cambios de estado, señales de pago/envío), con un panel a la derecha de snapshot para contexto del pedido/pago (total del pedido, método de pago, estado del envío, reembolsos/contracargos, IDs clave). Mantén enlaces profundos a objetos relacionados (pedido, pago, envío) como rutas relativas tipo /orders/123 y /payments/abc.
Añade un área de mensajes y una galería de evidencia con vista previa rápida (imágenes, PDFs) y metadatos (quién subió, cuándo, tipo, estado de verificación). Los agentes nunca deberían buscar en montones de adjuntos para entender la última actualización.
Las acciones de decisión (reembolsar, denegar, pedir más info, escalar) deben ser inequívocas. Usa confirmaciones para pasos irreversibles y exige entradas estructuradas: nota obligatoria, código de motivo y plantillas de decisión opcionales para mantener consistencia.
Separa canales de colaboración: notas internas (solo agentes, para traspasos) vs mensajes externos (visibles para comprador/vendedor). Incluye controles de asignación y un “propietario actual” visible para evitar trabajo duplicado.
Diseña para navegación por teclado, contraste legible y etiquetas para lectores de pantalla—especialmente en botones de acción y campos. Las vistas móviles deben priorizar el snapshot, el último mensaje, el próximo plazo y una ruta de un toque a la galería de evidencia para revisiones rápidas durante guardias.
Las disputas son mayormente problemas de comunicación con un temporizador adjunto. Tu app debe dejar claro quién tiene que hacer qué, cuándo y por qué canal—sin obligar a la gente a buscar en hilos de correo.
Usa mensajería in-app como fuente de la verdad: cada solicitud, respuesta y adjunto debe vivir en la línea del tiempo del caso. Luego replica actualizaciones clave por email (nuevo mensaje, solicitud de evidencia, plazo próximo, decisión emitida). Si añades SMS, úsalo para avisos sensibles al tiempo (p. ej., “Plazo en 24 horas”) y evita incluir detalles confidenciales.
Crea plantillas para solicitudes comunes para que los agentes mantengan consistencia y los usuarios sepan qué evidencia es “buena”:
Permite placeholders como ID de pedido, fechas e importes, y un área corta para edición humana para que las respuestas no parezcan robóticas.
Cada solicitud debe generar un plazo (p. ej., el vendedor tiene 3 días hábiles para responder). Muéstralo de forma prominente en el caso, envía recordatorios automáticos (48 h y 24 h) y define resultados claros por falta de respuesta (auto-cierre, auto-reembolso o escalado).
Si atiendes varias regiones, almacena el contenido de mensajes con una etiqueta de idioma y ofrece plantillas localizadas. Para prevenir abuso, añade límites por tasa por caso/usuario, límites de tamaño/tipo de adjuntos, escaneo antivirus y renderizado seguro (sin HTML inline, sanitiza nombres de archivo). Mantén una pista de auditoría de quién envió qué y cuándo.
La evidencia es donde se ganan o pierden la mayoría de disputas, así que tu app debe tratarla como un flujo de trabajo de primera clase, no como una pila de adjuntos.
Empieza definiendo tipos de evidencia esperados: enlaces/escaneos de tracking, fotos del embalaje o daño, facturas/recibos, registros de chat, etiquetas de devolución y notas internas. Hacer explícitos estos tipos ayuda a validar entradas, estandarizar la revisión y mejorar informes más adelante.
Evita pedir “sube cualquier cosa”. Genera solicitudes estructuradas desde el motivo (p. ej., “Artículo no recibido” → tracking del transportista + prueba de entrega; “No conforme” → captura del anuncio + fotos del comprador). Cada solicitud debe incluir:
Esto reduce idas y vueltas y hace los casos comparables entre revisores.
Trata la evidencia como registros sensibles. Para cada carga, guarda:
Estos controles no “demuestran” que el contenido sea veraz, pero sí prueban si el archivo fue alterado tras la presentación y quién lo manejó.
Las disputas a menudo terminan en revisión externa (procesador de pagos, transportista, arbitraje). Proporciona una exportación con un clic que empaquete archivos clave más un resumen: hechos del caso, línea de tiempo, metadata del pedido e índice de evidencia. Mantén el formato consistente para que los equipos confíen en él bajo presión.
La evidencia puede contener datos personales. Implementa reglas de retención por tipo de disputa y región, más un proceso de eliminación rastreado (con aprobaciones y logs) cuando sea legalmente necesario.
La decisión es donde una app de disputas construye confianza o genera más trabajo. El objetivo es consistencia: casos similares deben tener resultados similares y ambas partes deben entender por qué.
Define políticas como reglas legibles, no en prosa legal. Para cada motivo de disputa, documenta:
Versiona estas políticas para poder explicar decisiones tomadas bajo reglas antiguas y reducir la “deriva” de políticas con el tiempo.
Una buena pantalla de decisión empuja al revisor hacia resultados completos y defendibles.
Usa listas de verificación por motivo que aparezcan automáticamente en la vista del caso (por ejemplo: “escaneo del transportista presente”, “foto muestra daño”, “el anuncio prometía X”). Cada ítem puede:
Esto crea una pista de auditoría consistente sin obligar a todos a escribir desde cero.
La decisión debe calcular el impacto financiero, no dejarlo en hojas de cálculo. Guarda y muestra:
Deja claro si el sistema emitirá automáticamente el reembolso o generará una tarea para finanzas/soporte (especialmente cuando los pagos están divididos o parcialmente capturados).
Las apelaciones reducen la frustración cuando aparece nueva información, pero pueden convertirse en bucles infinitos.
Define: cuándo se permiten apelaciones, qué significa “evidencia nueva”, quién revisa (preferiblemente un revisor distinto), y cuántos intentos están permitidos. En la apelación, congela la decisión original y crea un registro vinculado para distinguir informe inicial vs final.
Cada decisión debe generar dos mensajes: uno para el comprador y otro para el vendedor. Usa lenguaje claro, lista la evidencia clave considerada y explica los siguientes pasos (incluyendo elegibilidad y plazos para apelación). Evita jerga y culpar a las partes: céntrate en hechos y política.
Las integraciones transforman una herramienta de disputas de un “bloc de notas” en un sistema que puede verificar hechos y ejecutar resultados de forma segura. Empieza por listar los sistemas externos que deben concordar la realidad: gestión de pedidos (qué se compró), pagos (qué se capturó/reembolsó), transportistas (qué se entregó) y tu proveedor de email/SMS (qué se comunicó y cuándo).
Para cambios sensibles en tiempo—alertas de contracargo, estado de reembolso o actualizaciones de tickets—prefiere webhooks. Reducen la latencia y mantienen la línea de tiempo exacta.
Usa sincronización programada cuando los webhooks no estén disponibles o sean poco fiables (común con transportistas). Un híbrido práctico es:
Sea cual sea, guarda el “último estado externo conocido” en el caso y conserva la carga útil cruda para auditoría y depuración.
Las acciones financieras deben ser a prueba de repeticiones. Reintentos de red, dobles clics y re-entregas de webhooks pueden generar reembolsos duplicados.
Haz cada llamada que afecte dinero idempotente:
case_id + decision_id + action_type)Este patrón aplica también a reembolsos parciales, anulaciones y reversiones de tarifas.
Cuando algo no coincida (un reembolso aparece “pendiente” o falta un escaneo), tu equipo necesita visibilidad. Registra cada evento de integración con:
Expón una pestaña ligera de “Integración” en el detalle de caso para que soporte pueda auto-servirse.
Planifica entornos seguros desde el día uno: sandbox del procesador de pagos, números de tracking de prueba (o respuestas mockeadas del transportista) y “destinatarios de prueba” para email/SMS. Añade un banner visible de “modo prueba” en no-producción para que QA no ejecute reembolsos reales.
Si construyes herramientas admin, documenta credenciales y scopes requeridos en una página interna como /docs/integrations para que la configuración sea reproducible.
Un sistema de gestión de disputas crece rápido: cargas de evidencia, búsquedas de pagos, recordatorios, informes—por eso la arquitectura debe ser aburrida y modular.
Para v1, prioriza lo que tu equipo ya domina. Una configuración convencional (React/Vue + API REST/GraphQL + Postgres) suele ser más rápida que experimentar con frameworks nuevos. El objetivo es entrega predecible, no novedad.
Si quieres acelerar la primera iteración sin encerrarte en una caja negra, una plataforma como Koder.ai puede ayudar a generar una base funcionando (React + Go + PostgreSQL) desde una especificación por escrito, manteniendo la opción de exportar el código fuente y tomar la propiedad total.
Mantén límites claros entre:
Esta separación facilita escalar partes específicas (p. ej., procesamiento en background) sin rehacer toda la app.
La recolección y verificación de evidencia suele implicar escaneo antivirus, OCR, conversiones de archivo y llamadas externas. Exportes y recordatorios programados también son pesados. Pon estas tareas detrás de una cola para que la UI siga rápida y los usuarios no reenvíen acciones. Muestra el estado de los jobs en el caso para que los operadores vean qué está pendiente.
Las colas de casos viven y mueren por la búsqueda. Diseña filtrado por estado, SLA/plazos, método de pago, banderas de riesgo y agente asignado. Añade índices pronto y considera búsqueda full-text solo si el indexado básico no basta. Diseña paginación y “vistas guardadas” para flujos habituales.
Define staging y producción desde el inicio, con datos semilla que reflejen escenarios reales (flujo de contracargo, automatización de reembolso, apelaciones). Usa migraciones versionadas, feature flags para cambios riesgosos y un plan de rollback para poder desplegar con frecuencia sin romper casos activos.
Si tu equipo valora iteración rápida, funciones como snapshots y rollback (disponibles en plataformas como Koder.ai) pueden complementar los controles tradicionales de release, especialmente mientras flujos y permisos evolucionan.
Un sistema de disputas mejora cuando puedes ver qué pasa a través de los casos—rápido. Reporting no es solo para la dirección: ayuda a agentes a priorizar, a managers a detectar riesgos operativos y al negocio a ajustar políticas antes de que los costes crezcan.
Mide un conjunto pequeño de KPIs accionables y hazlos visibles en todas partes:
Los agentes necesitan una vista operativa: “¿Qué debo atender ahora?” Construye un dashboard estilo cola que destaque SLA incumplidos, plazos próximos y casos con evidencia faltante.
Los managers necesitan detección de patrones: picos en motivos concretos, vendedores de alto riesgo, totales de reembolso inusuales y caídas de tasa de éxito tras cambios de política. Una vista semanal suele ser más útil que una página gráfica sobrecargada.
Soporta exportes CSV e informes programados, pero añade protecciones:
La analítica solo funciona si los casos están etiquetados consistentemente. Usa códigos de motivo controlados, etiquetas opcionales (libre pero normalizadas) y avisos de validación cuando un agente cierre un caso con “Otro”.
Trata el reporting como un ciclo de retroalimentación: revisa las principales causas de pérdida mensualmente, ajusta listas de verificación de evidencia, refina umbrales de auto-reembolso y documenta cambios para que las mejoras aparezcan en cohortes futuras.
Lanzar un sistema de disputas no es tanto pulir la UI como asegurarse de que se comporte correctamente bajo estrés: evidencia faltante, respuestas tardías, casos límite de pago y controles de acceso estrictos.
Escribe pruebas que sigan flujos reales de extremo a extremo: abrir → solicitar/recibir evidencia → decidir → payout/reembolso/retención. Incluye caminos negativos y transiciones basadas en tiempo:
Automatiza estas pruebas alrededor de tus APIs y jobs background; mantén un conjunto pequeño de scripts manuales exploratorios para regresiones en UI.
Los fallos en control de acceso son de alto impacto. Construye una matriz de permisos por rol (comprador, vendedor, agente, supervisor, finanzas, admin) y verifica:
Las apps de disputa dependen de jobs e integraciones. Añade monitorización para:
Prepara un runbook interno con problemas comunes, rutas de escalado y sobrescrituras manuales (reabrir caso, extender plazo, revertir/reparar reembolso, volver a pedir evidencia). Luego despliega en fases:
Cuando iteras rápido, un “modo planificación” estructurado (como el que ofrecen plataformas tipo Koder.ai) puede ayudar a alinear stakeholders en estados, roles e integraciones antes de hacer cambios en producción.
Comience por definir los tipos de disputas (artículo no recibido, no conforme/dañado, fraude/no autorizado, contracargos) y mapee cada uno a requisitos de evidencia, ventanas temporales y posibles resultados distintos. Trate el tipo de disputa como el motor del flujo de trabajo para que el sistema pueda imponer pasos y plazos coherentes.
Un v1 práctico suele incluir: creación de casos, recopilación estructurada de evidencia, mensajería in-app que se refleja por correo electrónico, plazos SLA con recordatorios, una cola básica para agentes y registro de decisiones con una pista de auditoría inmutable. Deje las automatizaciones avanzadas (puntuación de fraude, reglas de auto-reembolso, analíticas complejas) para cuando el flujo de trabajo central sea fiable.
Use un conjunto pequeño y mutuamente exclusivo como:
Para cada estado, defina criterios de entrada, transiciones permitidas y campos requeridos antes de avanzar (por ejemplo: no se puede entrar en “En revisión” sin la evidencia obligatoria para ese código de motivo).
Establezca plazos por estado/acción (p. ej., “el vendedor tiene 72 horas para aportar el número de seguimiento”), automatice recordatorios (48 h/24 h) y defina resultados por defecto cuando el tiempo expire (auto-cierre, auto-reembolso o escalado). Haga visibles los plazos tanto en la cola (para priorización) como en el detalle del caso (para claridad).
Separe el estado (dónde está el caso en el flujo) del resultado (qué se ejecutó). Los resultados suelen incluir reembolso, reembolso parcial, reemplazo, liberación de fondos, reversión de pago, restricción de cuenta o crédito de cortesía. Esto permite reportar con precisión aunque el mismo estado (“Resuelto”) implique acciones financieras diferentes.
Como mínimo modele: Pedido, Pago, Usuario, Caso/Disputa, Motivo (códigos controlados), Evidencia, Mensajes y Decisión. Mantenga la información defendible en modo append-only mediante un registro de eventos (cambios de estado, cargas de evidencia, decisiones, movimientos de dinero), y permita ediciones limitadas para campos operativos como notas internas, etiquetas y asignaciones.
Trate los artefactos sensibles y defendibles como de solo escritura:
Acompañe esto con una “instantánea actual” en el caso para consultas UI rápidas. Esto facilita investigaciones, apelaciones y la preparación de paquetes de contracargo.
Defina roles explícitos (comprador, vendedor, agente, supervisor, finanzas, admin) y conceda permisos por acción, no solo por pantalla. Use privilegios mínimos por defecto, SSO + MFA para personal con privilegios y enmascaramiento por campo para PII/datos de pago. Mantenga notas internas y señales de riesgo ocultas a las partes externas, con acceso de “romper vidrio” auditado para excepciones.
Cree una cola estilo operaciones con filtros que reflejen la tría real: estado, motivo, importe, antigüedad/SLA, vendedor y puntuación de riesgo. Haga las filas escaneables (ID de caso, chip de estado, días abiertos, importe, parte, riesgo, próximo plazo) y añada vistas guardadas como “Atrasados” o “Nuevos de alto valor”. Limite las acciones masivas a operaciones seguras como asignar/quitar o etiquetar.
Use mensajería in-app como fuente de la verdad, refleje eventos clave por correo electrónico y use SMS solo para avisos sensibles al tiempo sin contenido confidencial. Genere solicitudes de evidencia desde el código de motivo con plantillas (prueba de entrega, fotos, instrucciones de devolución) y siempre incluya una fecha límite para que el usuario sepa exactamente qué debe hacer.