Skip to content

API de Epinium ​

Acceso: Configuración → API Keys

Epinium expone tus datos por una API REST para que puedas leerlos desde tus propias herramientas: un cuadro de mando propio, un script de análisis o un asistente de IA. Es la misma información que ves en la app, con las mismas cifras.

La API lee tus datos y escribe en Amazon y en tus tiendas: consulta catálogo, campañas y métricas, tu P&L con coste de producto, y lo que hay dentro de tus tiendas de Shopify y WooCommerce; crea y edita campañas de Sponsored Products y edita las de Sponsored Brands y Display; crea y edita carteras; crea, edita, clona y ejecuta workflows; crea, resuelve y aplica tareas; da de alta o actualiza el coste de tus productos y registra sus compras a proveedores; guarda cambios en cualquier atributo de tus listings de Amazon y da de alta ofertas, productos nuevos y familias de variaciones; y crea, edita y borra productos y contenido en tus tiendas Shopify y WooCommerce conectadas. En tu catálogo de Amazon, lo que guardas queda pendiente y solo llega a Amazon cuando se publica, desde la app o desde la API con su propio permiso; el de tus tiendas cambia directamente, sin quedar pendiente. Cada área tiene su permiso, y los de escritura los das tú al crear la clave.

¿Buscas usarla desde un asistente de IA?

No necesitas programar nada. El MCP de Epinium conecta estos mismos datos con Claude y otros asistentes compatibles.

Generar un token ​

  1. Ve a Configuración → API Keys
  2. Haz clic en Crear API key y dale un nombre que te recuerde para qué es
  3. Marca los permisos que necesite
  4. Copia la clave y guárdala en un sitio seguro
  5. Úsala en la cabecera Authorization de cada petición

La clave solo se muestra una vez

Al crearla se ve el valor completo una única vez. Si la pierdes no se puede recuperar: hay que revocarla y crear otra.

Permisos ​

Cada token lleva los permisos que le marques al crearlo. Concede solo los que la integración necesite.

PermisoDa acceso a
catalog:readProductos, marcas, países, clusters, prompts personalizados e identidad de marca, con sus métricas: ventas, comisiones de Amazon y margen, devoluciones, stock y, en Vendor, reseñas; y tu P&L, con el coste de producto y tus gastos propios si tu plan lo incluye
campaigns:readCampañas, carteras, ad groups, targets, product ads y términos de búsqueda
workflows:readTus workflows, su configuración y a qué campañas llegan
connections:readLas conexiones de tu cuenta: Amazon, Shopify y WooCommerce
tasks:readTareas de Epinium y sus items
skills:readEl catálogo de playbooks de marketing validados de Epinium
platform:readLo que hay dentro de tus tiendas de Shopify y WooCommerce: productos, stock, precios y el resto de lo que expone cada tienda, leído en directo de su propia API. Incluye el registro de los cambios hechos en ellas (/v1/platform-changes, 1 crédito por fila devuelta)
catalog:writeCrear, editar y borrar clusters de keywords: su nombre, sus keywords positivas y negativas, los productos que agrupan y los prompts que usan. Crear y editar prompts personalizados. Crear y editar tu identidad de marca, con una ficha por competidor. Guardar cambios en los atributos de tus listings de Amazon desde un fichero, como cambios pendientes de publicar. Guardar y descartar altas en Amazon (ofertas sobre productos que ya existen, productos nuevos y familias) y subir imágenes de producto. Nada llega a Amazon hasta que lo publicas
costs:writeDar de alta o actualizar el precio de coste y el coste de envío de tus productos, y registrar, corregir y borrar sus compras, uno a uno o importándolos desde un fichero; y crear, cambiar y borrar tus gastos propios y sus categorías
campaigns:writeCrear y modificar campañas, carteras, ad groups, targets y product ads en Amazon, y configurar qué persigue el optimizador en cada una
platform:writeCrear, editar y borrar productos y contenido en tus tiendas Shopify y WooCommerce conectadas, directamente y sin revisión previa, por la misma ruta con la que se consultan (POST /v1/platform-request): una mutation en Shopify, o un método que no sea GET en WooCommerce, con la cabecera Idempotency-Key. Necesita también platform:read (el nivel Editar de la pantalla de API keys concede las dos). Cada cambio queda registrado 12 meses y cuesta lo mismo que una consulta: 5 créditos por llamada más 1 por KB devuelto
tasks:writeCrear tareas, aprobar o rechazar sus sugerencias, cerrarlas y aplicar lo aprobado. Pedir a la IA de Epinium que reescriba fichas como sugerencias de una tarea
workflows:writeCrear, copiar, editar, encender, pausar, borrar y restaurar workflows, y lanzarlos o simularlos
catalog:publishPublicar en Amazon los cambios de listings y las altas pendientes que elijas (POST /v1/pending-listing-changes/publish), por el mismo camino que el botón Publicar de la app. No se puede deshacer. Necesita también catalog:write

Escribir es de los planes Business y Master. En Free y Guru los tokens leen: no se puede crear una clave ni autorizar un asistente con permisos de escritura, y si bajas a uno de esos planes, los que ya tuvieras siguen leyendo pero sus escrituras se rechazan con un 403.

Un token alcanza todas las conexiones de tu cuenta. Si eres una agencia, alcanza las conexiones que cada cliente te haya compartido al aceptar tu invitación.

Si eres una agencia: elige la cuenta en cada llamada ​

Un token de agencia alcanza varias cuentas, así que cada petición tiene que decir sobre cuál opera. Con la cabecera Epinium-Account: <id de la cuenta>, o con el parámetro account_id si llamas desde el MCP.

/v1/me y /v1/accounts son la excepción: responden sin elegir cuenta, y son precisamente los que te dicen qué cuentas alcanzas y cómo se llaman.

Elegida la cuenta, la ves entera: sus productos y campañas se acotan a las conexiones que te compartió, y sus recursos de cuenta —workflows, tareas y clusters, que no cuelgan de ninguna conexión— se acotan a la cuenta. Lo que no está en tu alcance no se filtra en silencio: un account_id que no tengas invitado devuelve un error explícito, no una lista vacía.

Qué endpoints cubre ​

Cada recurso tiene un listado, y la mayoría permite además recuperar un elemento por su id. Los recursos de métricas solo tienen listado: una fila agregada sobre un rango de fechas no tiene identificador propio.

Catálogo — catalog:read ​

