Sales API

Resumen rápido

La Sales API proporciona métricas de ventas agregadas por intervalos de tiempo. No devuelve pedidos individuales, sino totales: número de pedidos, unidades vendidas, facturación total, precio medio por pedido, etc. Es la API para construir dashboards de rendimiento de ventas.

---

Conceptos importantes

• GetOrderMetrics: La operación principal de Sales API. Devuelve métricas agregadas de pedidos para un intervalo y granularidad dados.
• Granularity: La granularidad temporal del agrupado. Opciones: Hour, Day, Week, Month, Year, Total.
• Interval: El rango de fechas para el que quieres las métricas, en formato ISO 8601.
• OrderMetrics: El objeto de respuesta con las métricas calculadas.
• AverageUnitPrice: Precio medio por unidad vendida.
• TotalSales: Facturación total en el período.
• UnitCount: Total de unidades vendidas.
• OrderItemCount: Total de artículos de pedido (puede ser mayor que el número de pedidos si hay pedidos con varios artículos).
• OrderCount: Número total de pedidos.

---

Cómo funciona

Rate limits de Sales API

Operación	Tasa (req/s)	Burst
GetOrderMetrics	0.5	15

Estructura de la respuesta de GetOrderMetrics

{
  "payload": [
    {
      "interval": "2024-01-01T00:00:00Z--2024-01-31T23:59:59Z",
      "unitCount": 1247,
      "orderItemCount": 1354,
      "orderCount": 1201,
      "averageUnitPrice": {
        "amount": "15.99",
        "currencyCode": "EUR"
      },
      "totalSales": {
        "amount": "19938.53",
        "currencyCode": "EUR"
      }
    }
  ]
}

---

Pasos prácticos

Obtener métricas de ventas del último mes (Python)

import requests
from datetime import datetime, timedelta

def get_order_metrics(
    access_token: str,
    endpoint: str,
    marketplace_id: str,
    granularity: str = "Total",
    days_back: int = 30
) -> list:
    """Obtiene métricas de ventas del período especificado."""
    now = datetime.utcnow()
    start = (now - timedelta(days=days_back)).strftime("%Y-%m-%dT%H:%M:%SZ")
    end = now.strftime("%Y-%m-%dT%H:%M:%SZ")

    headers = {"x-amz-access-token": access_token}
    params = {
        "marketplaceIds": marketplace_id,
        "interval": f"{start}--{end}",
        "granularity": granularity,
    }

    response = requests.get(
        f"{endpoint}/sales/v1/orderMetrics",
        headers=headers,
        params=params,
    )
    response.raise_for_status()
    return response.json()["payload"]

Ejemplo: métricas diarias de los últimos 7 días

metrics = get_order_metrics(
    access_token=token,
    endpoint="https://sellingpartnerapi-eu.amazon.com",
    marketplace_id="A1RKKUPIHCS9HS",
    granularity="Day",
    days_back=7
)

for day in metrics:
    print(f"Día: {day['interval']}")
    print(f"  Pedidos: {day['orderCount']}")
    print(f"  Unidades: {day['unitCount']}")
    print(f"  Facturación: {day['totalSales']['amount']} {day['totalSales']['currencyCode']}")

---

Errores comunes

• Confundir Sales API con Orders API: Sales API da totales agregados; Orders API da pedidos individuales. Para un dashboard de ventas generalmente usas Sales API. Para detalles de pedidos concretos, usas Orders API.
• Formato del intervalo incorrecto: El intervalo se pasa como "INICIO--FIN" (dos guiones). Si el formato no es correcto, dará error.
• Granularidad Total para períodos muy largos: Si pides Total para un año entero, obtienes un único número. Si quieres evolución temporal, usa Day, Week o Month.
• No incluir zona horaria en las fechas: Las fechas deben estar en UTC con el sufijo Z.

---

Qué debo saber antes de programarlo

• Sales API es solo lectura. No puedes modificar nada con ella.
• Los datos son datos de pedidos confirmados, no necesariamente cobrados. Las cancelaciones y devoluciones posteriores no se reflejan en tiempo real.
• Para obtener datos segmentados por ASIN o SKU, necesitas usar la Reports API con un informe de tipo de ventas por producto. Sales API solo da totales del marketplace.
• Esta API es perfecta para construir gráficas de tendencias de ventas en dashboards.
• Si necesitas combinar datos de ventas con datos de publicidad (PPC), necesitas también la Amazon Ads API, que es una API separada con su propio sistema de autenticación.

---

Pendiente de revisar

• ¿Existe un filtro por SKU o ASIN en Sales API, o es siempre a nivel de cuenta?
• ¿Se pueden filtrar por canal de ventas (FBA vs FBM)?
• Verificar si Sales API tiene datos de devoluciones o solo de pedidos creados.