Tu integración envía una actualización de precio o inventario, recibe ACCEPTED y marca el trabajo como completado. Después, un vendedor informa de que el listing sigue sin poder comprarse. El paso que falta es conciliar el envío con una observación posterior del listing.
Amazon distingue entre la aceptación para procesamiento y los problemas de procesamiento posteriores. Su respuesta de escritura no puede informar de problemas que surjan después; una lectura posterior con getListingsItem sí puede exponerlos. Conserva el acuse de recibo, pero no lo uses como prueba de que se ha alcanzado el estado activo previsto. La descripción general de Listings Items de Amazon explica este límite.
Este runbook está pensado para una integración autorizada que comprueba un SKU independiente o un SKU hijo vendible de su propio vendedor en un único marketplace de Amazon. El ejemplo de inventario usa gestión logística por el vendedor y el canal DEFAULT. No concilia stock de FBA, ofertas de competidores ni la Oferta Destacada. Un padre de variación es deliberadamente no comprable, así que exclúyelo de una alerta que espere un artículo comprable. La guía de flujos de trabajo de Amazon documenta esa excepción.
Conserva cuatro registros en lugar de un único indicador de éxito
Usa esta estructura de registros propuesta para que cada conclusión sea inspeccionable:
| Registro | Qué conservar | Qué puede establecer |
|---|---|---|
| Estado de negocio previsto | Vendedor, SKU, marketplace, revisión interna, precio/moneda previstos, intención de inventario y estado de venta | Lo que tu negocio pretendía cambiar |
| Acuse del envío | Hora de la petición, operación, estado de la respuesta, identificador del envío y problemas devueltos | Si Amazon aceptó inicialmente ese envío |
| Contribución del vendedor | Datos de attributes solicitados en una lectura posterior, con su hora de recogida | Los últimos atributos aportados que devuelve Amazon |
| Estado observado del listing | Resumen, ofertas, disponibilidad de gestión logística y problemas de esa lectura, dentro del alcance solicitado | Lo que esos conjuntos de datos devueltos informan sobre el listing |
Son registros separados, no una transacción atómica. Guarda la respuesta y la hora de recogida para que un revisor posterior pueda distinguir una comparación de campos de una suposición sobre el orden de procesamiento.
Amazon indica que attributes representa los últimos datos proporcionados por el vendedor, mientras que secciones como fulfillmentAvailability representan datos activos del listing. Esas cantidades pueden diferir legítimamente tras una venta. Comparar el inventario enviado con el inventario activo como si siempre tuvieran que ser iguales crea una señal de reparación falsa. Las consideraciones de Listings Items dan ese ejemplo concreto.
Solicita los conjuntos de datos que pretendes verificar
getListingsItem devuelve summaries por defecto. Una petición correcta que omitió offers no ha comprobado el precio activo de la oferta. Selecciona explícitamente los conjuntos de datos necesarios para esta investigación. La referencia de la operación enumera los parámetros y los valores por defecto.
Esta es la forma de la petición para un cliente SP-API autorizado ya existente, no un comando autenticado completo:
GET /listings/2021-08-01/items/{sellerId}/{sku}
marketplaceIds={marketplaceId}
includedData=summaries,attributes,issues,offers,fulfillmentAvailabilityUsa el endpoint regional y el contexto de vendedor autorizado ya configurados en tu cliente, codifica el SKU como componente de la ruta y envía las dos últimas líneas como parámetros de consulta. Inspeccionamos deliberadamente un solo marketplace por investigación para simplificar la atribución.
Haz coincidir el SKU devuelto y el resumen del marketplace objetivo. Para la comprobación de precio, selecciona una oferta de ese marketplace, el tipo de oferta B2C o B2B previsto, la audiencia aplicable si existe y la moneda esperada. Si la oferta prevista no puede seleccionarse sin ambigüedad, deja la comprobación de precio sin resolver. Compara los importes monetarios como decimales y no como aproximaciones en coma flotante.
Para este ejemplo gestionado por el vendedor, inspecciona el canal de gestión logística DEFAULT, que Amazon define como gestión logística estándar por el vendedor en su guía de gestión logística. No lo sustituyas por otro canal ni trates una cantidad ausente como cero. El modelo de respuesta oficial hace opcionales varios conjuntos de datos y no exige una cantidad de gestión logística. En este runbook, los datos ausentes son un resultado distinto.
Convierte cada observación en una siguiente acción concreta
La siguiente matriz es una política operativa derivada de esa semántica de respuesta. No es una garantía de finalización por parte de Amazon.
| Observación | Conclusión permitida | Siguiente acción |
|---|---|---|
El envío está ACCEPTED; sin lectura posterior | Aceptado, resultado activo sin verificar | Programa una lectura con alcance definido; conserva el acuse |
| La lectura falla con un error de autorización, de limitación (throttling) o de servicio | El estado actual del listing es desconocido | Resuelve el fallo de lectura; mantenlo separado del estado del listing |
| La respuesta correcta carece de un conjunto de datos requerido o de una oferta coincidente | Esa comprobación es desconocida | Confirma los conjuntos de datos solicitados y el alcance; no rellenes los valores ausentes con cero ni false |
El resumen objetivo válido carece de BUYABLE, para un SKU que se espera vender | El estado devuelto es no comprable | Inspecciona los problemas solicitados y la disponibilidad de gestión logística; comprueba si hubo un cierre intencionado y la intención de inventario |
| El conjunto de datos de problemas está vacío | No se informa de problemas en ese conjunto de datos | Comprueba la comprabilidad de forma independiente; no la infieras de una lista vacía |
| Se informa de problemas para el listing objetivo | Esos problemas informados necesitan diagnóstico | Inspecciona código, gravedad, atributos relevantes y detalles de marketplace/aplicación cuando se proporcionen; investiga cada problema aplicable mientras compruebas la comprabilidad de forma independiente |
| La oferta devuelta coincide con el precio y la moneda previstos | Esta oferta observada coincide | Registra la coincidencia; evalúa inventario y comprabilidad por separado |
| La oferta seleccionada sin ambigüedad tiene la moneda esperada pero un precio distinto | Discrepancia de precio observada; requiere atención | Conserva los valores esperado/observado, verifica la última revisión de negocio y otras escrituras, y luego continúa la conciliación acotada o escala; no reenvíes a ciegas |
| El inventario aportado difiere del inventario activo | Se devolvieron dos tipos de cantidad distintos | Consulta la autoridad de inventario actual y los cambios intermedios antes de cualquier escritura |
BUYABLE y DISCOVERABLE describen estados distintos. Un array de estado válido sin BUYABLE es diferente de un resumen ausente o de una lectura fallida. Amazon también indica que la ausencia de problemas definidos puede coexistir con otros problemas del listing. Las definiciones de notificaciones de estado y problemas describen estas distinciones; la guía de recuperación relaciona el diagnóstico de no comprable con los problemas y el inventario.
Gestiona los fallos HTTP en la capa de peticiones. La referencia distingue los fallos de autorización 403, la limitación 429 y los errores de servicio 500/503. Un 404 requiere investigar el listing y el alcance de la petición; no significa una cantidad de inventario verificada de cero. Usa reintentos de lectura acotados cuando corresponda, dentro del plan de uso actual de la API, sin convertir cada lectura fallida en una nueva escritura del listing. Las respuestas de getListingsItem proporcionan las categorías de error.
Analiza una discrepancia de cantidad antes de repararla
Considera una traza totalmente ilustrativa, no una prueba con un vendedor real. La actualización prevista es un precio B2C de USD 24.90 y cinco unidades gestionadas por el vendedor para un SKU vendible. El envío se acepta. Una lectura posterior, con el alcance correcto, informa de:
| Campo | Observación ilustrativa | Interpretación |
|---|---|---|
Inventario enviado en attributes | 5 | Última contribución devuelta |
Cantidad activa en DEFAULT | 4 | Cuatro unidades informadas como disponibles en ese canal |
| Oferta seleccionada | USD 24.90 | El precio observado coincide con el importe y la moneda previstos |
| Estado del resumen | BUYABLE, DISCOVERABLE | Se informan ambos estados para este listing |
| Problemas solicitados | Array vacío | No se informa de ningún problema ahí |
La diferencia de inventario por sí sola no demuestra que la actualización fallara. Una venta es una explicación posible, pero esta respuesta no establece la causa. Concilia con el sistema de inventario y con los pedidos o escrituras intermedios antes de decidir si hace falta una corrección. Restaurar cinco unidades a ciegas podría deshacer un cambio legítimo de inventario.
El atajo contrario también falla: el precio coincidente no demuestra que este envío concreto causara el valor observado. Otro escritor podría haber proporcionado el mismo importe. Registra una coincidencia observada, conserva la revisión interna y el acuse, y no afirmes la causalidad.
Si esta lectura hubiera solicitado solo summaries, la comprabilidad podría ser observable mientras las comprobaciones de precio y cantidad seguirían siendo desconocidas. Conserva ese resultado parcial en lugar de elevar todo el trabajo a éxito.
Acota la investigación y mantén útiles las notificaciones tardías
Mantén un registro de conciliación por vendedor, SKU, marketplace y revisión interna. Da a cada comprobación requerida su propio estado: pendiente, coincidencia observada, requiere atención o desconocido. Una revisión de negocio más reciente debe reemplazar a un objetivo más antiguo, en lugar de ser sobrescrita por el reintento de ese trabajo antiguo.
Elige una programación de reintentos, un número máximo de intentos y un plazo de investigación adecuados a tu riesgo de inventario y a tu asignación de API. Son decisiones operativas tuyas; este runbook no proporciona ningún retraso universal tras el cual una actualización aceptada deba estar activa. Al vencer el plazo, escala las comprobaciones sin resolver con el acuse conservado, el alcance, las horas de recogida y los campos de respuesta relevantes.
Usa las notificaciones de estado o de problemas aplicables para programar otra lectura con alcance definido, y usa un barrido de conciliación acotado para los trabajos que sigan pendientes. Conserva la identidad y la hora de la notificación para el diagnóstico. Una notificación tardía debe motivar una investigación sin reemplazar una observación más reciente solo porque llegó la última. Las preguntas frecuentes de las Listings APIs de Amazon reconocen que las notificaciones pueden ir por detrás de las lecturas directas.
El lastUpdatedDate del resumen es una marca de tiempo de actualización del listing. El modelo no lo define como una marca de tiempo de referencia independiente para cada campo de precio o inventario. No lo trates como prueba de que todas las secciones devueltas describen un único estado atómico ni de que tu envío se ha aplicado por completo.
Mantén la resolución de problemas de transporte separada de las decisiones sobre el listing
Cambiar de proxy no puede resolver un problema de catálogo solo porque la petición ahora se complete. Si una petición falla antes de que llegue una respuesta útil, diagnostica la conexión con la guía de tiempos de espera de proxy. Una vez que llegue una respuesta válida del listing, usa sus campos con alcance definido y tu intención de negocio para decidir la siguiente acción.
Para un flujo de trabajo distinto de recopilación de páginas públicas, comprobar si un HTTP 200 de Amazon contiene la página prevista aborda una pregunta diferente. Este flujo de conciliación del vendedor usa datos autorizados de la SP-API y no infiere el estado del listing a partir de una tienda obtenida por scraping.
Este artículo y su matriz de decisión se prepararon con asistencia de IA a partir de la documentación primaria de Amazon consultada el 12 de septiembre de 2026, y después se revisaron de forma independiente. El ejemplo es ilustrativo; no se consultó ninguna cuenta de vendedor ni se modificó ningún listing. La matriz es un método operativo propuesto, no un resultado de recuperación medido.
Únete a la lista de espera de ipvolt para recibir una única notificación cuando se abra el acceso a los proxies. El acceso todavía no está abierto. Un correo cuando se abra el acceso. Nada más.