Guía de uso de Mercavisor

¿Qué es Mercavisor?

Mercavisor es una plataforma B2B donde las importadoras cubanas reportan voluntariamente lo que planean importar en las próximas semanas. A cambio ven lo que el resto del mercado ya tiene en ruta: categorías saturadas, puertos congestionados, ETAs concentradas.

Resultado práctico: dejas de comprar 10 contenedores de arroz cuando ya hay 90 entrando el mismo mes. Decides con datos reales en lugar de rumores.

¿Cómo funciona?

1. Reportas antes de comprar: categoría, volumen, ruta, ETA estimada.
2. El admin de Mercavisor revisa y aprueba tu reporte (usualmente en menos de 24 horas).
3. Una vez aprobado, aparece en el manifiesto compartido que ven todas las importadoras participantes.
4. Tú ves los reportes de los demás: cuotas, saturación por categoría, ETAs concentradas por puerto.
5. Decides con esos datos: ajustas volumen, cambias categoría, retrasas un mes.

Primer login

Después de que el admin apruebe tu solicitud, recibirás un email con tu usuario y contraseña inicial. Pasos al entrar:

1. Inicia sesión desde mercavisor.com con el botón Iniciar sesión.
2. Cambia tu contraseña: Mi cuenta → Cambiar contraseña.
3. Verifica que tu importadora está correctamente vinculada (debe aparecer en la card del sidebar).
4. Sube tu foto de perfil y completa tus datos si faltan.
5. Reporta tu primer envío (ver siguiente sección).

Reportar tu primer envío

Desde cualquier vista del panel, click en el botón + Reportar envío arriba a la derecha. Se abre un modal:

• Categoría: arroz, aceite, cemento, paneles solares, etc. Si tu categoría no existe en la lista, escríbela y se creará.
• SKU: código interno de tu producto. Si ya lo reportaste antes, el sistema lo autocompletará.
• Descripción: nombre comercial del producto.
• Volumen: cantidad de contenedores (20' o 40') y tipo.
• Ruta: puerto de origen → puerto de destino.
• ETA estimada: cuándo esperas que llegue.
• Estado: en tránsito / reportado / en aduana / llegado.

Hay también campos privados (proveedor, precio FOB, naviera, agente, notas) que solo tú y los miembros de tu importadora ven. No se comparten en el manifiesto público.

Editar o eliminar un envío

Editar: en Mis envíos, click en "Editar" de cualquier fila. Modificas lo necesario y guardas.

Eliminar individual: click en el ícono de papelera (🗑) al final de cada fila. Va a la papelera, no se borra definitivamente. El admin podría restaurarlo si fue por error.

Eliminar varios: marca los checkboxes de las filas que quieres eliminar, click en "Eliminar seleccionados (N)" en la barra negra que aparece arriba.

Permisos:

• El autor del envío siempre puede editarlo o eliminarlo.
• El admin de la importadora puede editar y eliminar cualquier envío de su org.
• Los reporteros solo sus propios envíos.
• Los solo lectura no pueden editar ni eliminar.

Importar CSV en lote

Si tienes muchos envíos en una hoja de cálculo, puedes importarlos de una vez en Importar CSV del sidebar.

Formato requerido (columnas, en este orden):

1. Importadora (debe coincidir con tu importadora)
2. Categoría
3. Descripción
4. SKU
5. Volumen (número de contenedores)
6. Tipo contenedor (20 / 40)
7. Puerto origen
8. Puerto destino
9. ETA (formato YYYY-MM-DD)
10. Estado (transito / reportado / aduana / llegado)

Descarga la plantilla CSV de ejemplo desde la misma página de importación para empezar.

Flujo de aprobación

Por seguridad y para mantener calidad de los datos, los envíos no se publican automáticamente. El flujo:

1. Tú reportas → envío en estado Pendiente.
2. El admin recibe email de notificación.
3. Admin revisa la coherencia: ¿volumen razonable? ¿ruta válida? ¿categoría correcta?
4. Si todo OK → admin Aprueba → envío pasa a Publicado.
5. Si hay inconsistencia → admin Rechaza con un motivo → envío queda en estado Borrador y tú recibes email para corregirlo.

Tiempo típico de aprobación: menos de 24 horas en días laborables.

Manifiesto del mercado

Es la vista principal del panel. Muestra todos los envíos publicados de todas las importadoras participantes, en orden cronológico por ETA.

Para cada fila ves:

• Importadora: quién reporta (sin datos privados).
• Producto: categoría y descripción.
• Ruta: puerto origen → puerto destino con banderas.
• Volumen: contenedores.
• ETA: cuándo se espera.
• Estado: en tránsito / reportado / aduana / llegado.

Puedes filtrar por categoría, puerto, rango de fechas, importadora desde el panel "Filtros".

Si detectas un envío con datos sospechosos o inconsistentes, click en "Reportar" al final de la fila. El admin lo revisa.

Análisis de saturación

Vista Análisis del sidebar. Te muestra:

