Conectar un canal

POST /channel_connections ejecuta el mismo flujo de conexión que el panel de Nembol, en el siguiente hueco libre para ese canal. Una segunda cuenta de eBay se convierte en una segunda cuenta de canal. Tu clave necesita el scope channels:connect.

Canales OAuth: envía un enlace al comerciante

eBay, Etsy, Shopify, WooCommerce, TikTok Shop, Temu, Amazon, Google Merchant Center, Facebook Catalog, Square, Squarespace, Faire, Wix, Facebook, Pinterest y Tumblr requieren que el comerciante inicie sesión en el canal y apruebe Nembol. Recibes un enlace de un solo uso, válido 1 hora:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "shopify", "params": {"shop": "acme-vintage"},
       "return_url": "https://app.example.com/nembol/callback?user=42"}'

{
  "id": "conn_66f0a1",
  "object": "channel_connection",
  "status": "pending",
  "connect_url": "https://api.nembol.com/rest/v1/connect/…",
  "expires_at": "2026-10-07T16:00:00.000Z"
}

Abre connect_url en el navegador del comerciante. Cuando termina, vuelve a tu return_url con el resultado añadido a la query string:

https://app.example.com/nembol/callback?user=42&connection_id=conn_66f0a1&status=connected&channel_account_id=chac_6aa12cab

Un enlace que no se puede usar también vuelve a tu return_url: caducado (status=expired&error=link_expired), ya usado (el status actual y error=link_already_used) o rechazado (status=failed y el motivo, por ejemplo plan_not_eligible). Muestra tu propio mensaje y crea un enlace nuevo si hace falta. El vendedor nunca ve una página de error de Nembol.

No te fíes solo de la query string. Confírmalo con GET /channel_connections/{id} (connected / failed / expired) o con el webhook channel_account.connected.

Agentes de IA y scripts: omite return_url. El comerciante termina en una página de Nembol que le dice que puede cerrar la pestaña, y el agente consulta la conexión periódicamente.

Registra antes tus URL de retorno

return_url debe empezar por una URL registrada para la tienda. Esto evita que se use el flujo de inicio de sesión de Nembol para enviar a la gente a sitios arbitrarios:

curl -X POST https://api.nembol.com/rest/v1/redirect_urls \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/nembol/callback"}'

Coincide cuando el origen es el mismo y la ruta empieza por la registrada; se admite cualquier query string. El comerciante también puede gestionar la lista en Configuración → Desarrolladores → URL de redirección.

Canales con clave API: conexión inmediata

Kaufland, OnBuy, PrestaShop y Subito se conectan con credenciales, y la respuesta ya es connected o failed:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "kaufland", "params": {"client_key": "…", "secret_key": "…"}}'

Las claves se pasan al canal y nunca se guardan en la conexión.

Canales que preguntan qué cuenta conectar

Amazon, Google Merchant Center y Facebook Catalog se conectan con un enlace, como los demás. Tras el inicio de sesión, el vendedor puede tener varias cuentas entre las que elegir (varias cuentas de Merchant Center, varios negocios). La conexión pasa entonces a needs_choice, su lista choices muestra las opciones, y la completas con POST /channel_connections/{id}/choose y el value elegido. Si hay una sola opción, Nembol la elige y la conexión queda directamente en connected.

Desconectar

curl -X POST https://api.nembol.com/rest/v1/channel_accounts/chac_6aa12cab/disconnect \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Desconectar detiene toda la sincronización con esa cuenta y no se puede deshacer desde la API (para volver a conectar hace falta que el comerciante inicie sesión otra vez), así que primero pide una confirmación:

1. La primera solicitud responde 409 confirmation_required con una descripción de las consecuencias y un confirmation.token.
2. Muestra las consecuencias al comerciante. Si está de acuerdo, repite la misma solicitud con la cabecera Nembol-Confirmation: <token>. El token sirve una sola vez y caduca a los 10 minutos.

Consulta Confirmaciones y deshacer.

Después de conectar: importaciones y opciones de sincronización

A través de la API, una conexión nueva no importa nada: tu app es dueña del catálogo. Pide lo que necesites al crear la conexión:

Los pedidos nuevos se sincronizan desde el momento en que la cuenta se conecta, elijas lo que elijas. (El panel siempre importa ambos: el vendedor quiere ver su tienda enseguida.) También puedes importar más tarde con POST /imports.

Una cuenta recién conectada tiene todas las opciones de sincronización desactivadas: las ediciones de Nembol no llegan al canal y las ventas del canal no cambian el stock en otros sitios hasta que las activas con PATCH /channel_accounts/{id}. Consulta Editar un producto: qué llega a los canales.

