Conceptos básicos

Cinco objetos explican toda la API.

Producto

El artículo central del catálogo, propiedad de Nembol. Contiene toda la información comercial: título, descripción (el único texto que publica cada canal, se admite HTML; short_description es solo un alias obsoleto de ella), marca, category, etiquetas, mpn, vat_rate, weight/dimensions, images[] (hasta 20) y variants[] (cada una con SKU, precio, msrp (precio tachado en los canales que lo admiten), cantidad, código de barras, grams (peso de envío por variante) e images propias de la variante). Los precios son cadenas decimales en la moneda base de la tienda (GET /store → currency).

Las variantes con options (p. ej. Color/Talla) deben cubrir todas las combinaciones de los valores de las opciones. Los canales generan la matriz completa, así que los conjuntos incompletos se rechazan de entrada en lugar de publicar anuncios defectuosos.

Un producto puede existir en local sin estar en ningún canal, incluso sin imágenes (sigue siendo un borrador local hasta que se publica).

Anuncio

La proyección de un producto en una cuenta de canal. Es un recurso de primer nivel con su propio id (list_…), status (listed, imported, ongoing, error, delisted), id_on_channel, url_on_channel e issues[], que contiene el mensaje de error del propio canal cuando algo falla.

POST   /rest/v1/listings              {product_id, channel_account_id}   # publish
PATCH  /rest/v1/listings/{id}         {}                                 # re-sync
DELETE /rest/v1/listings/{id}                                            # delist

La publicación es idempotente para cada par (product_id, channel_account_id), y GET /listings?status=error es la consulta que debe ejecutar tu lógica de reintentos.

Dos comportamientos del lado del canal que conviene conocer: algunos vendedores configuran reglas de precio por canal (un ajuste porcentual o fijo), así que el precio en el canal puede diferir legítimamente del precio del producto; y en WooCommerce el vendedor puede haber elegido crear los productos como borradores, en cuyo caso un anuncio listed existe en la tienda pero su URL todavía no es pública.

Cuenta de canal

Una cuenta conectada en una plataforma de venta. GET /channel_accounts las lista con ids estables y opacos (chac_…). Si un vendedor tiene dos cuentas de eBay, cada una es su propia cuenta de canal, y un id nunca apunta a otra cuenta. El id se conserva cuando se reconecta un inicio de sesión caducado (channel_account_id). Desconectar la elimina: volver a conectar esa cuenta le da un id nuevo, el antiguo responde 404 channel_account_not_found, y los anuncios que tenía pasan a llevar el id nuevo en channel_account_id (los anuncios pertenecen a la posición de la cuenta, no al id). Guarda los ids, y con channel_account.connected vuelve a leer GET /channel_accounts y tus anuncios. El campo channel contiene la plataforma base (shopify, amazon, ebay, etsy, woocommerce, tiktok, …). Aparecen otras nuevas a medida que Nembol añade integraciones, así que acepta valores desconocidos.

Pedido

Un pedido normalizado recibido de cualquier canal: currency por pedido, status y fulfillment_status normalizados, seguimiento, líneas de pedido y datos del comprador, incluida la dirección de envío completa (con el scope orders:read). Con orders:write, POST /orders/{id}/fulfillment lo marca como enviado, añade el seguimiento y (por defecto, cuando hay seguimiento) avisa al marketplace de origen.

Operación

El seguimiento del trabajo asíncrono en los canales. Lo clave que debes entender sobre las escrituras en Nembol:

1. La escritura local es síncrona. POST/PATCH devuelven el recurso actualizado al instante, así que lo que escribes es lo que recibes.
2. La propagación a los canales es asíncrona. Pasa por los workers de canal de Nembol, que respetan los rate limits de cada canal. El bloque sync de la respuesta te da un operation_id; GET /operations/{id} informa de los results[] por canal (succeeded, failed, channel_rate_limited, simulated), y una operación puede terminar en partial.

En lugar de consultar las operaciones periódicamente, suscríbete al webhook operation.completed.

Cómo funciona la sincronización

• Las escrituras desde la API se ponen en cola detrás de las actualizaciones generadas por pedidos y de las acciones del panel, así que una integración nunca puede bloquear la sincronización de pedidos.
• Cuando un canal limita las peticiones, Nembol espera y reintenta; mientras tanto la operación muestra channel_rate_limited.
• Eliminar un producto nunca toca los canales: mientras siga publicado en alguno, DELETE /products/{id} responde 422 product_still_listed, así que retira primero cada anuncio (si una retirada sigue en curso responde 409 listing_operation_in_progress: espera a que termine y luego elimina). Un producto eliminado se puede recuperar con POST /products/{id}/restore; sus fotos se conservan durante 30 días, después vuelve sin ellas. Consulta Retira y limpia.

Última actualización el 22 de octubre de 2026