• Tu cuota vs el mercado: porcentaje de los reportes totales que vienen de tu importadora, por categoría.
• Saturación por categoría: una categoría está "saturada" cuando el volumen reportado supera un umbral histórico configurado.
• Heatmap de ETAs: qué semanas tienen más llegadas concentradas (útil para anticipar congestión en puerto).
• Oportunidades: categorías con saturación menor al 30% — espacio para entrar.

Tu catálogo

El catálogo se construye automáticamente a partir de los envíos que reportas. Cada SKU único que reportes se vuelve un producto en tu catálogo, con histórico de volúmenes y proveedores.

Útil para:

• Ver qué productos has importado este año.
• Recordar el último proveedor que usaste para un SKU.
• Buscar rápido cuando vayas a reportar uno parecido (autocomplete por SKU).

El catálogo solo lo ves tú y los miembros de tu importadora. Es información privada.

Alertas

Vista Alertas del sidebar. Te avisa de:

• Saturación detectada: una categoría donde tienes reportes activos se cruzó al umbral de saturación.
• Envíos en aduana: tus envíos con ETA pasada y todavía sin marcar como llegado.
• Inconsistencias reportadas: otro usuario reportó tu envío como sospechoso y el admin lo está revisando.

El número junto a "Alertas" en el sidebar muestra cuántas pendientes tienes.

Invitar miembros a tu equipo

Vista Equipo del sidebar (solo visible si eres admin de tu importadora).

En la columna derecha, escribe el email del nuevo miembro y elige su rol. Al enviar, se crea una cuenta provisional y se le manda un email con un link de activación.

El invitado tiene 7 días para aceptar la invitación. Al hacer click en el link, completa nombre, apellidos, carné y contraseña, y entra directo al panel.

Roles y permisos

El "Solo lectura" sirve para roles administrativos o contadores que necesitan ver datos pero no modificarlos.

Gestionar invitaciones

En la página de Equipo, si hay invitaciones sin aceptar, aparecen en la sección "Invitaciones pendientes".

Por cada invitación pendiente puedes:

• Reenviar: regenera el token (nuevo plazo de 7 días) y reenvía el email. Útil si la invitación expiró o el invitado no encuentra el correo.
• Cancelar: elimina la cuenta provisional. Úsalo si te equivocaste de email o ya no quieres invitar a esa persona.

Transferir el rol de admin

Si quieres dejar de ser admin (por ejemplo, porque te vas de la empresa), debes transferir primero el rol a otro miembro.

1. En Equipo, encuentra al miembro que será el nuevo admin.
2. Click en el ícono ⋮ a la derecha de su fila → "Cambiar a Admin de importadora".
3. Ahora hay dos admins. Ya puedes degradarte tú mismo a Reportero o Solo lectura.

Datos públicos vs privados

El modelo de Mercavisor se sostiene en una regla: compartimos solo lo agregado, no lo identificador comercial.

Públicos (visibles a todas las importadoras en el manifiesto):

• Nombre de la importadora
• Categoría del producto
• Descripción genérica (ej: "Arroz vietnamita grano largo")
• SKU interno (si lo registras)
• Volumen (contenedores)
• Puerto origen / destino
• ETA estimada
• Estado del envío

Privados (solo tú y tu equipo):

• Proveedor / fabricante
• Precio FOB
• Naviera
• Agente aduanal
• Notas internas

Nadie de otra importadora puede ver los campos privados, ni siquiera el admin de Mercavisor en pantalla (existen en la base de datos, pero la política es que no se consultan salvo investigación legal).

Verificación de identidad

Antes de aprobarte como miembro de una importadora, el admin de Mercavisor verifica:

• Que el carné de identidad que enviaste es legítimo.
• Que efectivamente trabajas en la importadora que dices.
• Que la importadora está registrada legalmente en Cuba.

Una vez verificada tu cuenta, aparece un check verde en tu perfil. Los datos de identidad quedan bloqueados (no puedes cambiarlos sin contactar al admin) para evitar suplantación posterior.

Cambiar contraseña

En Mi cuenta, sección "Cambiar contraseña":

1. Escribe tu contraseña actual.
2. Escribe la nueva contraseña (mínimo 8 caracteres).
3. Repítela para confirmar.
4. Click Guardar cambios.

Si dejas los campos de contraseña vacíos, el resto de tus datos se guarda igual sin cambiarla.

Recuperar acceso si olvidaste tu contraseña

1. En mercavisor.com, click en Iniciar sesión.
2. En el modal de login, click en "¿Olvidaste tu contraseña?".
3. Escribe el email con que te registraste.
4. Recibirás un email con un link para crear contraseña nueva.

Si el email no llega: revisa spam, espera 5 minutos, o contacta a soporte (ver más abajo).

Eliminar mi cuenta

En Mi cuenta, hasta el final, está la "Zona peligrosa" con el botón "Solicitar eliminación de mi cuenta".

Lo que pasa al hacerlo:

