Pasarelas y trackings

Stripe y el tracking automático de transportistas son Fase 2; confirmar en producto/decisiones-vigentes.md antes de tomar cualquier compromiso contractual.

Integraciones¶

Integraciones del sistema, organizadas por fase de implementación.

Listado de integraciones¶

Integración	Descripción	MVP	Fase	Preparación en DB
API de tracking de transportistas	Consulta automática del estado de envío (UPS, USPS, FedEx)	Manual	2	Sí — campo `carrier_tracking_id` existe
Lectura de etiquetas (código de barras / QR)	Escaneo rápido en almacén para identificar paquetes	Manual	2	Sí — `tracking_number` indexado
OCR para capturas de órdenes	Lectura automática de datos desde fotos de confirmación de compra	No	2	Sí — `purchase_items` con campos para datos leídos
WhatsApp para notificaciones	Envío de alertas por WhatsApp además de push y email	No	3	Sí — tabla `notifications` con canal `whatsapp`
Stripe (pasarela de pago)	Cobro en línea con tarjeta por servicios, envíos y cargos adicionales. Integración vía Stripe Checkout + Webhooks	Manual	2	Sí — `payments` con `payment_provider='stripe'` y `provider_reference` (Payment Intent ID)
Sistema de la agencia aliada	Conexión con el sistema de la agencia que despacha hacia Cuba	Manual	2	Sí — `shipments` con `master_guide` y `carrier`
Formularios de devolución de marketplaces	Conexión con procesos de retorno de Amazon, SHEIN, Temu	No	3	Sí — `return_requested` y `return_status` en `physical_packages`

Columnas de la tabla¶

Columna	Significado
MVP	Si dice "Manual": en el MVP un operador hace esta tarea desde Django Admin. Si dice "No": no existe en MVP.
Fase	Fase en que se automatiza o se habilita la integración.
Preparación en DB	Si dice "Sí": la base de datos ya tiene los campos necesarios. No se necesita reestructurar.

Base de datos preparada desde el inicio

Aunque muchas integraciones son manuales en el MVP, los campos correspondientes ya existen en el modelo de datos. Esto permite que la automatización posterior no requiera cambios de esquema.

API de tracking — detalle¶

GET /api/v1/trackers/{carrier}/{tracking_number}

Campo	Descripción
carrier	ups / usps / fedex / dhl
tracking_number	Número de seguimiento
status	Estado del envío según el transportista
last_update	Última actualización
estimated_delivery	Fecha estimada
events	Array de eventos del transportista

Estados mapeados¶

Estado transportista	Estado interno Casillero
picked_up	recibido_identificado
in_transit	en_transito
delivered	entregado
exception	incidencia
returned	devuelto_a_tienda

OCR — detalle¶

POST /api/v1/ocr/extract-order

Campo	Descripción
image	Foto de la confirmación de orden
Returns	marketplace, order_number, items[], total_value, currency

Validación post-OCR¶

Los datos extraídos por OCR se pre-rellenan en el formulario de prealerta. El usuario revisa y confirma. Nunca se crea la prealerta automáticamente sin confirmación del usuario.

Glosario de integraciones¶

Término	Significado
Webhook	Llamada automática que hace el sistema externo cuando ocurre un evento
Tracking push	El transportista notifica cambios de estado sin que Casillero haga polling
OCR	Optical Character Recognition — lectura de texto desde imágenes
Pasarela de pago	Proveedor elegido: Stripe. Servicio que procesa cobros con tarjeta y otros métodos. IslaBox usa Stripe Checkout para el formulario y Webhooks firmados para confirmar el pago.
Agencia aliada	Empresa de paquetería que transporta los envíos hacia Cuba

Diagrama de integraciones¶

flowchart LR
    subgraph Sistema Casillero
        API["API Backend"]
        DB["PostgreSQL"]
    end
    subgraph Externas
        T["APIs de Tracking"]
        W["WhatsApp API"]
        P["Stripe (pagos)"]
        AG["Sistema Agencia"]
        QR["Lector QR/Barras"]
        OCR["Servicio OCR"]
    end
    API --> T
    API --> W
    API --> P
    API --> AG
    QR --> API
    OCR --> API

Criterio de priorización

Las integraciones se priorizarán según el volumen de operación manual que eliminan y el impacto directo en la experiencia del usuario.