Documento histórico

Este documento se conserva solo para trazabilidad. Consulte el índice maestro para la fuente vigente.

Documento histórico — no usar como fuente de decisiones actuales

Reemplazado por la versión canónica del 2026-07-11. Conservar solo como trazabilidad histórica.

Glosario del proyecto¶

Referencia terminológica histórica. No es fuente de verdad vigente; cualquier término nuevo debe validarse contra el índice maestro y los documentos canónicos.

A¶

Actividad: Unidad de trabajo registrada en la línea de tiempo de un paquete o envío. Ej.: "recibido en almacén", "identificado por operador".
Aduana: Autoridad cubana (Aduana General de la República de Cuba) que regula la entrada de envíos al país. Norma de referencia: Resolución 175/2022.
Almacenaje: Tiempo que un paquete permanece en el casillero antes de ser despachado. Período gratuito resuelto: 15 días naturales desde la fecha de recepción. Costo por día extra resuelto: $0.50 USD. Configurable desde Django Admin (valores por defecto). Ver preguntas.md.
App: Aplicación móvil nativa del usuario final. En IslaBox existen la app Android (Kotlin/Compose) y, en Fase 2+, iOS (Swift/SwiftUI).
Arancel: Porcentaje (30% en envíos generales) que se aplica sobre el valor gravado de un envío al pasar por aduana.
Armonización: Mapeo entre capítulos de la Resolución 175/2022 y las categorías operativas del sistema. Ver aduana.md.
Auditoría: Registro inmutable de cambios relevantes para trazabilidad y resolución de disputas (audit_logs).

B¶

Backoffice: Panel interno de operación, basado en Django Admin con colas operativas personalizadas. Lo usan operadores y administradores.
Beneficio 2026: Exención arancelaria especial para envíos de alimentos, aseo, medicamentos e insumos médicos (200 USD / 20 kg exentos si vienen separados y exclusivos).
Bucket: Contenedor de archivos en MinIO. Cada tipo de archivo (KYC, fotos de paquetes, evidencias, etc.) tiene su propio bucket.
Agencia aliada: Empresa externa (no IslaBox) que realiza el transporte internacional de los paquetes desde Miami hacia Cuba y la entrega final al destinatario. IslaBox actúa como intermediario digital: recibe paquetes en su casillero propio y los entrega a la agencia. La agencia provee una API (webhook/consulta) para actualizar el estado del envío. Contrato pendiente de firma (ver preguntas.md). La agencia es quien posee la licencia de courier; IslaBox no.

C¶

Casillero: Dirección física en Miami, FL, operada directamente por IslaBox (casillero propio, no de un tercero), que el usuario utiliza como destino de envío de sus compras online. No es un casillero personal del usuario. IslaBox recibe los paquetes y los entrega a la agencia aliada para su transporte internacional.
Categoría operativa: Cada uno de los 15 tipos de producto que el sistema maneja (Ropa, Calzado, Electrónicos, etc.). Cada categoría tiene flags regulatorios derivados de la normativa cubana.
Categoría restringida: Categoría con accepted = "No" (prohibida) o accepted = "Condicional".
Check-digit (dígito verificador): Último dígito del identificador de casillero (CP-NNNNNN-D). Se calcula con algoritmo Mod-10 sobre el número secuencial.
Cola operativa: Vista del backoffice que muestra un subconjunto de elementos pendientes de acción (recepción, conciliación, KYC, devoluciones, etc.).
Compra: Transacción comercial del usuario en un marketplace (Amazon, SHEIN, Temu, etc.) que será reportada como prealerta.
Consolidación: Agrupación de varios paquetes físicos en un único envío hacia Cuba, para optimizar costos logísticos.
Cotización (Quote): Estimación formal del costo de un envío o consolidación, con vigencia definida.
Crecimiento: Módulo del sistema dedicado al programa de referidos, niveles, crédito y tarjetas promocionales. Se activa en Fase 2.
Cupón: Véase Tarjeta promocional.

D¶

Dashboard: Pantalla principal de la app, donde el usuario ve su identificador, dirección del casillero, resumen de paquetes y la sección "Requiere tu atención".
Dígito verificador: Véase Check-digit.
Destinatario (recipient): Persona en Cuba que recibe un paquete. No se registra en la app; sus datos los gestiona el usuario registrado. Teléfono: +53 (Cuba) o +1 (EE.UU.).
Django: Framework backend que define los modelos, las migraciones, el ORM y el panel de administración. Comparte capa de servicios con FastAPI.
Documento de identidad (KYC): Pasaporte, carné de identidad o licencia de conducir que el usuario presenta para verificación.

E¶

Empaque: Material y presentación física del paquete al momento de ser recibido. Puede estar en estado "Bien", "Dañado" o "Reparado".
Envío (shipment): Despacho consolidado o individual de uno o más paquetes hacia Cuba, con un destinatario definido y un número de guía maestra.
Estado: Valor discreto dentro del ciclo de vida de una entidad (prealerta, paquete, envío, pago, KYC, etc.). Lista oficial en estados.md.
Evento: Cambio de estado registrado con timestamp, autor (usuario u operador) y referencia. Se almacena en package_events para construir el timeline.
Exención: Monto o peso del valor aduanero que no paga arancel. Para envíos generales: primeros 30 USD / 3 kg.

