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, 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; y crea, edita y borra productos y contenido en tus tiendas Shopify y WooCommerce conectadas. Tu catálogo de Amazon solo cambia al aplicar una tarea aprobada; el de tus tiendas cambia directamente, sin tarea. 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.

Permiso	Da acceso a
catalog:read	Productos, marcas, países y clusters, con sus métricas: ventas, comisiones de Amazon y margen, devoluciones, stock y, en Vendor, reseñas
campaigns:read	Campañas, carteras, ad groups, targets, product ads y términos de búsqueda
workflows:read	Tus workflows, su configuración y a qué campañas llegan
connections:read	Las conexiones de tu cuenta: Amazon, Shopify y WooCommerce
tasks:read	Tareas de Epinium y sus items
skills:read	El catálogo de playbooks de marketing validados de Epinium
platform:read	Lo 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:write	Crear, editar y borrar clusters de keywords: su nombre, sus keywords positivas y negativas y los productos que agrupan. Nada llega a Amazon
campaigns:write	Crear y modificar campañas, carteras, ad groups, targets y product ads en Amazon, y configurar qué persigue el optimizador en cada una
platform:write	Crear, 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:write	Crear tareas, aprobar o rechazar sus sugerencias, cerrarlas y aplicar lo aprobado
workflows:write	Crear, copiar, editar, encender, pausar, borrar y restaurar workflows, y lanzarlos o simularlos

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

Endpoint	Qué devuelve
/v1/products	Tus productos unificados
/v1/amazon-seller-products	La vista de Seller Central de cada producto, y la categoría de su ranking con expand=salesRanks
/v1/amazon-vendor-products	La vista de Vendor Central, la categoría del ranking con expand=salesRanks y las reseñas con expand=customerFeedback
/v1/amazon-advertising-products	La vista de Advertising
/v1/seller-product-metrics	Ventas, sesiones, Buy Box, rank, comisiones de Amazon, margen, devoluciones, stock, B2B y días de cobertura por producto
/v1/vendor-product-metrics	Ventas de Vendor por producto, con manufacturing y sourcing, devoluciones, sell-in con Amazon, inventario y días de cobertura
/v1/product-brands	Tus marcas
/v1/countries	Países y marketplaces
/v1/clusters	Tus clusters de keywords; con catalog:write también los creas y editas

Publicidad — campaigns:read

Endpoint	Qué devuelve
/v1/campaigns	Tus campañas de Amazon Advertising
/v1/campaign-metrics	Gasto, ventas, ACOS y ROAS por campaña
/v1/portfolios	Tus carteras y el tope de presupuesto que cada una pone a sus campañas
/v1/adgroups	Los ad groups de cada campaña
/v1/adgroup-metrics	Rendimiento por ad group
/v1/targets	Keywords y targets de producto
/v1/target-metrics	Rendimiento por target, con su keyword y tipo de concordancia
/v1/product-ads	El vínculo entre un ad group y el producto que anuncia
/v1/product-ad-metrics	Rendimiento por producto anunciado, con su ASIN
/v1/search-terms	Las búsquedas reales de los compradores
/v1/search-term-metrics	Rendimiento por búsqueda, con el texto y el target que la emparejó
/v1/campaigns/{id}/optimization-history	Qué cambió la automatización en una campaña, con el efecto neto
/v1/advertising-changes	Todo lo que Epinium ha cambiado en Amazon, venga de donde venga

Automatización — workflows:read

Endpoint	Qué devuelve
/v1/workflows	Tus 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}/campaigns	A qué campañas llega de verdad, y por qué entra cada una
/v1/workflows/{id}/performance	El 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

Endpoint	Permiso	Qué devuelve
/v1/connections	connections:read	Tus conexiones: Amazon, Shopify y WooCommerce
POST /v1/platform-request	platform:read, y platform:write para escribir	Una 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:read	La versión de la API de esa plataforma, su referencia y los campos que tiene tu tienda ahora mismo
/v1/tasks	tasks:read	Tareas de Epinium
/v1/task-items	tasks:read	Los items de cada tarea
/v1/skills	skills:read	El 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.

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.

Ruta	Qué hace
POST /v1/campaigns	Crear una campaña
POST /v1/campaigns/full	Campaña + ad group + targets + product ads en una llamada
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batch	Estado, presupuesto diario, nombre y cartera (la cartera, solo en Sponsored Products)
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batch	Crear; estado, puja por defecto y nombre
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batch	Crear 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/batch	Anunciar 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. Y las entidades que gestiona el optimizador se rechazan, porque su ejecución de las 03:00 UTC volvería a escribir encima.

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 product	targetType admitidos
Sponsored Products	KEYWORD, PRODUCT, PRODUCT_CATEGORY
Sponsored Brands	Los de Sponsored Products y THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND o KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES)
Sponsored Display	KEYWORD; 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.

Ruta	Qué hace
PATCH /v1/campaigns/{id}/optimization-config	Cambiar la configuración de optimización de una campaña
POST /v1/campaigns/optimization-config/batch	La 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.

Ruta	Qué hace
POST /v1/tasks	Crear una tarea, con sus sugerencias
PATCH /v1/tasks/{id}	Título, descripción, prioridad y fecha de caducidad
POST /v1/tasks/{id}/resolve	Resolverla o descartarla
PATCH /v1/task-items/{id} · POST /v1/task-items/batch	Aprobar o rechazar sugerencias, opcionalmente con tu propio valor en appliedValue
POST /v1/tasks/{id}/apply	Aplicar lo aprobado

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.

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 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.

Ruta	Qué hace
POST /v1/clusters	Crear un cluster, con sus keywords y productos si ya los tienes
PATCH /v1/clusters/{id}	Añadir o quitar keywords y productos, o renombrarlo
DELETE /v1/clusters/{id}	Borrarlo, sin vuelta atrás

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.

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:

Cabecera	Qué es
X-Epinium-Credits-Cost	Lo que ha costado esta llamada
X-Epinium-Credits-Remaining	Lo que te queda. Es aproximado: si tienes otras cosas consumiendo a la vez, puede desviarse
X-Epinium-Credits-Breakdown	El desglose, por recurso y precio unitario: product=100x1,country=100x0
X-Epinium-Credits-Max	Lo 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:

{
  "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.