API de Wivo Analytics

La API de Wivo te permite acceder programáticamente a datos de ventas, ítems de órdenes, costos asociados (comisiones, envíos, promociones, publicidad), márgenes y métricas de rentabilidad disponibles en los reportes de la plataforma.

Casos de uso principales

Integrar datos de Wivo en data warehouses, ERPs, sistemas contables o herramientas internas
Automatizar reportes y dashboards personalizados sin exportaciones manuales de archivos

Datos disponibles

La API entrega información a nivel de ítem de orden, que incluye:

Detalle de la orden (ID, fecha de compra, SKUs, tipo de envío, estado de orden y pago)
Costos de la orden (comisiones, envío, logística)
Costos adicionales (almacenamiento fulfillment, publicidad)
Métricas derivadas (rentabilidad, porcentaje de rentabilidad)

Proceso de habilitación

Accede a tu cuenta de Wivo con credenciales de administrador
Ve a “Integración API” en el menú superior derecho
Haz clic en “Solicitar habilitación de API”
Agenda una reunión con un representante de Wivo para la activación
Recibe tu API Key personal y confidencial

Autenticación

Incluye tu API Key en el header HTTP de cada petición:

Ocp-Apim-Subscription-Key: TU_API_KEY

Las claves inválidas o ausentes retornan HTTP 401 Unauthorized.

Límites de uso (Rate limits)

5 peticiones por minuto por cuenta
5.000 peticiones por día (recomendado)
Superar los límites retorna HTTP 429 Too Many Requests

Como buenas prácticas, implementa reintentos con backoff exponencial y agrupa la lógica para aprovechar al máximo cada petición.

5. Los datos que entrega la API

5.1. Endpoints principales

GET /data — Devuelve órdenes e ítems de costos con todo su detalle.

5.2. Parámetros de `GET /data`

date (purchase_date o updated_at): Debes escoger uno de estos parámetros (obligatorio)
from: obligatorio, ISO 8601, ej: 2025-01-31
to: opcional, ISO 8601, ej: 2025-02-01
page: opcional

Ejemplos:

Con purchase_date:

curl "https://api.wivoanalytics.com/data?date=purchase_date&from=2025-01-01&to=2025-01-31&page=1" \
  -H "Ocp-Apim-Subscription-Key: TU_API_KEY_AQUI"

Con updated_at:

curl "https://api.wivoanalytics.com/data?date=updated_at&from=2025-01-01T20:55:00" \
  -H "Ocp-Apim-Subscription-Key: TU_API_KEY_AQUI"

5.3. Estructura de respuesta de `GET /data`

Ejemplo simplificado:

{
  "data": [
    {
      "Canal": "Marketplace A",
      "Cuenta": "Cuenta Demo 1",
      "Orden": "1000000000000001",
      "Nro. suborden": "1000000000000001",
      "SKU Producto": "SKU-DEMO-001",
      "Producto": "Producto Demostración 1 - Talla: L",
      "Variante": "Talla: L",
      "Fecha de actualización": "2024-01-11T06:26:29.000",
      "Estado de Orden": "Regular",
      "Estado de Pago": "Pagado",
      "Estado de Despacho": "Entregado",
      "Tipo de Despacho": "No Fulfillment",
      "Fecha de compra": "2024-01-09T23:56:56.000",
      "Ventas": "7500",
      "Unidades": "1",
      "Costo de Marketplace": "1500.00",
      "Rentabilidad Marketplace": "6000.00",
      "% Rentabilidad Marketplace": "80.00",
      "Costo Envío": "1000",
      "Costo de Comisiones": "500"
    },
    {
      "Canal": "Marketplace A",
      "Cuenta": "Cuenta Demo 1",
      "Orden": "1000000000000002",
      "Nro. suborden": "1000000000000003",
      "SKU Producto": "SKU-DEMO-002",
      "Producto": "Producto Demostración 2 - Talla: L Tamaño: 10.2",
      "Variante": "Color: Azul, Tamaño: 10.2",
      "Fecha de actualización": "2024-01-11T06:29:13.000",
      "Estado de Orden": "Regular",
      "Estado de Pago": "Pagado",
      "Estado de Despacho": "Entregado",
      "Tipo de Despacho": "Fulfillment",
      "Fecha de compra": "2024-01-09T23:56:43.000",
      "Ventas": "12000",
      "Unidades": "1",
      "Costo de Marketplace": "4000.00",
      "Rentabilidad Marketplace": "8000.00",
      "% Rentabilidad Marketplace": "66.67",
      "Costo Envío": "2000",
      "Costo de Comisiones": "2000"
    }
    // ... aquí podrías seguir agregando más items con los mismos campos
  ],
  "meta": {
    "page": 1,
    "pageSize": 100,
    "count": 100,
    "from": "2024-01-09T00:00:00",
    "to": "2024-01-09T23:59:59",
    "date": "purchase_date",
    "totalRows": 3282,
    "totalPages": 33,
    "correlation_id": "00000000-0000-4000-8000-000000000001"
  }
}

6. Cómo usar la API - Flujo histórico vs flujo regular

Normalmente tendrás dos flujos de uso de datos: (1) flujo histórico para la carga inicial de datos y (2) flujo regular para mantener los datos sincronizados.

6.1. Flujo histórico (backfill inicial)

Objetivo: cargar toda la historia disponible desde Wivo hacia tu sistema.

Recomendaciones:

Definir rango de fechas amplio: Por ejemplo, desde 2020-01-01 hasta la fecha actual.
Usar paginación: Iterar por page hasta cubrir todo el rango.
Guardar con lógica de delete+insert: En tu base de datos borra las órdenes e insértalas de nuevo.
Registrar el último purchase_date y updated_at procesados: Esto servirá luego para el flujo incremental.

6.2. Flujo regular (incremental diario / horario)

Objetivo: mantener tus datos sincronizados con Wivo.