eBay: políticas empresariales

Para publicar en eBay, la cuenta debe usar las Business Policies de eBay (cada anuncio lleva políticas de envío, pago y devolución). La mayoría de los vendedores ya las usan. Conectar nunca cambia esto, porque la adhesión cambia la cuenta de eBay del vendedor de forma definitiva. Si la cuenta no está adherida, eBay rechaza la primera publicación; actívalas de forma explícita, con el acuerdo del vendedor:

curl -X POST https://api.nembol.com/rest/v1/channel_accounts/chac_6aa12cab/enable_business_policies \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Pide la confirmación en dos pasos. La respuesta es ready (políticas configuradas, la publicación funciona) o pending (eBay está migrando la cuenta: vuelve a llamar dentro de unos minutos). Una cuenta ya adherida responde ready y no cambia nada.

Desconectar y volver a conectar la misma tienda

Una cuenta desconectada conserva su hueco con el nombre de su última tienda, para que sus anuncios puedan volver a encontrarla. El siguiente POST /channel_connections para ese canal la recupera: la respuesta incluye reconnects_shop (la tienda que tenía), y el vendedor inicia sesión en esa misma tienda.

• Para conectar otra tienda distinta, envía "new_account": true: ocupa un hueco nuevo.
• Si el vendedor inicia sesión en otra tienda sin new_account, la conexión falla con different_channel_account y no cambia nada.

Reconectar un inicio de sesión caducado

El inicio de sesión de un marketplace puede caducar o revocarse (una contraseña cambiada, una app eliminada en el canal). La cuenta muestra entonces errores y deja de sincronizar. Para arreglarlo sin el panel, vuelve a conectar esa misma cuenta:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel_account_id": "chac_6aa12cab",
       "return_url": "https://app.example.com/nembol/callback"}'

Funciona como una conexión nueva (un connect_url para el vendedor y luego return_url), con tres diferencias:

• La cuenta conserva su id (chac_…) y todos los anuncios vinculados a ella; no se crea ninguna cuenta de canal nueva ni hace falta un hueco libre.
• Si el vendedor inicia sesión en una tienda o cuenta distinta de la que se está reconectando, no cambia nada y la conexión falla con different_channel_account.
• channel es opcional; si se envía, debe ser el canal de la cuenta.

Las mismas reglas que el panel

La API ejecuta el propio flujo de conexión del panel, así que se aplican todas las reglas de Nembol. Nada de lo que haga una integración puede ir más allá de lo que el comerciante podría hacer en Nembol:

• Una cuenta de marketplace, una tienda de Nembol. Una cuenta de eBay (Etsy, Shopify…) ya conectada a cualquier tienda de Nembol no se puede volver a conectar; la conexión termina en failed con el mensaje del canal.
• Se requiere una suscripción activa, comprobada igual que en el panel (incluida una comprobación en directo con el proveedor de pago): si no, 402 subscription_inactive.
• La cuenta a través de la que la tienda paga a Nembol (facturación de Shopify, WooCommerce o Wix) no se puede desconectar: 422 channel_not_disconnectable.
• Todo se vuelve a comprobar al abrir el enlace. Si mientras tanto se ocupó el hueco, cambió el plan o caducó la suscripción, el enlace se rechaza y la conexión termina en failed.

Puntos a tener en cuenta

• Un enlace, un uso. Un enlace abierto o caducado no se puede reutilizar. Crea una conexión nueva.
• Inicio de sesión caducado frente a cuenta desconectada. Una cuenta cuyo inicio de sesión caducó sigue existiendo: reconéctala con channel_account_id (conserva su id). Una cuenta que se desconectó vuelve con la siguiente conexión de ese canal (mismo hueco y mismos anuncios, un id chac_ nuevo: el id antiguo responde 404 channel_account_not_found y sus anuncios llevan ahora el nuevo id en channel_account_id); consulta más arriba.
• Etsy, segunda tienda: el comerciante debe cerrar sesión en la primera tienda en etsy.com antes de abrir el enlace, o Etsy volverá a iniciar sesión en la misma tienda.
• Los huecos se llenan. Cada canal tiene un número limitado de cuentas por tienda: 422 channel_slots_full significa que primero hay que desconectar una.
• Se aplican los límites del plan igual que en el panel: 403 plan_channel_not_included cuando el plan no incluye el canal.
• No hay importación automática a través de la API. Una conexión hecha desde el panel inicia la primera importación habitual; una hecha a través de la API importa solo lo que piden import_products / import_orders.

Última actualización el 20 de octubre de 2026