# Guía de Integraciones Móviles - iNeed Marketplace

## Índice

1. [Firebase Cloud Messaging (Push Notifications)](#firebase-cloud-messaging)
2. [Mapas y Geolocalización](#mapas-y-geolocalización)
3. [Deep Linking](#deep-linking)
4. [Analytics Móvil](#analytics-móvil)
5. [Pagos Móviles](#pagos-móviles)

---

## Firebase Cloud Messaging

### Configuración del Proyecto Firebase

1. **Crear proyecto en Firebase Console**
   - Ve a [Firebase Console](https://console.firebase.google.com/)
   - Crea un nuevo proyecto o selecciona uno existente
   - Habilita Cloud Messaging

2. **Configuración para iOS**
   ```
   1. Descarga GoogleService-Info.plist
   2. Agrégalo a tu proyecto Xcode
   3. Configura APNs (Apple Push Notification service)
   4. Sube el certificado APNs a Firebase
   ```

3. **Configuración para Android**
   ```
   1. Descarga google-services.json
   2. Agrégalo a app/google-services.json
   3. Agrega el plugin de Google Services a build.gradle
   ```

### Endpoints de Push Notifications

#### Registrar Dispositivo
```bash
POST /api/mobile/notifications/register
Content-Type: application/json
Authorization: Bearer {token}

{
  "fcmToken": "device_fcm_token",
  "platform": "ios" | "android",
  "deviceId": "unique_device_id",
  "appVersion": "1.0.0"
}
```

#### Suscribirse a Temas
```bash
POST /api/mobile/notifications/topics
Content-Type: application/json
Authorization: Bearer {token}

{
  "action": "subscribe",
  "topics": ["promotions", "news", "loyalty"]
}
```

#### Temas Disponibles
| Tema | Descripción |
|------|-------------|
| `promotions` | Ofertas y descuentos |
| `news` | Novedades de productos y tiendas |
| `loyalty` | Programa de lealtad y puntos |
| `flash_sales` | Ofertas relámpago |

### Envío de Notificaciones (Server-side)

```bash
POST /api/mobile/push/send
Content-Type: application/json
Authorization: Bearer {admin_token}

{
  "targetType": "user" | "topic" | "all",
  "targetId": "user_id" | "topic_name",
  "notification": {
    "title": "Nueva oferta",
    "body": "50% de descuento en pizzas",
    "imageUrl": "https://www.shutterstock.com/image-photo/pizza-offer-concept-50-off-600w-1938067936.jpg"
  },
  "data": {
    "type": "promotion",
    "id": "promo123"
  }
}
```

---

## Mapas y Geolocalización

### APIs Disponibles

#### Calcular Ruta
```bash
GET /api/mobile/maps/route
?originLat={lat}&originLng={lng}&destLat={lat}&destLng={lng}&profile={driving|cycling|walking}
```

**Respuesta:**
```json
{
  "success": true,
  "route": {
    "distance": 5230,
    "distanceKm": "5.23",
    "duration": 720,
    "durationMinutes": 12,
    "eta": "2025-02-23T15:30:00Z",
    "etaFormatted": "3:30 PM",
    "polyline": "encoded_polyline",
    "steps": [...]
  }
}
```

#### Ruta Múltiple (Waypoints)
```bash
POST /api/mobile/maps/route
Content-Type: application/json

{
  "waypoints": [
    {"lat": 4.7110, "lng": -74.0721},
    {"lat": 4.7150, "lng": -74.0650},
    {"lat": 4.7200, "lng": -74.0600}
  ],
  "profile": "driving"
}
```

#### Geocodificación
```bash
# Dirección a coordenadas
GET /api/mobile/maps/geocode?address=Calle%2085%20Bogotá&countryCode=CO

# Coordenadas a dirección (reverse)
GET /api/mobile/maps/geocode?lat=4.7110&lng=-74.0721
```

#### Calcular ETA de Pedido
```bash
GET /api/mobile/maps/eta?orderId={order_id}&type=delivery
```

**Respuesta:**
```json
{
  "success": true,
  "eta": {
    "timestamp": "2025-02-23T16:00:00Z",
    "formatted": "4:00 PM",
    "minutesRemaining": 15,
    "distance": {
      "meters": 2500,
      "km": "2.50"
    }
  },
  "rider": {
    "id": "rider123",
    "name": "Juan Pérez"
  }
}
```

#### Matriz de Distancias
```bash
POST /api/mobile/maps/distance
Content-Type: application/json

{
  "type": "matrix",
  "origins": [{"lat": 4.71, "lng": -74.07}],
  "destinations": [
    {"lat": 4.72, "lng": -74.06},
    {"lat": 4.73, "lng": -74.05}
  ],
  "profile": "driving"
}
```

#### Optimización de Ruta (TSP)
```bash
POST /api/mobile/maps/distance
Content-Type: application/json

{
  "type": "optimize",
  "waypoints": [
    {"lat": 4.71, "lng": -74.07},
    {"lat": 4.72, "lng": -74.06},
    {"lat": 4.73, "lng": -74.05},
    {"lat": 4.74, "lng": -74.04}
  ],
  "profile": "cycling"
}
```

### Integración con Google Maps SDK

```javascript
// React Native con react-native-maps
import MapView, { Polyline, Marker } from 'react-native-maps';
import polyline from '@mapbox/polyline';

const [route, setRoute] = useState(null);

const fetchRoute = async (origin, destination) => {
  const res = await fetch(
    `/api/mobile/maps/route?originLat=${origin.lat}&originLng=${origin.lng}&destLat=${destination.lat}&destLng=${destination.lng}`
  );
  const data = await res.json();
  
  // Decode polyline
  const coordinates = polyline.decode(data.route.polyline).map(([lat, lng]) => ({
    latitude: lat,
    longitude: lng
  }));
  
  setRoute(coordinates);
};

// En el render
<MapView>
  {route && <Polyline coordinates={route} strokeWidth={4} strokeColor="#2196F3" />}
</MapView>
```

---

## Deep Linking

### Configuración iOS (Universal Links)

1. **Asociar dominio en Xcode**
   ```
   Signing & Capabilities > Associated Domains
   applinks:ineed.market
   webcredentials:ineed.market
   ```

2. **Archivo apple-app-site-association**
   Ya configurado en: `/.well-known/apple-app-site-association`

3. **Manejar en AppDelegate.swift**
   ```swift
   func application(_ application: UIApplication,
                    continue userActivity: NSUserActivity,
                    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
       guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
             let url = userActivity.webpageURL else {
           return false
       }
       
       // Resolver deep link
       resolveDeepLink(url)
       return true
   }
   ```

### Configuración Android (App Links)

1. **Agregar intent-filter en AndroidManifest.xml**
   ```xml
   <activity android:name=".MainActivity">
       <intent-filter android:autoVerify="true">
           <action android:name="android.intent.action.VIEW" />
           <category android:name="android.intent.category.DEFAULT" />
           <category android:name="android.intent.category.BROWSABLE" />
           <data android:scheme="https"
                 android:host="ineed.market"
                 android:pathPrefix="/producto" />
           <data android:pathPrefix="/tienda" />
           <data android:pathPrefix="/pedido" />
           <data android:pathPrefix="/tracking" />
       </intent-filter>
   </activity>
   ```

2. **Archivo assetlinks.json**
   Ya configurado en: `/.well-known/assetlinks.json`
   
   **Importante:** Reemplazar `sha256_cert_fingerprints` con tu huella digital:
   ```bash
   keytool -list -v -keystore release.keystore -alias myalias
   ```

### Generar Deep Links

```bash
POST /api/mobile/deeplink
Content-Type: application/json

{
  "type": "product",
  "params": { "id": "abc123" },
  "track": true
}
```

**Respuesta:**
```json
{
  "success": true,
  "links": {
    "app": "ineed:///producto/abc123",
    "universal": "https://ineed.market/producto/abc123",
    "web": "https://ineed.market/producto/abc123",
    "short": "https://ineed.market/dl/abc123xyz"
  },
  "qrCodeUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/8/8d/QR_Code_Damaged.jpg/250px-QR_Code_Damaged.jpg"
}
```

### Tipos de Deep Links

| Tipo | Path | Ejemplo |
|------|------|--------|
| `product` | `/producto/:id` | `/producto/abc123` |
| `store` | `/tienda/:id` | `/tienda/pizza-hut` |
| `order` | `/pedido/:id` | `/pedido/ord456` |
| `tracking` | `/tracking/:orderId` | `/tracking/ord456` |
| `category` | `/categoria/:slug` | `/categoria/pizzas` |
| `coupon` | `/cupon/:code` | `/cupon/DESCUENTO20` |
| `referral` | `/referido/:code` | `/referido/JUAN2025` |
| `search` | `/buscar/:query` | `/buscar/hamburguesa` |

### Resolver Deep Links

```bash
GET /api/mobile/deeplink/resolve?url=https://ineed.market/producto/abc123
```

**Respuesta:**
```json
{
  "success": true,
  "resolved": true,
  "navigation": {
    "screen": "ProductDetail",
    "params": { "productId": "abc123" }
  },
  "webFallback": "https://ineed.market/producto/abc123"
}
```

---

## Analytics Móvil

### Eventos Disponibles

#### Sesión
- `app_open`, `app_close`, `session_start`, `session_end`

#### Navegación
- `page_view`, `screen_view`

#### Autenticación
- `login`, `logout`, `signup`, `password_reset`

#### E-commerce
- `view_product`, `view_store`, `view_category`, `search`
- `add_to_cart`, `remove_from_cart`, `update_cart`, `view_cart`
- `begin_checkout`, `add_payment_info`, `purchase`, `refund`

#### Engagement
- `add_to_wishlist`, `share`, `rate_product`, `rate_store`, `rate_rider`
- `apply_coupon`, `redeem_loyalty`

#### Pedidos
- `track_order`, `cancel_order`, `request_support`

#### Notificaciones
- `notification_received`, `notification_opened`, `notification_dismissed`

### Registrar Eventos

#### Evento Simple
```bash
POST /api/mobile/analytics/events
Content-Type: application/json

{
  "single": {
    "eventName": "view_product",
    "sessionId": "sess123",
    "properties": {
      "product_id": "abc123",
      "product_name": "Pizza Margherita",
      "price": 45000,
      "category": "Pizzas"
    }
  },
  "platform": "ios",
  "appVersion": "1.2.0",
  "deviceInfo": {
    "model": "iPhone 14",
    "os": "iOS",
    "osVersion": "17.0"
  }
}
```

#### Vista de Página
```bash
POST /api/mobile/analytics/events
Content-Type: application/json

{
  "pageView": {
    "pageName": "ProductDetail",
    "referrer": "HomePage",
    "duration": 45
  },
  "platform": "android"
}
```

#### Conversión
```bash
POST /api/mobile/analytics/events
Content-Type: application/json

{
  "conversion": {
    "type": "purchase",
    "value": 125000,
    "currency": "COP",
    "items": [
      { "id": "prod1", "name": "Pizza", "price": 45000, "quantity": 2 },
      { "id": "prod2", "name": "Bebida", "price": 8000, "quantity": 2 }
    ]
  }
}
```

#### Eventos en Batch
```bash
POST /api/mobile/analytics/events
Content-Type: application/json

{
  "events": [
    { "eventName": "app_open", "timestamp": "2025-02-23T10:00:00Z" },
    { "eventName": "view_product", "properties": { "product_id": "123" } },
    { "eventName": "add_to_cart", "properties": { "product_id": "123", "quantity": 1 } }
  ],
  "platform": "ios",
  "appVersion": "1.2.0"
}
```

### Gestión de Sesiones

#### Iniciar Sesión
```bash
POST /api/mobile/analytics/session
Content-Type: application/json

{
  "action": "start",
  "platform": "ios",
  "deviceInfo": {
    "model": "iPhone 14",
    "os": "iOS",
    "osVersion": "17.0"
  }
}
```

**Respuesta:**
```json
{
  "success": true,
  "action": "session_started",
  "sessionId": "1708700000-abc123xyz",
  "timestamp": "2025-02-23T15:00:00Z"
}
```

#### Finalizar Sesión
```bash
POST /api/mobile/analytics/session
Content-Type: application/json

{
  "action": "end",
  "sessionId": "1708700000-abc123xyz",
  "duration": 1800
}
```

### Resumen de Analytics
```bash
GET /api/mobile/analytics/session?days=30
```

---

## Pagos Móviles

### Métodos de Pago por País

```bash
GET /api/mobile/payments/methods?countryCode=CO
```

| País | Métodos |
|------|--------|
| CO | PSE, Nequi, Daviplata, Efecty, Tarjeta |
| CL | WebPay, Khipu, Tarjeta |
| MX | OXXO, SPEI, Tarjeta |

### Iniciar Pago
```bash
POST /api/mobile/payments/initiate
Content-Type: application/json

{
  "orderId": "order123",
  "method": "pse",
  "bankCode": "1007"
}
```

### Verificar Pago
```bash
POST /api/mobile/payments/verify
Content-Type: application/json

{
  "transactionId": "tx123",
  "method": "pse"
}
```

---

## Headers Requeridos

Todas las solicitudes autenticadas deben incluir:

```
Authorization: Bearer {jwt_token}
Content-Type: application/json
X-Platform: ios | android | web
X-App-Version: 1.0.0
X-Device-Id: unique_device_identifier
```

---

## Soporte

- **Email:** soporte@ineed.market
- **WhatsApp:** +57 300 123 4567
- **Documentación API:** https://ineed.market/api-docs