1. Tu solicitud entra como pendiente. El admin recibe email.
2. El admin revisa: ¿no eres el único admin de tu importadora? ¿no hay envíos críticos en revisión?
3. Al aprobar la eliminación, tu cuenta se borra y tus envíos publicados se anonimizan (los datos agregados quedan en el mercado, pero sin tu nombre).
4. Recibes email de confirmación.

API REST

Mercavisor incluye una API REST para integrar tu sistema interno —ERP, hoja de cálculo, dashboard propio— con la plataforma sin pasar por el panel web. Está disponible para el plan Premium (capability Acceso a la API).

Autenticación

Generá tu API key desde el panel, en Cuenta → API. La key se muestra una sola vez; guardala en un lugar seguro. Enviala en el header de cada request:

Authorization: Bearer TU_API_KEY

La key se guarda hasheada (nunca en texto plano). Podés regenerarla o revocarla cuando quieras desde el mismo panel; al regenerarla, la anterior deja de funcionar.

Endpoints disponibles

• GET /me — datos de tu cuenta y plan.
• GET /manifiesto — envíos activos del mercado (datos compartidos). Paginado con ?page=1&per_page=50.
• GET /envios — tus envíos, con los datos completos de tu importadora. Paginado.
• POST /envios — crear un envío. Campos obligatorios: producto, contenedores. Opcionales: tipo, eta, categoria, descripcion, sku, proveedor, naviera.
• GET /saturacion — volumen de contenedores por categoría.

La base de la API es https://mercavisor.com/wp-json/mercavisor/v1. Los endpoints que devuelven listas incluyen los campos page, per_page, total y total_pages, además de los headers X-WP-Total y X-WP-TotalPages.

Ejemplos

Leer el manifiesto:

curl -H "Authorization: Bearer TU_API_KEY" \
  https://mercavisor.com/wp-json/mercavisor/v1/manifiesto?page=1&per_page=50

Crear un envío:

curl -X POST https://mercavisor.com/wp-json/mercavisor/v1/envios \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"producto":"Aceite girasol","contenedores":3,"tipo":"40HC","categoria":"Alimentos","eta":"2026-07-15"}'

Webhooks salientes

Configurá una URL https en Cuenta → API y Mercavisor te enviará un POST automático cada vez que se publica un envío nuevo en el mercado. El evento es envio.published y el cuerpo contiene los datos públicos del envío.

Cada entrega va firmada con HMAC-SHA256 en el header X-Mercavisor-Signature, usando el secret que ves en tu panel. Verificá esa firma en tu servidor para confirmar que el webhook viene realmente de Mercavisor:

// Pseudocódigo de verificación
firma_esperada = hmac_sha256(cuerpo_crudo, TU_SECRET)
if (firma_esperada !== header['X-Mercavisor-Signature']) rechazar()

Límites

• Rate limit: 120 requests por minuto por cuenta. Al superarlo, la API responde 429 indicando cuántos segundos esperar.
• Paginación: máximo 100 resultados por página.
• Privacidad: el manifiesto y los webhooks solo exponen datos públicos. Los datos privados (proveedor, FOB, naviera, notas) solo aparecen en /envios, y únicamente los de tu propia importadora.

¿Por qué tengo que reportar si yo solo quiero ver el mercado?

Porque sin que tú aportes datos, no hay datos para compartir. El sistema funciona como una cooperativa de información: todos contribuyen, todos ven el agregado.

Si solo unos pocos reportan honestamente y el resto solo observa, el mercado se distorsiona y nadie confía en los números. Por eso el acceso es por invitación, y se valida que cada miembro reporta consistentemente.

¿Qué pasa con mis datos si alguien dentro de Mercavisor los filtra a la competencia?

Los datos privados (proveedor, precio FOB) están almacenados en la base de datos pero no son visibles en pantalla para nadie fuera de tu importadora, ni siquiera para el admin de Mercavisor.

Estamos sujetos a las leyes cubanas sobre datos comerciales. Un eventual filtrado constituiría un delito tipificado por la Ley 118 sobre inversión extranjera y normativa de protección de información comercial.

Lo que sí pasa: si tú o tu importadora violan la lógica de reportar honestamente (reportes falsos, no reportar lo que sí compras), el admin puede revocar tu acceso.

¿Cómo consigo acceso si todavía no tengo cuenta?

El acceso es por invitación o por solicitud aprobada:

• Si conoces a alguien que ya usa Mercavisor y es admin de su importadora, pídele que te invite directo.
• Si no conoces a nadie, ve a la página principal de mercavisor.com → "Solicitar acceso". Completas tu nombre, tu importadora, tu rol, y el admin revisa la solicitud manualmente.

Aprobamos solicitudes en menos de 48 horas si la importadora está correctamente identificada.

Contactar soporte

Si después de leer esta documentación sigues con dudas o algo no funciona:

• Email: [email protected]
• Respondemos en menos de 24 horas en días laborables.
• Si reportas un bug, incluye captura de pantalla y descripción del paso a paso.

Para temas comerciales, asociaciones o licencias contacta a [email protected].