API

‍

La API de Wivo permite acceder programáticamente a la misma información que ves en los reportes de la plataforma: ventas, ítems por orden, costos asociados (comisiones, envíos, promociones, publicidad), márgenes, entre otros.

¿Para que sirve la API?

1. Integrar los datos de Wivo en tu data warehouse, ERP, sistema contable o cualquier otra herramienta interna.
2. Automatizar reportes y tableros personalizados sin tener que exportar archivos manualmente.

¿Que datos puedo obtener de la API?

La API entrega información a nivel de ítem de orden (order item), con los principales campos de:

• información de la orden (id, fecha de compra, SKUs, tipo de envio, estado de la orden, estado de pago, etc)
• Costos de la orden: comisiones, envíos, costos de logística
• Otros costos: almacenamiento fulfillment, publicidad, etc
• Métricas derivadas: rentabilidad, rentabilidad %, etc.

2. Habilitación de la API

Para comenzar a usar la API, primero debes habilitarla para tu cuenta.

Pasos para habilitar la API

1. Ingresar a Wivo
   Accede a tu cuenta en Wivo con tu usuario administrador.
2. Ir a Integración con API
   Dentro de la plataforma, ve al menú de la esquina superior derecha.
   Haz clic en la opción "Integración con API"
3. Activar la API para tu cuenta
   • Haz clic en “Solicitar habilitar API”.
   • Agenda una reunión con una agente de Wivo donde se habilitará el API.
4. Obtener tu API Key
   • Una vez habilitada la API se mostrará el API Key.
   • La API Key es personal y secreta, y estará asociada a tu cuenta.

3. Autenticación

La autenticación a la API se realiza mediante un API Key que debes enviar en cada request.

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

Ocp-Apim-Subscription-Key: TU_API_KEY_AQUI

Ejemplo con curl:

curl "https://api.wivoanalytics.com/data" \  
	-H "Ocp-Apim-Subscription-Key: TU_API_KEY_AQUI"

• Si la API Key es inválida, expirada o revocada, la API responderá con HTTP 401 Unauthorized.
• Si no incluyes el header de Ocp-Apim-Subscription-Key, la API responderá con HTTP 401 Unauthorized.

4. Límites de uso (Rate Limits)

Para proteger la estabilidad del servicio, la API aplica límites de consultas por unidad de tiempo.

⚠️ Reemplaza estos valores por los reales que definan ustedes.

• Límite por cuenta: 5 requests por minuto
• Límite diario sugerido: 5000 requests por día

Cuando se excede el límite:

• La API responde con HTTP 429 Too Many Requests.
• El cuerpo incluirá información del límite y el tiempo recomendado de espera antes de reintentar.

Ejemplo de respuesta

{  "error": "rate_limit_exceeded",  
	"message": "Has superado el límite de 5 solicitudes por minuto. Intenta nuevamente en 30 segundos."}

‍

‍Buenas prácticas:

• Implementar reintentos con backoff exponencial en tu cliente.
• Agrupar la lógica para aprovechar al máximo cada request (por ejemplo, usar paginación para traer bloques de datos en vez de hacer muchas consultas muy pequeñas).

5. Los datos que entrega la API

5.1. Endpoints principales

Nota: ajusta rutas y nombres a como lo implementen exactamente.

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

5.2. Parámetros  de GET /data

1. date (purchase_date o updated_at). Debes escoger uno de estos parámetros (obligatorio)
2. from (obligatorio, ISO 8601, ej: 2025-01-31).
3. to (opcional, ISO 8601, ej: 2025-02-01)
4. 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) para actualizar los datos de órdenes y costos a medida que vayan generándose en los marketplaces.

6.1. Flujo histórico (backfill inicial)

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

Recomendaciones:

1. Definir rango de fechas amplio
   • Por ejemplo, desde 2020-01-01 hasta la fecha actual.
2. Usar paginación
   • Iterar por page hasta cubrir todo el rango.
3. Guardar con lógica de delete+insert (revisar)
   • En tu base de datos borra las ordenes e insertalas de nuevo.  
4. 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.

Recomendaciones:

1. Usar el parámetro updated_at
   • Por ejemplo, cada hora: date=updated_at&from= última_fecha_hora_que_procesaste.
   • Así obtendrás órdenes nuevas y actualizaciones (cambios de estado, ajustes de costos, cancelaciones).
   • Es importante que uses la hora para no repetir datos excesivamente entre iteraciones.
2. Repetir la lógica de delete+insert por orden
   • borrar todos los itemes de la orden e insertar por completo de nuevo.
3. Ventana de seguridad
   • Para evitar perder actualizaciones por temas de reloj o latencias, puedes usar una ventana de seguridad de algunos minutos:
     • Si tu último updated_at procesado fue 2025-01-15T10:00:00, en la siguiente corrida puedes pedir desde 2025-01-15T09:55:00.

‍

‍