EndpointQué devuelve
/v1/productsTus productos unificados
/v1/amazon-seller-productsLa vista de Seller Central de cada producto, y la categoría de su ranking con expand=salesRanks
/v1/amazon-vendor-productsLa vista de Vendor Central, la categoría del ranking con expand=salesRanks y las reseñas con expand=customerFeedback
/v1/amazon-advertising-productsLa vista de Advertising
/v1/seller-product-metricsVentas, sesiones, Buy Box, rank, comisiones de Amazon, margen, devoluciones, stock, B2B y días de cobertura por producto
/v1/vendor-product-metricsVentas de Vendor por producto, con manufacturing y sourcing, devoluciones, sell-in con Amazon, inventario y días de cobertura
/v1/product-brandsTus marcas
/v1/countriesPaíses y marketplaces
/v1/clustersTus clusters de keywords; con catalog:write también los creas y editas
/v1/pnl/*Tu P&L: cascada, tabla por producto, por cluster, por canal de venta, publicidad cruzada, frescura, fugas de margen e inventario - explicado en El P&L con coste de producto
/v1/promptsTus prompts personalizados; con catalog:write también los creas y editas
/v1/brand-identitiesTu identidad de marca, con una ficha por competidor; con catalog:write también la creas y editas - explicado en Escribir tu identidad de marca
/v1/listing-filesLos ficheros de cambios de listings que has subido en los últimos 7 días; subir uno pide catalog:read, y guardar como fichero unas filas escritas a mano, catalog:write
/v1/listing-updatesPreparar y validar los cambios de un fichero sin guardar nada; con catalog:write, guardarlos como pendientes de publicar - explicado en Cambiar listings desde un fichero
/v1/listing-draftsTus altas en Amazon y su estado; con catalog:write, guardarlas y descartarlas. Para buscar el producto y validarlas, /v1/amazon-catalog/search, /v1/amazon-product-types/search, /v1/amazon-shipping-templates y /v1/listing-drafts/validate - explicado en Dar de alta productos en Amazon
/v1/listing-imagesCon catalog:write, subir una imagen de producto para una ficha o un alta: JPG, PNG, GIF o TIFF, hasta 8 MB, guardada 30 días
/v1/pending-listing-changesLo que hay pendiente de publicar en Amazon, cambios y altas; con catalog:write y catalog:publish, publicarlo
/v1/publicationsCada publicación en Amazon y cómo va por país, como el panel de Publicaciones de la app

Publicidad — campaigns:read ​

EndpointQué devuelve
/v1/campaignsTus campañas de Amazon Advertising
/v1/campaigns/budget-usageCuánto lleva gastado hoy cada campaña de su presupuesto diario, según Amazon y con media hora de retraso como mucho
/v1/campaign-metricsGasto, ventas, ACOS y ROAS por campaña
/v1/portfoliosTus carteras y el tope de presupuesto que cada una pone a sus campañas
/v1/portfolios/budget-usageCuánto lleva gastado cada cartera de su tope este periodo, a qué ritmo va y cuánto puede gastar al día para acabar justo
/v1/adgroupsLos ad groups de cada campaña
/v1/adgroup-metricsRendimiento por ad group
/v1/targetsKeywords y targets de producto
/v1/target-metricsRendimiento por target, con su keyword y tipo de concordancia
/v1/product-adsEl vínculo entre un ad group y el producto que anuncia
/v1/product-ad-metricsRendimiento por producto anunciado, con su ASIN
/v1/search-termsLas búsquedas reales de los compradores
/v1/search-term-metricsRendimiento por búsqueda, con el texto y el target que la emparejó
/v1/campaigns/{id}/optimization-historyQué cambió la automatización en una campaña, con el efecto neto
/v1/advertising-changesTodo lo que Epinium ha cambiado en Amazon, venga de donde venga

Automatización — workflows:read ​

EndpointQué devuelve
/v1/workflowsTus workflows, con su programación y si están activos
/v1/workflows/{id}La configuración completa de uno: su diagrama y cada variable con su valor efectivo
/v1/workflows/{id}/campaignsA qué campañas llega de verdad, y por qué entra cada una
/v1/workflows/{id}/performanceEl rendimiento de esas campañas, con su objetivo al lado para poder juzgarlo

Un workflow puede estar programado todas las noches y no tocar ninguna campaña: /campaigns es lo que lo destapa, y cuando el conjunto sale vacío dice el motivo.

Conexiones, tareas y skills ​

EndpointPermisoQué devuelve
/v1/connectionsconnections:readTus conexiones: Amazon, Shopify y WooCommerce
POST /v1/platform-requestplatform:read, y platform:write para escribirUna consulta a una de tus tiendas o, con platform:write, un cambio en ella: GraphQL en Shopify, REST en WooCommerce
/v1/platform-request/docs/{platform}platform:readLa versión de la API de esa plataforma, su referencia y los campos que tiene tu tienda ahora mismo
/v1/taskstasks:readTareas de Epinium
/v1/task-itemstasks:readLos items de cada tarea
/v1/skillsskills:readEl catálogo de playbooks de marketing de Epinium

El catálogo de skills es contenido escrito por Epinium, no datos de tu cuenta: es el mismo para todos los clientes. Qué partes de cada playbook recibes depende de tu plan.

Las consultas a tus tiendas no devuelven datos personales: nombres, emails, teléfonos y direcciones se rechazan antes de que la petición llegue a la tienda. Se cobran por el tamaño de la respuesta, igual que los cambios. Estas dos rutas no están en la referencia navegable: lo habitual es usarlas desde el MCP de Epinium.

Además, /v1/me te dice qué permisos y qué cuentas alcanza tu token. Es la primera llamada útil para comprobar que la clave funciona.

Tres reglas al leer los datos ​

Estas tres explican casi todas las dudas de interpretación:

  • Los importes son texto, no números. "cost": "8.22" llega como cadena a propósito, para que no pierda precisión al convertirse a decimal binario.
  • Los ratios van en fracción, no en porcentaje. Un ACOS del 90,83 % llega como 0.908287. Multiplica por 100 para mostrarlo.
  • null no es 0. null significa que Amazon no reportó ese dato; 0 significa cero de verdad. Un acos a null es una campaña que gastó sin vender, no publicidad gratis. Y new_to_brand_sales llega a null en Sponsored Products porque Amazon no lo mide en ese formato.

Rentabilidad, stock y reseñas de tus productos ​

Las métricas de producto no se quedan en las ventas: también dicen cuánto se queda Amazon, cuánto stock queda y qué opinan los compradores. Cuatro cosas antes de sacar conclusiones:

  • Las comisiones y el margen de Seller van sin IVA, y sales lo lleva donde aplica: no restes unas de otro. margin_before_ads es lo que queda después de pagar a Amazon, antes de publicidad y del coste del producto: para el margen después de anuncios, réstale el gasto de /v1/product-ad-metrics. Amazon imputa el almacenamiento a un solo día del mes y las devoluciones a la fecha del reembolso, así que el margen se lee por meses, no por días.
  • days_of_coverage son los días que dura el stock al ritmo de la ventana: el stock del último día entre las unidades medias diarias del rango que pidas. Sale a null con cualquier granularidad que no sea total, si el producto no vendió nada o, al agrupar, si group_by no incluye el país. Con order_by=days_of_coverage&order=asc tienes primero los que están a punto de agotarse.
  • En Vendor también está el sell-in: las unidades que confirmaste a Amazon, las de pedidos de compra abiertos, el fill rate y el plazo de entrega, además de las devoluciones separadas por manufacturing y sourcing y la salud del inventario.
  • La categoría del ranking y las reseñas se piden al producto, no a las métricas. expand=salesRanks dice en qué categoría está cada posición del Best Seller Rank, y en Vendor expand=customerFeedback devuelve los temas positivos y negativos de las reseñas y los motivos de devolución de la categoría. Es la foto de esta semana, con la tendencia de seis meses que calcula Amazon, no un histórico.

Totales de cuenta, por periodo y por cluster ​

Para saber cuánto vendió la cuenta en septiembre no hace falta paginar el catálogo y sumar: los siete recursos de métricas agregan ellos mismos.

  • group_by suma entre entidades. account da el total de la cuenta; country y connection desglosan por país o por conexión, y se combinan repitiendo el parámetro (group_by[]=connection&group_by[]=country). account no se combina con nada. Las filas siguen separadas por moneda —los importes nunca se convierten— y, en publicidad, por tipo de anuncio (SP, SB, SD).
  • granularity parte el rango en periodos de calendario. Además de total y daily acepta weekly, monthly, quarterly y yearly, y cada fila lleva en date el inicio de su periodo: el lunes de la semana o el día 1 del mes, del trimestre o del año. Los periodos de los extremos son parciales: del 15 de enero al 10 de marzo con monthly devuelve enero del 15 al 31, febrero entero y marzo del 1 al 10.
  • cluster acota a una familia de productos. En las métricas de Seller, Vendor y producto anunciado, cluster=<id> deja solo los productos de ese cluster; con varios ids, la unión. Se combina con lo anterior: group_by=account&granularity=monthly&cluster=<id> es la serie mensual de esa familia.
  • group_by=cluster da una fila por cluster. En las mismas tres métricas, group_by=cluster devuelve en una sola llamada las cifras de cada uno de tus clusters, con su id en cluster y su nombre en cluster_name. Un producto que está en varios clusters cuenta entero en cada uno, así que las filas no suman el total de la cuenta, y los productos sin cluster no aparecen. Se combina con country y connection, y con el filtro cluster para elegir qué clusters salen; si tus clusters suman más de 2.000 pertenencias producto-cluster, la API te pide que los acotes con ese filtro.

En las filas agrupadas, los campos que identifican una entidad (product, asin, campaign…) salen a null, igual que lo que no se puede sumar: el rank, el precio, el canal y las tasas de Vendor. El stock de Seller solo se suma si agrupas por país: con el inventario paneuropeo de FBA, Amazon reporta el mismo stock en cada marketplace, y sumarlo entre países contaría las mismas unidades varias veces. Por eso, con group_by=account o connection, stock y days_of_coverage salen a null.

Un cluster agrupa productos del catálogo, no ASINs sueltos: el mismo ASIN en otra conexión queda fuera salvo que su producto también esté en el cluster. Y las filas que Amazon no pudo asociar a un producto del catálogo no entran en el filtro: en torno al 5 % de las ventas de Vendor y al 3 % del gasto en producto anunciado.

Cuánto ahorra en créditos lo tienes en Créditos.

El P&L con coste de producto ​

Es la misma cuenta de resultados que ves en Rentabilidad → P&L: ventas, comisiones y logística de Amazon, publicidad y, si tu plan lo incluye, el coste de tus productos y tus gastos propios, con el mismo cálculo y las mismas cifras.

Lo que ves depende de tu plan. En Free y Guru el P&L llega hasta margin_before_ads: lo que queda después de Amazon, antes de publicidad y antes del coste de producto - no lo llames "beneficio", porque no lo es. En Business y Master llega hasta el final: margen de contribución, cada línea de coste de producto y su cobertura, y tus gastos propios hasta el beneficio neto. includes_product_cost en cada respuesta te dice cuál de los dos estás viendo, así que no hace falta que lo adivines por si las cifras cuadran con lo que esperabas. Fugas de margen (/v1/pnl/margin-leaks y /v1/pnl/category-medians) es solo de Business y Master: en Free y Guru responde 403 con code: "plan_feature_not_allowed", y sus respuestas no llevan includes_product_cost, porque siempre incluyen el coste. Lo mismo pasa con el inventario (/v1/pnl/inventory), que se valora con el coste de producto.

EndpointQué devuelve
/v1/pnl/cascadeLa cascada del periodo: ventas, refunds, comisiones, logística, publicidad, coste de producto y gastos propios hasta el beneficio neto, mes a mes o día a día
/v1/pnl/productsUna fila por producto, con su margen de contribución y su cobertura de coste
/v1/pnl/products/{id}El detalle de un producto: su propia cascada, mes a mes
/v1/pnl/clustersUna fila por cluster, con su margen de contribución, su cobertura de coste y cuántos productos tiene
/v1/pnl/channelsUna fila por canal de venta (Seller, Vendor…), con su publicidad desglosada por plataforma
/v1/pnl/ads-matrixEl gasto publicitario cruzado: en qué canal de venta se anuncia cada plataforma
/v1/pnl/freshnessLa fecha del último dato de cada fuente -Amazon, publicidad y coste de producto- para saber si lo que lees ya está completo
/v1/pnl/margin-leaksLos productos que han perdido margen frente al periodo anterior, ordenados por el dinero en riesgo, con su estado, su causa principal y los totales de todo el ranking: lo mismo que Fugas de margen
/v1/pnl/category-mediansLo habitual en tu cuenta: la mediana del peso de cada coste sobre las ventas netas, para ver si el coste de un producto está fuera de lo normal
/v1/pnl/inventoryEl capital inmovilizado en los almacenes de Amazon: el stock FBA de hoy valorado a coste, con sus días de stock, su rotación y el almacenamiento hasta venderlo: lo mismo que Inventario

Nueve cosas que conviene saber antes de la primera llamada:

  • Esta es la única parte de la API que convierte moneda. El resto de recursos devuelve cada importe en la moneda en la que ocurrió; aquí pides currency y todo se convierte a ella, al tipo de cambio del día en que ocurrió cada importe. Un día sin tipo de cambio cae a uno aproximado, nunca a un error.
  • Los gastos propios vienen en own_expenses. Los variables ya están restados en la sección variable_expenses, antes del margen de contribución, y own_expenses.periods[].variable los desglosa por categoría. Los fijos (fixed) se restan después, hasta net_profit. Como son de toda la cuenta, con connection, country o cluster, o con un token que no alcanza todas las conexiones de venta, fixed y net_profit salen null y fixed_unavailable dice por qué: filtered o partial_access. Si la cuenta no tiene gastos fijos no falta nada, y net_profit sale también con filtro o con un token que no alcanza todas las conexiones. En la tabla por producto, la columna own_expenses es la parte de los gastos variables de cada producto.
  • coverage dice qué parte de las ventas tiene coste real. Un producto sin coste cargado no se descarta ni se pone a cero en silencio: coverage.covered_sales sobre coverage.total_sales te dice qué proporción de la cifra es de fiar. En coverage, estimated_sales es la parte de covered_sales con coste estimado: el stock vendió más unidades de las que dejaron las compras registradas, y esas ventas llevan el último coste medio.
  • breakeven_acos, en /v1/seller-product-metrics, es hasta qué ACOS te puedes permitir gastar en publicidad antes de perder dinero con ese producto, calculado con tu margen real y tu coste real -nunca con un porcentaje de comisión supuesto. Sale null -nunca un número inventado- si el producto no tiene coste completo, si no vendió nada en la ventana, si el coste está registrado en una moneda distinta de la del propio marketplace (este recurso no convierte monedas, al contrario que /v1/pnl/*) o si tu plan no incluye coste de producto (Free y Guru).
  • El coste de producto se conserva al bajar de plan, no se borra. Si pasas a Guru, el coste que ya tenías cargado sigue ahí: solo deja de servirse. Vuelve a aparecer en cuanto subes de plan otra vez.
  • cluster acota /v1/pnl/cascade, /v1/pnl/products, /v1/pnl/clusters, /v1/pnl/freshness, /v1/pnl/margin-leaks, /v1/pnl/category-medians y /v1/pnl/inventory a los productos de uno o varios clusters, igual que en las métricas: con varios ids, la unión, y un cluster sin productos devuelve vacío, no un error. La publicidad solo cuenta el gasto de esos productos: Sponsored Brands y el gasto de campaña que no corresponde a un producto concreto se quedan fuera, porque no pertenecen a ningún cluster. En /v1/pnl/clusters un producto que está en dos clusters cuenta en los dos, y lo que no está en ningún cluster no sale.
  • /v1/pnl/margin-leaks devuelve por defecto los productos en los tres estados, igual que la pantalla; con status te quedas con los que elijas. En la misma llamada, summary trae cuántos hay de cada estado y el total en riesgo de los productos en Fuga y A vigilar de todo el ranking, sin paginar, y cada fila trae main_cause, el coste que más margen ha quitado, calculado igual que en la pantalla. Si el periodo anterior no tiene ventas, has_previous_sales sale false: la lista vacía quiere decir que no hay con qué comparar, no que no haya fugas.
  • /v1/pnl/inventory es el stock de hoy, sin periodo: una fila por stock, y en la UE un SKU paneuropeo sale una sola vez, con todos sus countries, así que no sumes filas entre países. summary trae el capital inmovilizado de todo el alcance y su reparto por rotación, sin paginar y sin que le afecten rotation ni search. currency es obligatoria: el coste se convierte al último tipo de cambio y el almacenamiento, al de cada día. Solo cuenta el stock FBA de tus conexiones Seller.
  • El coste que vale hoy de cada producto viene en /v1/products. El campo cost trae cogs y shipping, cada uno con el importe por unidad, su moneda, valid_from y source, o null si no lo tiene. Con cost_state te quedas con los productos activos with (con coste), missing (sin coste) o missing_with_sales (sin coste y con ventas en los últimos 30 días, los que más inflan el margen), y con include_total sabes cuántos son. Es lo mismo que ves en Costes y gastos. En Free y Guru cost sale null y cost_state responde 403.

Qué cambió la automatización en una campaña ​

/v1/campaigns/{id}/optimization-history responde qué cambió el workflow en una campaña, no qué decidió. La diferencia importa: en un historial de decisiones el mismo target puede aparecer con una subida y una bajada la misma noche, y ahí no se ve que se anulan entre sí.

Por eso cada fila viene agregada al efecto neto de la entidad: la puja de antes del primer cambio del periodo contra la de después del último, y cuántas veces se movió por el camino. Un target que subió de 0,18 € a 0,45 € y esa misma noche volvió a 0,18 € sale con un neto de cero y dos movimientos — que es la lectura útil, y justo la que un listado esconde.

Tres cosas delimitan lo que devuelve:

  • Solo cambios reales. Las simulaciones no se exponen aquí, ni con ningún parámetro: son pujas que nunca llegaron a Amazon.
  • Solo lo aplicado, no lo propuesto. El optimizador calcula una puja que después un tope puede recortar; solo se reporta lo que se envió.
  • Ventana máxima de 90 días. Es lo que se conservan estos registros. Sin fechas, devuelve los últimos 90 días.

Los cambios que no son de puja —keywords cosechadas, negativos, ajustes de emplazamiento, targets en cuarentena o bloqueados— van contados aparte en other_changes, porque no tienen una puja anterior con la que compararse.

Todo lo que Epinium ha cambiado en Amazon ​

/v1/advertising-changes responde a una pregunta distinta de la anterior: no por qué decidió la automatización, sino qué se tocó y si Amazon lo aceptó. Y no solo lo de la automatización: también lo que hizo una persona desde la aplicación, un proceso interno o esta misma API.

La regla es de una línea: si se envió a Amazon, hay fila. De ahí salen tres consecuencias que conviene tener claras:

  • Lo que Amazon rechazó también deja fila, con result: "failed" y el mensaje de Amazon en error. Es el primer sitio donde mirar cuando un cambio no surtió efecto.
  • Lo que no se llegó a intentar no deja fila: un presupuesto por debajo del mínimo del país, o una puja que ya era la que se pedía.
  • Los cambios de configuración dentro de Epinium quedan fuera, porque no salen hacia Amazon.

Cada fila dice de dónde vino. source distingue la aplicación (front), el optimizador (workflow), un proceso interno (system) y este canal (public-api, mcp), y actor identifica a la persona o a la credencial concreta — cuando el cambio lo hizo alguien desde la aplicación, ahí está su email. Si vino de un workflow, correlation_id es el identificador de esa ejecución, que es la clave para cruzar esta respuesta con optimization-history.

Puedes filtrar por campaign, adgroup, entity, entity_type, source, result, field y correlation_id, y acotar la ventana con start_date y end_date (YYYY-MM-DD, los dos incluidos). Los registros se conservan doce meses.

Escribir en Amazon ​

Con el permiso campaigns:write, la API deja de solo leer: crea campañas, ad groups, targets y product ads, y mueve sus estados, presupuestos y pujas. Lo escrito sale hacia Amazon de verdad y deja su fila en /v1/advertising-changes.

Cinco cosas que conviene saber antes de la primera llamada:

  • Todo nace en pausa. Una campaña o un ad group se crean PAUSED salvo que pidas ENABLED explícitamente, porque lo activo empieza a gastar en cuanto Amazon lo acepta.
  • Archivar tiene verbo propio: DELETE /v1/<recurso>/{id}. Es la única operación irreversible de esta API: en Amazon archivar no se deshace. Por eso no es un valor de state que puedas poner sin querer junto a un cambio de puja, sino otra llamada con otro verbo. Si solo quieres parar el gasto, usa state: "PAUSED", que sí se deshace.
  • Toda escritura exige una cabecera Idempotency-Key. Reutiliza el mismo valor si reintentas la misma intención: sin eso, un timeout de red se convierte en dos campañas.
  • Un lote no es todo-o-nada. POST /v1/<recurso>/batch admite hasta 1.000 entidades y responde una fila por cada una, en el orden en que las mandaste. applied es lo que llegó a Amazon, y es lo único que se cobra. Un resultado parcial es lo normal, no un error: léelo en vez de reintentar el lote entero, porque un reintento duplicaría lo que sí entró.
  • Una entidad solo cuenta como aplicada si entró todo lo que pediste sobre ella. Si en un PATCH cambias estado y presupuesto y Amazon acepta el primero y rechaza el segundo, esa entidad sale failed con el motivo — decir que se aplicó es como se acaba creyendo que la puja se movió cuando no.
RutaQué hace
POST /v1/campaignsCrear una campaña
POST /v1/campaigns/fullCampaña + ad group + targets + product ads en una llamada
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batchEstado, presupuesto diario, nombre y cartera (la cartera, solo en Sponsored Products)
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batchCrear; estado, puja por defecto y nombre
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batchCrear targets (los tipos dependen del ad product del ad group); estado y puja
POST /v1/product-ads · PATCH /v1/product-ads/{id} · POST /v1/product-ads/batchAnunciar productos; estado
POST /v1/portfolios · PATCH /v1/portfolios/{id}Crear una cartera; nombre, estado y tope de presupuesto
DELETE /v1/campaigns/{id} · DELETE /v1/adgroups/{id} · DELETE /v1/targets/{id} · DELETE /v1/product-ads/{id}Archivar - irreversible

Lo que no se puede cambiar, y por qué: lo que define a un target —su keyword, su ASIN, su concordancia— no es editable en Amazon, así que para cambiarlo se crea otro y se archiva el anterior. Un product ad solo admite estado: es el enlace entre un producto y un ad group, no tiene puja ni nombre propios.

El tope de una cartera limita lo que gastan juntas todas sus campañas. MONTHLY_RECURRING se reinicia cada mes, DATE_RANGE vale entre startDate y endDate y NO_CAP lo quita; la moneda es la del marketplace y no se envía. En un PATCH, budget se sustituye entero: manda el tope completo que quieres, no solo el importe. Para meter o sacar una campaña de Sponsored Products de una cartera, cambia su portfolioId con PATCH /v1/campaigns/{id}.

Dos códigos que conviene distinguir. Una entidad que no existe, o que es de otra cuenta, responde 404 — nunca 403, que confirmaría que existe. Un rechazo de Amazon responde 200 con result: "failed" y el motivo: la llamada sí llegó, y lo que falló fue el cambio.

Los tres ad products se escriben, pero no igual:

  • Sponsored Brands y Sponsored Display se cambian y se archivan con las mismas rutas que Sponsored Products: estado, presupuesto, nombre y pujas de campañas, ad groups, targets y product ads. Lo que todavía no se puede es crearlos: POST /v1/campaigns, /v1/campaigns/full, /v1/adgroups y /v1/product-ads son solo de Sponsored Products.
  • Los ad groups de Sponsored Brands no tienen puja por defecto. Un cambio de defaultBid sobre uno se rechaza con un mensaje que lo explica. Los de Sponsored Display sí la tienen.
  • Los targets y targets negativos sí se crean en ad groups de SB y SD, con POST /v1/targets. El targetType admitido depende del ad product del ad group (tabla de abajo). Solo a nivel de ad group: SB y SD no tienen targets negativos de campaña.
  • Epinium solo comprueba los límites de puja y presupuesto del marketplace en Sponsored Products, antes de enviar. En Brands y Display no aplica límites propios: valida Amazon y su motivo vuelve en la respuesta, por entidad con result: "failed" o, al crear targets, en failure_details, donde reference identifica el target (keyword, ASIN, SKU o el id de audiencia, categoría o ubicación).
Ad producttargetType admitidos
Sponsored ProductsKEYWORD, PRODUCT, PRODUCT_CATEGORY
Sponsored BrandsLos de Sponsored Products y THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND o KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES)
Sponsored DisplayKEYWORD; PRODUCT por ASIN o por sku, con productMatchType PRODUCT_EXACT o PRODUCT_SIMILAR; PRODUCT_CATEGORY con refinamientos (marca, precio, valoración, rango de edad, elegibilidad Prime); THEME (INTERESTED_AUDIENCE); PRODUCT_AUDIENCE (ASIN + event PURCHASE o VIEW + lookback de 7, 14, 30, 60, 90, 180 o 365 días); AUDIENCE (audienceId), CONTENT_CATEGORY (contentCategoryId) y LOCATION (locationId)

Los ids de AUDIENCE, CONTENT_CATEGORY y LOCATION salen de la consola de Amazon Ads: la API todavía no los lista.

Configuración de optimización ​

Con el mismo permiso campaigns:write, además de escribir en Amazon puedes leer y cambiar la configuración que usa el optimizador de Epinium: qué persigue en cada campaña. Es una superficie distinta de la de la sección anterior, y no conviene confundirlas.

No sale hacia Amazon. Es configuración propia de Epinium que consume el optimizador en su ejecución de cada noche, no un dato de la cuenta de Amazon. Por eso aquí no se cumplen dos reglas de "Escribir en Amazon": no hace falta cabecera Idempotency-Key -no hay ningún viaje de ida y vuelta a Amazon que un reintento pueda duplicar- y el cambio no deja fila en /v1/advertising-changes, que solo registra lo que se envió a Amazon.

Se lee con expand, no por defecto. GET /v1/campaigns y GET /v1/campaigns/{id} solo devuelven optimizationConfig si pides ?expand[]=optimizationConfig. Es opt-in porque muy pocas campañas tienen esta configuración guardada: sin el expand, la columna saldría casi siempre a null.

Lo que se puede fijar con PATCH /v1/campaigns/{id}/optimization-config, en lenguaje de negocio:

  • El objetivo: un ACOS o un ROAS objetivo, o un objetivo de volumen -impresiones o pedidos- con un techo de ACOS que lo acompañe.
  • Los límites de puja: el suelo y el techo que no puede cruzar, el tope del multiplicador de placement, y el gasto mínimo antes de negativizar un target.
  • El presupuesto mensual que persigue el optimizador -no el presupuesto diario de la campaña en Amazon, que se cambia con PATCH /v1/campaigns/{id} y es un dato distinto con el mismo nombre.
  • Los overrides de harvesting de la campaña: su nivel de descubrimiento y si permite apuntar a ASINs de la competencia.
  • Qué workflows la optimizan.

Este último punto es el que de verdad importa: asignar workflows es lo que pone la campaña bajo optimización, no ningún otro campo de este bloque. linkedWorkflowDefinitionIds la fuerza a entrar -el workflow la procesa cada noche aunque su propio filtro no la hubiera elegido- y es la vía por la que un workflow mueve pujas reales en Amazon; confírmalo con la persona antes de escribirlo, igual que activar una automatización. Un workflow con selección automática también puede recogerla por su cuenta, y workflowsOptOut: true es lo que declina esa selección automática. Lo único que la saca con garantía es excludedWorkflowDefinitionIds: gana siempre, aunque el resto diga lo contrario.

aiEnabled no es el interruptor del optimizador

Es el consentimiento del titular de la cuenta, y viaja a Amazon como la etiqueta epinium:ai_enabled. Ponerlo a false no saca la campaña de la optimización: para eso está excludedWorkflowDefinitionIds, o quitarla de linkedWorkflowDefinitionIds.

optimizeDate y optimizingSince son de solo lectura -los sella el propio optimizador- y escribir cualquiera de los dos responde con un 400.

POST /v1/campaigns/optimization-config/batch aplica el mismo patch a hasta 1.000 campañas, y no es todo o nada: responde una fila por campaña, en el orden en que las mandaste, y cada una se valida contra su propio estado guardado -un límite obligatorio para un objetivo puede ser opcional para otro-, así que una fila puede fallar sin que las demás se vean afectadas.

Dos códigos que conviene distinguir, igual que al escribir en Amazon: un rechazo de validación -un objetivo fuera de rango, un workflow que no es tuyo- responde 200 con result: "failed" y el motivo en reason. Una campaña que no existe o es de otra cuenta responde 404 en el PATCH individual; en el lote, en cambio, esa misma campaña sale como una fila failed con reason: "not_found", precisamente para que una fila mala no tumbe las otras 999.

RutaQué hace
PATCH /v1/campaigns/{id}/optimization-configCambiar la configuración de optimización de una campaña
POST /v1/campaigns/optimization-config/batchLa misma configuración sobre hasta 1.000 campañas, una fila por resultado

Escribir tareas ​

Con el permiso tasks:write la API crea tareas y decide sobre sus sugerencias, lo mismo que haces en Procesos → Tareas. Es la pieza para que un asistente o una integración proponga cambios y una persona los revise antes de que lleguen a Amazon.

Cuatro cosas que conviene saber antes de la primera llamada:

  • Aprobar no aplica. Son dos pasos: aprobar o rechazar cada sugerencia, y después POST /v1/tasks/{id}/apply. Ahí los cambios de campaña —presupuesto diario, estado y nombre— van a Amazon en el momento, y la respuesta dice cuáles entraron (applied) y cuáles rechazó (failed). Los de producto se encolan (enqueued) y se aplican en segundo plano: para saber si entraron, vuelve a leer las sugerencias y mira appliedAt y applyError.
  • Una sugerencia que nada sabe aplicar es una nota. Hoy se aplican las de producto y las de campaña que llevan fieldPath; las que no lo llevan, y las de ad groups, targets, product ads y términos de búsqueda, se quedan en nota. Aprobarlas deja constancia de la decisión y no cambia nada, y la respuesta lo dice con autoApplySkipped: true. No es un error. Al crear, en cambio, una sugerencia de campaña con un campo que no sea dailyBudget, state o name, o con un valor que no se pueda aplicar, se rechaza con un 400: guardarla sería prometer un cambio que nadie va a hacer.
  • Las sugerencias van con la tarea. Hasta 50 en items al crearla, cada una apuntando a una entidad de tu cuenta; no se añaden después. Una entidad que no existe o es de otra cuenta rechaza la tarea entera, sin crear nada.
  • Resolver una tarea es terminal. Sus sugerencias pendientes no se resuelven con ella: se quedan congeladas y ya no se pueden aprobar. Decide primero las que te importen y cierra la tarea después. Resolverla tampoco reanuda ningún workflow.
RutaQué hace
POST /v1/tasksCrear una tarea, con sus sugerencias
PATCH /v1/tasks/{id}Título, descripción, prioridad y fecha de caducidad
POST /v1/tasks/{id}/resolveResolverla o descartarla
PATCH /v1/task-items/{id} · POST /v1/task-items/batchAprobar o rechazar sugerencias, opcionalmente con tu propio valor en appliedValue
POST /v1/tasks/{id}/applyAplicar lo aprobado
POST /v1/tasks/listing-optimizationsPedir a la IA de Epinium que reescriba fichas, como sugerencias de una tarea - explicado en Reescribir fichas con la IA de Epinium

Como en Amazon, toda escritura exige Idempotency-Key, y el lote de sugerencias no es todo-o-nada: responde una fila por sugerencia y applied cuenta las que quedaron registradas. Crear, editar o resolver una tarea cuesta un cargo fijo por llamada; aprobar o rechazar se cobra por sugerencia registrada. Aplicar no se cobra aparte: cada sugerencia ya se cobró al aprobarla.

Reescribir fichas con la IA de Epinium ​

Con el permiso tasks:write, POST /v1/tasks/listing-optimizations pide a la IA de Epinium que reescriba el título (con sus destacados, los Item Highlights), las viñetas, la descripción y los search terms de entre 1 y 20 productos de tu catálogo. Es la misma generación que la de la aplicación: sigue los clusters de keywords de cada producto, los prompts enlazados a ellos y tu identidad de marca. El resultado no cambia ninguna ficha: queda como sugerencias en una tarea, la del onboarding, para que una persona las revise.

Cinco cosas que conviene saber antes de la primera llamada:

  • Responde en el momento y genera después. La respuesta es un 202 con el id de la tarea (task) y lo que te queda del tope (limit). Cada sugerencia aparece en la tarea cuando está lista: léelas en /v1/task-items filtrando por task.
  • Nada llega a Amazon sin pasar por ti. Apruebas o rechazas cada sugerencia y aplicas la tarea (POST /v1/tasks/{id}/apply), como cualquier otra. Aplicar deja los cambios pendientes de publicar: llegan a Amazon cuando los publicas, desde la aplicación o con POST /v1/pending-listing-changes/publish, que pide catalog:publish.
  • No gasta tus créditos, pero tiene tope. La reescritura la paga Epinium, hasta 20 productos por cuenta en total. Cuenta cada producto de cada llamada, también si vuelves a lanzar uno o si su generación falla. Una llamada que pide más productos de los que te quedan se rechaza entera con un 403 cuyo code es listing_optimization_limit_reached, sin generar nada; limit (cap, used, remaining) dice en cada respuesta cuántos te quedan. Aprobar o rechazar las sugerencias se cobra como en cualquier tarea.
  • Tú eliges productos y campos. products son ids de productos de catálogo, de Seller o de Vendor (/v1/products; los de publicidad no valen). fields admite title, bullets, description y search_terms; sin él se reescriben los cuatro. title reescribe también los destacados.
  • Exige Idempotency-Key. Reutiliza la misma clave al reintentar, o volverías a gastar productos del tope.

Escribir clusters de keywords ​

Con el permiso catalog:write la API crea y edita tus clusters de keywords, los mismos que gestionas en Segmentación → Clusters: un grupo de productos con nombre, las keywords positivas por las que deberían posicionar o anunciarse y las negativas de las que mantenerse lejos. Es la forma de que un asistente que ha encontrado un hueco de keywords lo deje guardado donde lo recogerán los prompts SEO de Epinium, el discovery de keywords del optimizador y el filtro por cluster de los gráficos de producto.

Cuatro cosas que conviene saber antes de la primera llamada:

  • Nada llega a Amazon. Un cluster vive en Epinium. Por eso estas escrituras no dejan fila en /v1/advertising-changes, y por eso tu cliente de IA no te pedirá confirmación para hacerlas.
  • Se edita por deltas, no por sustitución. PATCH /v1/clusters/{id} admite addPositiveKeywords, removePositiveKeywords, addNegativeKeywords, removeNegativeKeywords, addProducts, removeProducts, addPrompts, removePrompts y name; envía solo lo que cambia. Añadir una keyword que ya está actualiza su idioma, su puntuación y su propósito, emparejada por texto; quitar una que no está no hace nada. Un cluster admite hasta 100 keywords positivas y 50 negativas, contadas después del cambio, y una keyword no puede ser positiva y negativa a la vez.
  • Las keywords siguen las reglas de la aplicación. En minúsculas, hasta 80 caracteres, el juego de caracteres de Amazon, sin - ni . al principio ni -, + o . al final; los duplicados se fusionan. language es un código como es-ES o en-GB, epiniumScore va de 1 a 5 y purpose es SEO, PPC o los dos (los dos por defecto).
  • Un cluster protegido se rechaza con 409. Proteger un cluster desde la aplicación es una decisión de una persona, y esta API no puede deshacerla: desprotégelo antes en Segmentación → Clusters. El campo protected de la respuesta te lo dice antes de intentarlo.
RutaQué hace
POST /v1/clustersCrear un cluster, con sus keywords, productos y prompts si ya los tienes
PATCH /v1/clusters/{id}Añadir o quitar keywords, productos y prompts, o renombrarlo
DELETE /v1/clusters/{id}Borrarlo, sin vuelta atrás

Cada prompt que enlaces tiene que ser de tu cuenta, o la llamada se rechaza con un 400 que nombra los ids que sobran. Cada producto que enlaces tiene que ser de tu cuenta — para una agencia, de las conexiones que la cuenta te compartió — y de catálogo (type seller o vendor en /v1/products; los de publicidad se rechazan), o la llamada entera se rechaza con un 400 que nombra los ids que sobran, sin escribir nada. El cluster queda a nombre de la persona detrás de la credencial, así que aparece en la tabla de la aplicación como suyo. Borrar es definitivo - no hay papelera - y se rechaza con un 409 mientras el cluster esté protegido o una smart campaign lo use como cluster base; el error nombra esas smart campaigns, que hay que cambiar o borrar antes. Cada escritura cuesta un cargo fijo por llamada, y el cupo de clusters del plan se aplica aquí igual que en la aplicación.

Escribir prompts personalizados ​

Con el permiso catalog:write la API crea y edita tus prompts personalizados, los de tu biblioteca de prompts: unas instrucciones con nombre que la IA de Epinium sigue al redactar el contenido de tus fichas -tono, estructura, palabras que usar o evitar-. Leerlos solo pide catalog:read, en /v1/prompts, y cada cluster devuelve en prompts los ids de los suyos; con expand[]=prompts los trae enteros.

Cuatro cosas que conviene saber antes de la primera llamada:

  • Un prompt no cambia nada por sí solo. Ni toca Amazon ni reescribe ninguna ficha al guardarse: se aplica cuando se genera el contenido de los productos de los clusters a los que lo enlazas (addPrompts en PATCH /v1/clusters/{id}). Si varios prompts de los clusters de un producto valen para el mismo campo, solo se usa uno, así que deja un prompt por campo.
  • fields dice a qué campos de la ficha se aplica: titleAndHighlights (el título y los destacados, que se redactan juntos), product_description, bullet_point o generic_keyword (los search terms). Sin fields, o con [], vale para todos. Un prompt antiguo puede llevar todavía item_name, el título suelto, que se lee pero ya no se acepta al escribir.
  • La instrucción tiene tope: hasta 2.000 caracteres, los mismos que en la aplicación. El nombre pide al menos 3.
  • Al editar, lo que envías sustituye a lo que había: PATCH /v1/prompts/{id} admite name, instruction y fields, y fields reemplaza la lista entera.
RutaQué hace
POST /v1/promptsCrear un prompt
PATCH /v1/prompts/{id}Renombrarlo o cambiar su instrucción o sus campos

El prompt queda a nombre de la persona detrás de la credencial. Borrar prompts no está disponible por la API. Cada escritura cuesta un cargo fijo por llamada, y el cupo de prompts del plan se aplica aquí igual que en la aplicación: si ya lo has alcanzado, crear responde 403.

Escribir tu identidad de marca ​

Con el permiso catalog:write la API crea y edita tu identidad de marca, la de Configuración → Marca: el nombre de la marca, su sector, sus webs, las de tus competidores, tus observaciones (tono, público, palabras que usar o evitar) y las marcas de tu catálogo que cubre. Es el contexto que usa la IA de Epinium al redactar tus fichas. Leerla solo pide catalog:read, en /v1/brand-identities. No son las marcas de tu catálogo, que están en /v1/product-brands.

Además de las webs sueltas de competitor_urls, cada competidor puede tener su ficha en competitors, hasta 50:

CampoQué es
nameNombre de la marca o del vendedor. Obligatorio
urlSu web o su tienda en Amazon
asinsLos ASIN de sus productos que compiten con los tuyos, hasta 20
threatSu peligrosidad: level (low, medium o high) y reason, el motivo visto en los datos. El nivel nunca va sin su motivo; si aún no hay pruebas, se deja fuera
price_positionSu precio frente al tuyo: below, similar o above

Cuatro cosas que conviene saber antes de la primera llamada:

  • Las fichas de competidor aún no se ven en la aplicación. Se guardan y se leen por la API y el MCP; Configuración → Marca todavía no las enseña.
  • Al editar, una lista sustituye a la que había. PATCH /v1/brand-identities/{id} cambia solo los campos que envías, pero competitors, competitor_urls, brand_urls y product_brand_ids se reemplazan enteras: para añadir un competidor, envía los que ya tenías más el nuevo. Lo anterior no se guarda en ningún sitio.
  • Las fichas no sustituyen a competitor_urls. Son dos listas independientes, y las webs que ya tenías se mantienen. Una identidad guardada antes de que existieran las fichas tiene competitors vacío.
  • Nada llega a Amazon. La identidad de marca vive en Epinium: guardarla no toca ni reescribe tus fichas. Por la API no se puede borrar ni subir su logo.
RutaQué hace
POST /v1/brand-identitiesCrear una identidad de marca
PATCH /v1/brand-identities/{id}Cambiar sus campos o sus listas

Como toda escritura, exige Idempotency-Key.

Cambiar listings desde un fichero ​

Con el permiso catalog:write la API guarda cambios en los atributos de muchas fichas de Amazon a la vez, a partir de un Excel o un CSV: cualquier atributo que Amazon deje editar en el tipo de producto de cada ficha, en Seller y en Vendor. Es lo que usa el MCP de Epinium, donde se explica el flujo completo desde el punto de vista de quien lo pide.

RutaPermisoQué hace
POST /v1/listing-filescatalog:readSube el fichero (.xlsx, .xls o .csv) y devuelve su file_id. Se guarda 7 días
POST /v1/listing-files/rowscatalog:writeGuarda como fichero unas cabeceras y unas filas que ya tienes, sin subir nada
POST /v1/listing-updates/preparecatalog:readEncuentra los productos del fichero por SKU, ASIN o EAN y dice qué atributos admiten
POST /v1/listing-updates/validatecatalog:readValida las filas contra las reglas de Amazon de cada tipo de producto, sin guardar nada
POST /v1/listing-updates/applycatalog:writeGuarda las filas válidas como cambios pendientes de publicar, en segundo plano
GET /v1/listing-updates/apply/{file_id}catalog:readEl estado de ese guardado, lo que se envió y lo que costó

Cinco cosas que conviene saber antes de la primera llamada:

  • Nada llega a Amazon al guardar. apply deja los cambios pendientes de publicar, y salen hacia Amazon cuando alguien los publica desde Publicar cambios en Epinium o con POST /v1/pending-listing-changes/publish (ver Dar de alta productos en Amazon).
  • Los datos que van juntos piden una persona. Un valor que obliga a rellenar otros, como las pilas, se guarda solo si su cascade_id llega en confirmed_cascades; si no, va a una tarea para revisarlo. El resto de la fila se guarda igual.
  • Se cobran 5 créditos por fila. Al aceptar el fichero se reservan 5 por cada fila, con un 402 si el saldo no llega. Al terminar solo se cobran las filas enviadas y el resto se devuelve, entero si falla. Subir, preparar, validar y consultar el estado no se cobran.
  • Los precios van por audiencia. Una columna se declara con offer: { audience, field } (field: price, min, max, sale_price, sale_start o sale_end); clear: true hace que sus celdas vacías borren, y date_order (dmy o mdy) fija el orden de unas fechas ambiguas. validate devuelve en offer_clears las columnas de precio con celdas vacías en productos que tienen ese valor, y las reglas de precio como problemas bloqueantes offer_*. En Vendor no se edita ningún precio: esas columnas llegan en not_applicable con el motivo vendor_price. prepare ofrece los campos de precio en offer_fields.
  • Un fichero se aplica una vez. Repetir la llamada con los mismos ajustes devuelve el estado; con otros ajustes, o con un fichero al que le quedan menos de 24 horas, responde 409. Como toda escritura, exige Idempotency-Key.

Los parámetros de cada ruta están en la referencia de catálogo.

Dar de alta productos en Amazon ​

Con el permiso catalog:write la API guarda altas: productos que todavía no están en tu cuenta de Amazon. Puede ser una oferta sobre un ASIN que ya existe (solo en Seller), un producto nuevo o una familia de variaciones, en Seller y en Vendor. Qué es cada una, qué pide Amazon y cómo se publica una familia está en Altas de productos en Amazon.

RutaPermisoQué hace
GET /v1/amazon-catalog/searchcatalog:readBusca un producto en el catálogo de Amazon por ASIN, EAN, UPC o GTIN, con sus restricciones para tu cuenta
GET /v1/amazon-product-types/searchcatalog:readRecomienda tipos de producto a partir del nombre de un producto nuevo
GET /v1/amazon-shipping-templatescatalog:readLas plantillas de envío de tu cuenta de Seller, para una oferta que envías tú
POST /v1/listing-drafts/validatecatalog:readValida el alta con las reglas de Amazon y con una previsualización de Amazon, sin guardar nada
POST /v1/listing-draftscatalog:writeGuarda el alta como pendiente de publicar
GET /v1/listing-draftscatalog:readTus altas y su estado, con lo que respondió Amazon
DELETE /v1/listing-drafts/{id}catalog:writeDescarta un alta pendiente
GET /v1/pending-listing-changescatalog:readLo que hay pendiente de publicar, como en Publicar cambios
POST /v1/pending-listing-changes/publishcatalog:write y catalog:publishPublica en Amazon los cambios y las altas elegidos, por el mismo camino que el botón Publicar de la app

Cuatro cosas que conviene saber antes de la primera llamada:

  • Guardar no publica. El alta queda pendiente hasta que se publica desde la app o con publish, que exige además catalog:publish y no se puede deshacer.
  • El SKU tiene que ser nuevo en ese marketplace (en Vendor, bajo ese vendor code): uno que ya existe, en Epinium o en Amazon, responde 409.
  • Guardar vuelve a preguntar a Amazon y responde 400, con lo que falta, si Amazon fuera a rechazar el alta: valida primero.
  • Se cobra validar (1 crédito) y guardar (5). Buscar, las plantillas, listar, descartar y publicar no se cobran. Como toda escritura, guardar y publicar exigen Idempotency-Key.

Los parámetros de cada ruta están en la referencia de catálogo.

Escribir el coste de un producto ​

Con el permiso propio costs:write -no catalog:write, que es para clusters, prompts y listings- la API da de alta o actualiza el precio de coste y el coste de envío de un producto: la misma acción que haces en la ficha del producto o al subir la plantilla CSV de costes, con la misma semántica. Para muchos productos a la vez, usa la importación.

RutaQué hace
POST /v1/products/{id}/costsDa de alta o actualiza el precio de coste (price) y el coste de envío (shipping_cost) de un producto

Cuatro cosas que conviene saber antes de la primera llamada:

  • La semántica es la del CSV. Una celda vacía no toca el valor: si solo mandas price, el coste de envío que ya tuviera se queda como estaba. Un 0 lo pone a cero de verdad -no es lo mismo que no mandar el campo. Al menos uno de los dos, price o shipping_cost, es obligatorio.
  • Una fecha pasada recalcula el histórico. date por defecto es hoy; si mandas una fecha anterior, el coste nuevo se aplica desde ahí y el P&L de los periodos ya cerrados que caigan después se recalcula solo. La respuesta dice qué pasó en recalculation: not_needed con fecha de hoy, queued si encoló el recálculo, o failed si no se pudo encolar -el coste se guarda igual, solo que el P&L tardará en reflejarlo.
  • Solo en los planes que incluyen coste de producto. En Free y Guru esta ruta responde 403, igual que el resto de escrituras en esos planes. Como toda escritura, exige Idempotency-Key.
  • Un producto con compras no acepta price. Su coste de producto lo calculan las compras registradas, así que responde 409 con el código COST_FROM_PURCHASES. Para cambiar solo su envío, manda shipping_cost solo, sin price: con los dos, se rechaza todo y el envío no se guarda. Para cambiar su coste de producto, registra o corrige una compra (Registrar las compras de un producto).

Registrar las compras de un producto ​

Cuando un producto tiene compras, su coste de producto es el coste medio de su stock: cada compra lo recalcula con las unidades que tenías y las que compras. Es lo mismo que Registrar compras en la ficha del producto, con el mismo cálculo. Leer pide catalog:read; registrar, corregir y borrar, costs:write. Las dos cosas, solo en los planes que incluyen coste de producto.

RutaQué hace
GET /v1/products/{id}/purchasesLas compras del producto, con el coste medio que dejó cada una
GET /v1/products/{id}/stock-groupCon qué productos comparte stock, o con cuáles se juntaría en su primera compra
GET /v1/purchasesTus compras, por cuenta y por fechas
GET /v1/purchases/{id}Una compra
POST /v1/products/{id}/purchasesRegistra una compra
PATCH /v1/purchases/{id}Corrige una compra: manda solo lo que cambia
DELETE /v1/purchases/{id}Borra una compra
  • El stock compartido tiene un solo coste. En pan-europeo, el mismo SKU en los países de la UE es el mismo stock, así que una compra cambia el coste de todos ellos (UK y Vendor van aparte). El grupo nace con la primera compra; si esos países tienen hoy costes distintos, esa compra pide prior_stock_unit_cost, cuánto valía el stock que ya había, o responde 400 con PRIOR_STOCK_VALUE_REQUIRED.
  • El stock antes de la compra. Sin stock_on_hand se toma el último de Amazon FBA de los 7 días anteriores, más las compras registradas desde entonces. En FBM es obligatorio.
  • El nº de pedido no se repite. Con reference, la misma compra otra vez responde 409 con DUPLICATE_PURCHASE_EXTERNAL_ID en vez de duplicarse.
  • Corregir o borrar recalcula. Cambia el coste medio de esa compra y de las de después, y el P&L de los periodos ya cerrados, como un coste con fecha pasada. Borrar no se deshace; si era la última compra del grupo, vuelven a valer los costes que había antes.
  • Con varias cuentas, leer pide una y escribir todas. Si el stock lo comparten cuentas a las que la clave no llega, puedes leer sus compras pero no tocarlas: 400 con STOCK_GROUP_OUT_OF_SCOPE al registrar, 404 al corregir o borrar.
  • Cada escritura cuesta lo mismo que escribir un coste, y como toda escritura exige Idempotency-Key.

Importar los costes de muchos productos ​

Para cargar el coste de tu catálogo, usa la importación: es la misma que Importar costes desde un fichero en la app, con la misma plantilla y las mismas reglas, y recalcula el P&L una sola vez al final. Con el mismo permiso costs:write.

No lo hagas producto a producto con POST /v1/products/{id}/costs: cada coste con fecha pasada recalcula el P&L de la cuenta entera, y mientras dura la API rechaza los siguientes con 409.

RutaQué hace
POST /v1/cost-imports/filesSube el fichero de costes y devuelve su file_id, sin importar nada. Se guarda 7 días. GET lista los que has subido
POST /v1/cost-imports/previewRevisa la importación sin guardar nada: qué filas se aplicarían, cuáles no y por qué, cuántas van sin fecha, cuántas solo contarán hasta un coste posterior que ya tiene el producto y cuánto costaría
POST /v1/cost-importsImporta los costes de los productos de una cuenta, desde ficheros subidos o desde filas
GET /v1/cost-imports/{id}El estado de la importación: cuántas filas se aplicaron, cuántas no cambiaban nada y cuántas se rechazaron, con el motivo de cada una

Lo que conviene saber:

  • Las filas llegan de dos formas. Con file_ids, los ficheros que subiste con POST /v1/cost-imports/files (.xlsx, .xls o .csv, hasta 8 MB y 200.000 filas por importación: un catálogo entero cabe en un fichero; un Excel con muchas columnas puede no entrar, y entonces se quitan las que sobran o se sube como CSV). Los ficheros subidos para cambios de listings no valen aquí. O con headers y rows, hasta 5.000 filas, si no has subido ningún fichero.
  • Las columnas son las de la plantilla (sellerSku, marketplace, date, cogs, cogsCurrency, shippingCost y shippingCostCurrency) y se reconocen igual que en la app, también con nombres habituales como "sku", "coste" o "fecha". Si alguna no se reconoce, dile de qué cabecera sale cada dato con columns. Cada fila sigue las reglas del fichero de la app.
  • Revísala antes, gratis. POST /v1/cost-imports/preview recibe el mismo cuerpo y aplica las mismas reglas fila a fila, también el cruce con tu catálogo, pero no guarda ni cobra nada. Te dice cuántas filas se aplicarían, cuántas se saltarían (vacías, o con el mismo coste que el producto ya tenía en su fecha: unchanged) y cuántas se rechazarían, con el motivo y ejemplos, cuántas irían sin fecha y cuántos créditos costaría. Solo al aplicar puede rechazarse alguna más, si no hay tipo de cambio para su moneda en su fecha.
  • Una fila sin fecha vale desde hoy. Si tus filas no traen fecha, pasa en date desde cuándo valen los costes: se aplica a las filas sin fecha, y las que la traen se quedan con la suya.
  • Los productos padre de variación se rechazan con parent_product: no venden, así que su coste no cubriría ninguna venta. El coste va en sus variaciones.
  • Es asíncrona. Responde 202 con status: "processing". Consulta GET /v1/cost-imports/{id} hasta que salga finished, finished_with_errors o error; consultarla no cuesta nada. Las filas con una celda más larga de lo que admite la plantilla vuelven en not_sent y no se importan.
  • Queda en el historial de la app, en el Historial de la importación de costes de esa cuenta, igual que si la hubieras subido desde la app.
  • Una cuenta por importación. Mientras el P&L de esa cuenta se está recalculando por un cambio de coste anterior, responde 409 sin importar nada: espera a que termine y vuelve a lanzarla.
  • Cada fila aplicada cuesta lo mismo que escribir el coste de un producto. Al crearla se reservan las filas que pueden aplicarse y, si tu saldo no llega, responde 402 sin importar nada. Al terminar se cobran solo las filas aplicadas y se devuelve el resto: las rechazadas y las que no cambiaban nada no cuestan. Solo en los planes que incluyen coste de producto, y exige Idempotency-Key.
  • También compras. Con kind: "purchases" importa compras con la plantilla de compras de la app (sellerSku, marketplace, date, units, currency, productCost, inboundShippingCost, tariffCost, otherCost, stockOnHand, reference), solo en cuentas Seller. La revisión de compras solo comprueba el formato de cada fila (checks: "format") y ya rechaza las filas mal formadas: el SKU, su grupo de stock y el stock se comprueban al aplicar, así que alguna fila más puede rechazarse entonces. Cada compra aplicada cuesta lo mismo que registrarla suelta.

Escribir gastos propios ​

Tus gastos propios (personal, agencia, 3PL, software…) se leen con catalog:read y se escriben con el mismo permiso costs:write que el coste de producto. Son los mismos que das de alta en Costes y gastos → Gastos propios, y el P&L los resta hasta el beneficio neto.

RutaQué hace
GET /v1/expensesTus gastos, filtrables por basis, status (active, upcoming o ended) y category
GET /v1/expenses/{id}Un gasto, con su histórico de importes por mes
POST /v1/expensesCrea un gasto
POST /v1/expenses/batchCrea hasta 100 gastos de una vez, de una lista o de una hoja subida (file_id), o los comprueba sin crear nada
POST /v1/expenses/filesSube una hoja de gastos y devuelve su file_id, sin crear nada. Se guarda 7 días. GET lista las que has subido
PATCH /v1/expenses/{id}Cambia el concepto o la categoría, o lo finaliza con valid_to (null lo reabre). Finalizarlo borra los cambios de importe programados después, y reabrirlo no los recupera
POST /v1/expenses/{id}/amountsCambia el importe desde un mes; los anteriores conservan el suyo
DELETE /v1/expenses/{id}Lo borra de todo el histórico
GET /v1/expense-categoriesLas categorías estándar y las tuyas
POST, PATCH y DELETE /v1/expense-categoriesCrea, renombra o borra una categoría tuya. Una categoría que usa algún gasto no se puede borrar

basis dice cómo se calcula cada gasto: fixed (un importe fijo, con frequency monthly, quarterly, yearly u once y, en este último, spread_months 1, 3, 6 o 12), per_unit (por unidad vendida neta), pct_net_sales o pct_ad_spend (en puntos: 5 es un 5 %). Los tres variables aceptan scope para aplicarse solo a algunas conexiones o países.

Cinco cosas que conviene saber antes de la primera llamada:

  • Para más de un gasto, el lote. POST /v1/expenses/batch crea hasta 100 de una vez. dry_run es obligatorio: mándalo primero con true, que no escribe nada ni gasta créditos, y después con false. Es todo o nada: si un gasto falla no se crea ninguno, y failure_details dice cuáles y por qué. possible_duplicates avisa de los que se parecen a uno que ya tienes o a otro del mismo lote, sin bloquearlos. Solo se cobran los gastos creados.
  • Una hoja de gastos, por fichero. Súbela con POST /v1/expenses/files (.xlsx, .xls o .csv, hasta 8 MB y 1.000 filas) y manda su file_id al lote: se lee con las mismas reglas que la importación de la app. Si sus columnas no se llaman como las de la plantilla, di de cuál sale cada dato con columns, y pasa en type y currency el tipo y la moneda de las filas que no los traen. Una fila que no se puede leer sale en failure_details como row N, y entonces no se crea nada.
  • El P&L los resta al momento. Los gastos se calculan al leer el P&L, así que un alta, un cambio o un borrado se ve en la siguiente consulta, también en los meses que ya han pasado.
  • Cada token toca los gastos de sus conexiones. Un token que no alcanza todas las conexiones de venta de la cuenta ve y cambia solo los gastos de las suyas, y no puede crear gastos de toda la cuenta (los fijos y los variables sin conexiones en scope) ni renombrar o borrar categorías: responde 403, y en el lote esa fila sale en failure_details. Un gasto que no puede ver responde 404.
  • Solo en los planes que incluyen coste de producto. En Free y Guru estas rutas responden 403, también la de subir el fichero. Todas las escrituras, salvo subir el fichero, exigen Idempotency-Key.

Límites ​

  • Las métricas exigen un rango de fechas. start_date y end_date son obligatorios en todos los recursos de métricas.
  • El rango tiene un máximo, y depende de la granularidad. Con granularity=daily, 93 días; con total o con los periodos de calendario (weekly, monthly, quarterly, yearly), 366. En targets y términos de búsqueda, los recursos más pesados, bajan a 31 y 93. Pedir más devuelve un error diciendo el límite exacto. Ambas fechas entran en el rango.
  • Los listados se paginan de dos formas. Los recursos de catálogo y estructura usan un cursor (starting_after); los de métricas usan limit y offset. En ambos casos, has_more te dice si queda otra página.
  • Hay un límite de peticiones por token. Si lo superas recibes un 429 y basta con reintentar más despacio.
  • También hay un límite de peticiones simultáneas. Un 429 puede significar "demasiadas a la vez", no solo "demasiadas por minuto"; y un 503 significa que el servidor está saturado en ese momento. Los dos traen Retry-After y los dos son transitorios: reintenta con menos peticiones en paralelo.
  • Una respuesta no puede expandir más de 5.000 objetos. expand sobre listas —los productos de un clúster, los países de una conexión— multiplica en cada nivel. Si te pasas recibes un 400 diciendo cuántos objetos habría devuelto: baja el limit, quita algún expand, o pide esos datos a su propio endpoint.

Créditos ​

Las llamadas a esta API consumen créditos de tu cuenta. Cuánto cuesta cada recurso lo puedes ver en la aplicación, en Configuración → Créditos.

Cada respuesta te dice lo que has gastado:

CabeceraQué es
X-Epinium-Credits-CostLo que ha costado esta llamada
X-Epinium-Credits-RemainingLo que te queda. Es aproximado: si tienes otras cosas consumiendo a la vez, puede desviarse
X-Epinium-Credits-BreakdownEl desglose, por recurso y precio unitario: product=100x1,country=100x0
X-Epinium-Credits-MaxLo máximo que podía costar, calculado antes de ejecutarla

Tres cosas que conviene saber:

  • Solo se cobra lo que se entrega. Una llamada que falla no consume nada, y un expand que no devuelve datos —porque tu token no tiene ese permiso, o el dato es de otra cuenta— tampoco.
  • En métricas cuesta también el rango de fechas, no solo las filas. Pedir un año con limit=1 no es barato: además de cada fila devuelta se paga cada día del rango, porque es lo que hay que leer para responder, con un mínimo de 3 días por llamada. Si quieres gastar menos, acorta el rango.
  • Para un total, group_by en vez de paginar. Un total de cuenta son pocas filas —una por moneda—, mientras que paginar el catálogo para sumarlo paga cada producto en cada página. En una cuenta real, el total de ventas de un mes cuesta 157 créditos con group_by=account y unos 17.600 paginando.

Si no te llegan los créditos recibes un 402 antes de ejecutar la llamada: nunca te vas a encontrar con media respuesta. Y no te dice solo que no llega, te dice qué cambiar y a qué valor:

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "message": "insufficient credits: needs up to 366 (campaignMetrics=1x1,campaignMetrics:window=365x1), 120 available. Shorten the date range to 119 days or less.",
    "param": "end_date"
  }
}

El param es el mismo remedio legible por máquina: limit, end_date o include_total. Si viene sin param, no hay ningún parámetro que arregle la llamada y hay que recargar.

Parámetros y respuestas de cada endpoint ​

La tabla anterior dice qué recursos hay. Para ver los parámetros de entrada y la forma exacta de cada respuesta, hay dos caminos:

  • Referencia navegable — cada endpoint con sus parámetros, sus tipos y un ejemplo de respuesta. Se genera desde la propia API, así que no puede quedarse desactualizada. Está en inglés.
  • Esquema OpenAPI — el documento OpenAPI 3.0 en crudo, para importarlo en Postman, Insomnia o un generador de clientes. No necesita token.

Epinium Documentation