Integraciones Móviles

Guía completa para integrar tu aplicación móvil con iNeed Marketplace

Firebase Cloud Messaging

Requisitos: Cuenta Firebase, APNs Certificate (iOS), google-services.json (Android)

1. 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"
}

2. Suscribirse a Temas

bash

POST /api/mobile/notifications/topics

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

3. Enviar Notificación (Admin)

bash

POST /api/mobile/push/send

{
  "targetType": "user" | "topic" | "all",
  "targetId": "user_id" | "topic_name",
  "notification": {
    "title": "Nueva oferta",
    "body": "50% de descuento en pizzas",
    "imageUrl": "https://d1csarkz8obe9u.cloudfront.net/posterpreviews/pizza-50%25-discount-promo-design-template-e75b2c55669ffdffd2c88304bda425a7_0449e7b4-37a8-4cdc-8a42-93be5563aa72_screen.png?ts=1767661531"
  },
  "data": {
    "type": "promotion",
    "id": "promo123"
  }
}

Mapas y Geolocalización

Calcular Ruta

bash

GET /api/mobile/maps/route?originLat=4.7110&originLng=-74.0721&destLat=4.7200&destLng=-74.0600&profile=driving

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

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

ETA de Pedido

bash

GET /api/mobile/maps/eta?orderId=order123&type=delivery

// Respuesta
{
  "eta": {
    "formatted": "4:00 PM",
    "minutesRemaining": 15,
    "distance": { "km": "2.50" }
  },
  "rider": { "name": "Juan Pérez" }
}

Optimización de Ruta

bash

POST /api/mobile/maps/distance

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

Deep Linking

🍎 iOS Universal Links

/.well-known/apple-app-site-association

🤖 Android App Links

/.well-known/assetlinks.json

Generar Deep Link

bash

POST /api/mobile/deeplink

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

// Respuesta
{
  "links": {
    "app": "ineed:///producto/abc123",
    "universal": "https://ineed.market/producto/abc123",
    "qrCodeUrl": "https://upload.wikimedia.org/wikipedia/commons/d/d0/QR_code_for_mobile_English_Wikipedia.svg"
  }
}

Tipos Disponibles

Tipo	Path	Ejemplo
`product`	`/producto/:id`	`/producto/abc123`
`store`	`/tienda/:id`	`/tienda/pizza-hut`
`order`	`/pedido/:id`	`/pedido/ord456`
`tracking`	`/tracking/:orderId`	`/tracking/ord456`
`coupon`	`/cupon/:code`	`/cupon/DESCUENTO20`
`referral`	`/referido/:code`	`/referido/JUAN2025`

Resolver Deep Link

bash

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

// Respuesta
{
  "resolved": true,
  "navigation": {
    "screen": "ProductDetail",
    "params": { "productId": "abc123" }
  }
}

Analytics Móvil

Evento Simple

bash

POST /api/mobile/analytics/events

{
  "single": {
    "eventName": "view_product",
    "sessionId": "sess123",
    "properties": {
      "product_id": "abc123",
      "product_name": "Pizza Margherita",
      "price": 45000
    }
  },
  "platform": "ios",
  "appVersion": "1.2.0"
}

Conversión E-commerce

bash

POST /api/mobile/analytics/events

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

Eventos en Batch

bash

POST /api/mobile/analytics/events

{
  "events": [
    { "eventName": "app_open" },
    { "eventName": "view_product", "properties": { "product_id": "123" } },
    { "eventName": "add_to_cart", "properties": { "product_id": "123" } }
  ],
  "platform": "android"
}

Gestión de Sesiones

bash

// Iniciar sesión
POST /api/mobile/analytics/session
{ "action": "start", "platform": "ios" }

// Respuesta: { "sessionId": "1708700000-abc123xyz" }

// Finalizar sesión
POST /api/mobile/analytics/session
{ "action": "end", "sessionId": "...", "duration": 1800 }

Pagos Móviles

Métodos por País

🇨🇴

Colombia

PSE, Nequi, Daviplata, Efecty, Tarjeta

🇨🇱

Chile

WebPay, Khipu, Tarjeta

🇲🇽

México

OXXO, SPEI, Tarjeta

bash

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

Iniciar Pago

bash

POST /api/mobile/payments/initiate

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

Webhooks

Configura webhooks para recibir notificaciones en tiempo real sobre eventos de tu aplicación.

Eventos Disponibles

order.created- Nuevo pedido creado

order.paid- Pedido pagado

order.delivered- Pedido entregado

order.cancelled- Pedido cancelado

payment.completed- Pago completado

payment.failed- Pago fallido

user.registered- Usuario registrado

review.created- Nueva reseña

Ejemplo de Payload

json

{
  "event": "order.delivered",
  "timestamp": "2025-02-23T16:00:00Z",
  "data": {
    "orderId": "order123",
    "customerId": "user456",
    "total": 125000,
    "status": "entregado"
  },
  "signature": "sha256=..."
}

Headers Requeridos

bash

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

Ver Swagger API Descargar Guía Completa Volver al Centro de Ayuda