F¶

Factura (invoice): Comprobante final con desglose de cargos (servicio de casillero, envío, consolidación, almacenaje, aduana, etc.) que se entrega al usuario al pagar.
Facturación: Proceso de generar y emitir facturas tras la confirmación de un envío o consolidación.
FastAPI: Framework backend que expone la API pública consumida por las apps móviles. Comparte capa de servicios con Django.
Fecha de recepción: Día en que el paquete físico llegó al casillero de Miami.
Franquicia: Exención total o parcial aplicable a un viajero (no aplica a envíos por casillero, que usan el régimen general de envíos).
Frontmatter: Metadatos YAML al inicio de los documentos Markdown de este proyecto.

G¶

Gestión: Servicio administrativo de IslaBox por coordinar el envío. Aparece como línea separada en la factura.
Glosario: Este documento. Términos y definiciones canónicos.
Gratuito (período de almacenaje): Días sin costo que un paquete puede permanecer en almacén. Configurable (ver preguntas.md).
Guía maestra (master guide): Número de seguimiento del envío consolidado, asignado por la agencia aliada que transporta hacia Cuba.

H¶

Hash: Cadena SHA-256 que identifica unívocamente un archivo subido a MinIO. Se almacena en file_attachments.checksum.

I¶

Identificador (de casillero): Código único del usuario con formato CP-NNNNNN-D. Es el primer criterio para asociar paquetes. Ver identificador.md.
Incidencia: Evento no previsto que requiere atención operativa (paquete dañado, dirección errónea, KYC rechazado, etc.).
Inspector: Operador autorizado para revisar KYC, consolidar paquetes o validar servicios adicionales.
Interfaz de pago: Integración con un proveedor externo para procesar cobros. Proveedor elegido: Stripe (Stripe Checkout + Webhooks). En MVP es manual (registro por el operador); en Fase 2 se automatiza vía Stripe.
Inventario: Conteo y trazabilidad de los paquetes físicos en almacén, con su ubicación.

J¶

Job: Tarea programada en background (vía Celery u otro planificador) que ejecuta lógica periódica: notificaciones push, vencimiento de almacenaje, expiración de crédito, recálculo de niveles, etc.

K¶

KYC (Know Your Customer): Proceso de verificación de identidad del usuario. Es obligatorio para despachar, consolidar para envío y pagar, pero no bloquea la prealerta.
KYC aprobado: Estado en que el usuario ya puede operar envíos. Vigencia: 10 años desde la aprobación.

L¶

LB (libra): Unidad de peso (0.4536 kg) que se usa como base del pricing de envío internacional.
Libreta de direcciones: Lista de destinatarios y remitentes guardados por el usuario.
Límite general de envío: Tope de valor aduanero permitido por envío por compañía (500 USD según Res. 175/2022).
Línea de tiempo (timeline): Secuencia visual de eventos de un paquete o envío, con fecha, estado y descripción.
Lote: Conjunto de paquetes pre-seleccionados para una consolidación, antes de confirmarla.

M¶

Marketplace: Tienda online donde el usuario compra (Amazon, SHEIN, Temu, etc.).
Master guide: Véase Guía maestra.
MinIO: Almacenamiento de objetos compatible con S3, usado para todos los archivos del sistema (KYC, fotos, evidencias).
Miscelánea: Capítulo 1 de la Res. 175/2022. Productos diversos como ropa, calzado, confecciones, bisutería. Se valora por peso (1 kg = 10 USD).
Módulo: Bloque funcional del sistema (usuarios, casillero, prealerta, consolidación, etc.). Ver modulos.md.
MVP (Minimum Viable Product): Lanzamiento mínimo viable. Ver mvp.md.
Múltiple destinatario: Capacidad de un usuario de tener varios destinatarios en Cuba registrados bajo su cuenta.

N¶

Nivel: Categoría del usuario en el programa de referidos (1, 2 o 3). Se evalúa de forma continua y puede subir o bajar automáticamente.
Notificación push: Mensaje enviado al dispositivo móvil del usuario cuando ocurre un evento relevante.

O¶

OCR: Reconocimiento óptico de caracteres. En IslaBox se usa para extraer datos de capturas de órdenes y etiquetas (Fase 2).
Operador: Usuario interno con permisos para registrar paquetes, revisar KYC, consolidar, validar servicios, etc.
Origen del usuario: Regla que define que solo se registran personas en EE.UU. con teléfono +1. Ver reglas-negocio.md.
OTP (One-Time Password): Código numérico de 6 dígitos enviado por SMS para verificar teléfono o recuperar contraseña. Vigencia: 5 minutos; 3 intentos máximo.

P¶

