Reports API

Resumen rápido

La Reports API permite generar, programar y descargar los mismos informes que ves en Seller Central. Hay decenas de tipos de informe: inventario, pedidos, rendimiento, fiscales, publicidad, etc. El proceso siempre es asíncrono: primero pides el informe, esperas a que Amazon lo procese, y luego lo descargas. Para evitar peticiones innecesarias mientras esperas, combínala con la Notifications API.

---

Conceptos importantes

• CreateReport: Solicita la generación de un informe de un tipo concreto.
• GetReport: Comprueba el estado de un informe ya solicitado.
• GetReportDocument: Obtiene la URL firmada para descargar el informe una vez procesado.
• ReportType: El tipo de informe que quieres generar (ej. GET_FLAT_FILE_OPEN_LISTINGS_DATA para listings activos).
• ReportId: El identificador del informe generado, devuelto por CreateReport.
• ReportDocumentId: El identificador del documento descargable, devuelto por GetReport cuando el informe está listo.
• ProcessingStatus: Estado del informe: IN_QUEUE, IN_PROGRESS, DONE, CANCELLED, FATAL.
• Compresión: Los informes grandes se comprimen en GZIP. Debes descomprimirlos al descargar.
• Scheduling: Puedes programar informes para que se generen automáticamente de forma periódica.

---

Cómo funciona

Flujo completo de un informe

1. CreateReport  →  Obtienes un reportId
         ↓
2. (Esperar)  →  El informe está IN_QUEUE o IN_PROGRESS
         ↓
3. GetReport  →  Cuando ProcessingStatus = DONE, obtienes reportDocumentId
         ↓
4. GetReportDocument  →  Obtienes una URL firmada temporal
         ↓
5. Descargar la URL  →  Archivo CSV/JSON (posiblemente comprimido en GZIP)

Forma poco optimizada (sondeo periódico): llamas a GetReport cada X segundos hasta que esté listo. Consume más rate limit.

Forma optimizada (Notifications API): te suscribes a REPORT_PROCESSING_FINISHED y Amazon te avisa cuando el informe está listo. Ver 09-notifications-api.md.

Tipos de informe más usados

ReportType	Descripción
GET_FLAT_FILE_OPEN_LISTINGS_DATA	Todos tus listings activos
GET_MERCHANT_LISTINGS_ALL_DATA	Todos tus listings con estado
GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL	Todos los pedidos por fecha
GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE	Informe de liquidación (Settlement)
GET_FBA_MYI_ALL_INVENTORY_DATA	Inventario FBA completo
GET_SELLER_FEEDBACK_DATA	Valoraciones del vendedor
GET_V1_SELLER_PERFORMANCE_REPORT	Rendimiento del vendedor
GET_FLAT_FILE_RETURNS_DATA_BY_RETURN_DATE	Devoluciones

La lista completa está en la documentación oficial bajo "reportType values".

---

Pasos prácticos

Flujo completo con sondeo (Python)

import requests
import time
import gzip
import io

def create_report(access_token: str, endpoint: str, report_type: str, marketplace_id: str) -> str:
    """Solicita un informe y devuelve el reportId."""
    headers = {
        "x-amz-access-token": access_token,
        "Content-Type": "application/json",
    }
    body = {
        "reportType": report_type,
        "marketplaceIds": [marketplace_id],
    }
    response = requests.post(
        f"{endpoint}/reports/2021-06-30/reports",
        headers=headers,
        json=body,
    )
    response.raise_for_status()
    return response.json()["reportId"]


def wait_for_report(access_token: str, endpoint: str, report_id: str, poll_interval: int = 30) -> str:
    """Espera hasta que el informe esté listo y devuelve el reportDocumentId."""
    headers = {"x-amz-access-token": access_token}

    while True:
        response = requests.get(
            f"{endpoint}/reports/2021-06-30/reports/{report_id}",
            headers=headers,
        )
        response.raise_for_status()
        data = response.json()
        status = data["processingStatus"]

        if status == "DONE":
            return data["reportDocumentId"]
        elif status in ("CANCELLED", "FATAL"):
            raise Exception(f"El informe falló con estado: {status}")

        time.sleep(poll_interval)


def download_report(access_token: str, endpoint: str, report_document_id: str) -> str:
    """Descarga el contenido del informe y lo devuelve como texto."""
    headers = {"x-amz-access-token": access_token}

    # Obtener la URL firmada
    response = requests.get(
        f"{endpoint}/reports/2021-06-30/documents/{report_document_id}",
        headers=headers,
    )
    response.raise_for_status()
    doc_data = response.json()

    url = doc_data["url"]
    compression = doc_data.get("compressionAlgorithm")

    # Descargar el contenido
    content_response = requests.get(url)
    content_response.raise_for_status()

    if compression == "GZIP":
        return gzip.decompress(content_response.content).decode("utf-8")
    return content_response.text


# Uso completo
def get_report_content(
    access_token: str,
    endpoint: str,
    report_type: str,
    marketplace_id: str
) -> str:
    report_id = create_report(access_token, endpoint, report_type, marketplace_id)
    print(f"Informe creado: {report_id}")

    doc_id = wait_for_report(access_token, endpoint, report_id)
    print(f"Informe listo: {doc_id}")

    content = download_report(access_token, endpoint, doc_id)
    print(f"Descargado: {len(content)} caracteres")
    return content

Parsear el CSV del informe de pedidos

import csv
import io

def parse_orders_report(csv_content: str) -> list[dict]:
    reader = csv.DictReader(io.StringIO(csv_content), delimiter="\t")
    return list(reader)

La mayoría de informes de Seller Central son TSV (tabulaciones, no comas).

---

Errores comunes

• Sondear demasiado frecuente: Llamar a GetReport cada pocos segundos consume rate limit innecesariamente. Usa intervalos de 30-60 segundos o mejor, la Notifications API.
• No manejar la compresión GZIP: Los informes grandes están comprimidos. Si intentas leerlos como texto directamente, obtendrás bytes ilegibles.
• Ignorar el estado FATAL: Significa que el informe falló (ej. no hay datos para ese período). Debes manejarlo.
• Usar la URL del documento directamente sin descargarla rápido: La URL firmada expira en poco tiempo (generalmente 5 minutos). Descarga inmediatamente.
• No saber qué reportType usar: Amazon tiene decenas de tipos. Revisa la documentación oficial o prueba en Seller Central descargando el informe manualmente y buscando su nombre.

---

Qué debo saber antes de programarlo

• Los informes grandes pueden tardar minutos o incluso horas. No asumas que están listos en segundos.
• Para apps de producción, la arquitectura recomendada es:
  1. Solicitar el informe.
  2. Guardar el reportId en base de datos.
  3. Suscribirse a la notificación REPORT_PROCESSING_FINISHED.
  4. Cuando llega la notificación, descargar el informe.
  5. Procesar y guardar los datos.
• Los informes de tipo Settlement (liquidaciones) no se generan bajo demanda; Amazon los genera automáticamente cada 2 semanas. Puedes descargarlo una vez generado, pero no pedirlo antes.
• Combinado con Notifications API, este flujo reduce las llamadas a la API hasta 100 veces respecto al sondeo manual.

---

Pendiente de revisar

• ¿Hay algún tipo de informe que devuelva datos de ventas por ASIN desagregados?
• ¿Cuánto tiempo están disponibles los documentos de informe antes de que caduquen?
• Confirmar qué informes están disponibles para Vendor Central vs Seller Central.