Paquete (physical package): Caja o sobre físico recibido en el casillero. Tiene un identificador, tracking, peso, dimensiones, estado y eventos.
Pasarela de pago: Véase Interfaz de pago (proveedor seleccionado: Stripe).
Perfil: Pantalla de la app donde el usuario ve sus datos, identificador, nivel, saldo de crédito, etc.
Período de almacenaje: Días que un paquete puede permanecer en almacén antes de empezar a generar cargos.
Pool promocional: Porcentaje de la ganancia neta por libra que se reparte entre referidos y fidelidad. Máximo 50% del margen ($0.50 / lb).
Pool de fidelidad: 30% del pool libre no consumido por los referidos, que se devuelve al propio usuario.
Pool de referidos: 50% del margen total, repartido entre niveles 1, 2 y 3 (50/30/20%).
Prealerta (purchase report): Reporte anticipado de una compra que el usuario hace antes de que el paquete llegue al almacén. Ver preguntas.md y estados.md.
Precio al cliente: Lo que paga el usuario final por libra, según la vía (barco $2.40, avión $3.35).
Proveedor de pago: Empresa externa (Stripe, PayPal, etc.) que procesa cobros.

Q¶

Quote: Véase Cotización.

R¶

Recepción: Módulo del sistema que registra cuando un paquete físico llega al casillero. Lo opera un usuario interno.
Reclamo: Petición formal de un usuario por una incidencia o disconformidad con un cargo o servicio.
Reempaque: Servicio adicional que cambia el embalaje de un paquete para mejorar su protección o reducir volumen.
Referido: Persona que se registró en IslaBox usando el código de referido de otro usuario. Activa una ventana de 180 días para el referidor.
Remitente (sender): Persona en EE.UU. que entrega físicamente el paquete al casillero de Miami. Suele ser el propio usuario registrado. Teléfono siempre +1.
Res. 175/2022: Resolución 175/2022 de la Aduana General de la República de Cuba. Norma de referencia para el cálculo de aranceles. Ver aduana-normativa-cuba.md.
Retención: Estado en que un paquete queda detenido por aduana o por una incidencia operativa.
ROI (Return on Investment): Métrica usada en la sección de crecimiento para evaluar el programa de referidos.
RUP (Rational Unified Process): Metodología de desarrollo iterativa e incremental basada en UML. Ver README de esta sección.

S¶

Saldo de crédito: Crédito disponible en la cuenta del usuario, con fecha de expiración. No es retirable en efectivo.
Servicio adicional: Servicio opcional contratado por el usuario: inspección visual, prueba funcional, reempaque, devolución. Cada uno tiene su propio ciclo de estados.
Subasta de identificación: Proceso (manual en MVP) por el cual el operador determina a qué usuario pertenece un paquete que llegó sin identificador claro.
Suscripción push: Registro del dispositivo del usuario en el servicio de notificaciones push (FCM/APNS).

T¶

Tarifa: Precio configurado para un servicio. Puede ser fija (ej.: inspección $5) o variable (ej.: envío $2.40/lb).
Tarjeta promocional (promo card): Tarjeta emitida al usuario al convertir crédito, usable como medio de pago. Tiene valor, fecha de emisión y fecha de expiración.
Tasa de cambio: Conversión USD ↔ CUP (no la maneja el sistema; los cargos están en USD).
Tienda: Véase Marketplace.
Tracking (número de seguimiento): Código que la tienda o el transportista asigna al envío. Permite consultar el estado logístico en el sistema del transportista.
Tutorial: Guía paso a paso de cómo usar IslaBox para una tienda específica (Amazon, SHEIN, Temu).

U¶

URL prefirmada (presigned URL): URL temporal que concede acceso a un objeto privado en MinIO. Caduca en 5-15 minutos según el caso de uso.
Usuario registrado (user): Persona radicada en EE.UU. que se registra en IslaBox con teléfono +1. Es el único actor que tiene cuenta en la app.

V¶

Valor aduanero: Valor que Aduana asigna al envío para cálculo arancelario. Para misceláneas: peso × 10 USD/kg.
Valor declarado: Valor que el usuario declara al reportar la compra. Puede no coincidir con el valor aduanero.
Valor exento: Porción del valor aduanero que no paga arancel. Para envíos generales: 30 USD / 3 kg.
Valor gravado: Valor aduanero menos el valor exento. Sobre este se aplica el arancel (30%).
Ventana de 180 días: Período individual por cada referido, contado desde su registro, durante el cual sus envíos generan pool para el referidor.
Verificación de identidad: Véase KYC.
VIP: Nivel alto del programa de referidos (Nivel 3: Pro/Socio). No es estado, es nivel.

W¶

Webhook: Llamada HTTP automática que un sistema externo hace a IslaBox cuando ocurre un evento. Se usa en integraciones Fase 2+.

X¶

(reservado)

Y¶

(reservado)

Z¶

(reservado)

Cómo usar este glosario¶

Antes de escribir un documento nuevo, revisa si hay un término que vayas a introducir. Si existe, defínelo aquí primero.
Si un término cambia de significado, actualiza este glosario y luego propaga el cambio a todos los documentos donde se usa.
Si dos documentos definen el mismo término de forma distinta, gana la definición de este glosario.