Programa de partners: gestiona muchas tiendas

El programa de partners te permite gestionar muchas tiendas de Nembol (una por cada empresa cliente) con una sola clave. Tus clientes nunca inician sesión en Nembol ni reciben emails nuestros: tú lo controlas todo a través de la API, y te facturamos una vez al mes por todos ellos a las tarifas que hayas negociado.

Nembol activa el acceso de partner después de firmar el acuerdo de partner: escribe a developer@nembol.com. A partir de ahí, tu clave necesita el permiso accounts:manage.

Empieza en el sandbox

Tu cuenta de partner empieza en sandbox: hasta 3 empresas abiertas, canales, webhooks y pedidos reales, y no se factura nada. Construye y prueba ahí toda la integración; cuando estés listo, pulsa Pasar a producción en Configuración → Partner (primero una tarjeta, con condiciones de pago con tarjeta): la facturación empieza ese día y la misma clave y las mismas empresas pasan a producción. Consulta Probar tu integración.

Tu clave y el panel

Hay dos páginas del panel que importan, con el propio inicio de sesión de Nembol de la cuenta de partner:

• Configuración → Desarrolladores: crea la clave API. Elige En línea (en sandbox, una clave En línea lo ejecuta todo de verdad y no se factura nada; una clave de Prueba solo simula las llamadas y no puede crear empresas reales). El preajuste Lectura y escritura incluye accounts:manage, necesario para todos los endpoints de partner; el formulario muestra todos los permisos que recibe la clave.
• Configuración → Partner: tus empresas (con un selector Empresas / Facturación), el extracto del mes por plan, tu método de pago y un aviso de Sandbox mientras la cuenta está en sandbox. Muestra los mismos datos que GET /accounts, GET /partner/statement y GET /partner/billing.

Tus comerciantes nunca usan el panel: todo lo de sus empresas pasa por la API.

1. Crear una empresa

curl -X POST https://api.nembol.com/rest/v1/accounts \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Srl", "plan": "pro", "country": "IT", "reference": "ERP-123"}'

{ "id": "acct_66f0a1", "object": "account", "name": "Acme Srl", "plan": "pro",
  "status": "active", "product_limit": 2000, "channel_accounts": 0, "products": 0 }

• plan: basic, pro, enterprise o enterprise_plus. La empresa recibe los límites de ese plan (productos, cuentas de canal, funciones).
• Se factura desde hoy, prorrateado. Sin periodo de prueba. Cambia el plan cuando quieras con PATCH /accounts/{id} (también prorrateado).

2. Trabajar dentro de una empresa

Añade Nembol-Account a cualquier solicitud. El resto de la API funciona exactamente como si la empresa tuviera su propia clave:

curl https://api.nembol.com/rest/v1/products \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Nembol-Account: acct_66f0a1"

Los límites de solicitudes y los Idempotency-Key se cuentan por empresa, así que una empresa muy activa nunca ralentiza a las demás.

3. Conectar los canales de la empresa

Crea un enlace de conexión y envíaselo al vendedor. Solo tiene que iniciar sesión en su cuenta del canal:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Nembol-Account: acct_66f0a1" \
  -H "Content-Type: application/json" \
  -d '{"channel": "amazon", "params": {"country": "US"}, "return_url": "https://erp.example.com/nembol/done"}'

Algunos canales preguntan qué cuenta conectar después de que el vendedor inicie sesión (Amazon con varios marketplaces, Google Merchant Center, Facebook Catalog con varios negocios). La conexión pasa entonces a needs_choice con choices: muéstralas en tu app (o deja que un agente elija) y envía la elección:

curl -X POST https://api.nembol.com/rest/v1/channel_connections/conn_8a12/choose \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Nembol-Account: acct_66f0a1" \
  -H "Content-Type: application/json" \
  -d '{"value": "A2EUQ1WTGCTBG2"}'

Registra tu return_url una sola vez en tu propia tienda (POST /redirect_urls): todas las empresas la usan (GET /redirect_urls dentro de una empresa la muestra con inherited: true).

Tras el inicio de sesión, el navegador del vendedor llega a tu return_url, con estos parámetros añadidos a la query string (los tuyos se conservan, así que pon ahí tu propio id de empresa):

https://erp.example.com/nembol/done?company=42&connection_id=conn_8a12&status=connected&channel_account_id=chac_77b0&account_id=acct_66f0a1

Los enlaces que no se pueden usar también vuelven aquí (caducados, ya usados o rechazados), así que el vendedor siempre termina en tu app, nunca en una página de error de Nembol.

El enlace de retorno solo lleva ids de Nembol, nunca los códigos ni los tokens del canal. El marketplace envía su código de autorización a Nembol, que lo canjea, guarda los tokens y se comunica con el canal por ti. Tú sigues trabajando con tu clave y Nembol-Account.

La query string solo le dice al navegador qué ha pasado: cualquiera puede abrir tu return_url con parámetros inventados. Antes de marcar el canal como conectado en tu app, confirma desde tu servidor con GET /channel_connections/{connection_id} (y Nembol-Account) que status es connected, o espera el webhook channel_account.connected.

Un enlace de conexión funciona una sola vez y durante una hora. Si se abre otra vez o pasada la hora, devuelve al vendedor a tu return_url con error=link_already_used o error=link_expired (sin return_url, el vendedor ve una página de Nembol), así que crea una conexión nueva. Los canales que se conectan con claves API (Kaufland, OnBuy, PrestaShop, Subito) no necesitan enlace: POST /channel_connections con las claves en params responde connected al momento, o channel_credentials_rejected con el motivo del canal.

Después de conectar

• No se importa nada salvo que lo pidas (import_products, import_orders en POST /channel_connections); tu ERP publica sus propios productos.
• ¿Desconectaste una cuenta y vas a conectar otra vez la misma tienda? La siguiente conexión de ese canal la recupera (reconnects_shop); para una tienda distinta, envía new_account: true. Consulta Conectar un canal.
• Todas las opciones de sincronización empiezan desactivadas: activa las que quiera el comerciante con PATCH /channel_accounts/{id} (por ejemplo, sync.quantity_from_orders: true para que una venta en el canal reduzca el stock en todas partes).

4. Webhooks o consulta periódica

Registra tus endpoints una sola vez, en tu propia tienda: reciben los eventos de todas tus empresas, cada uno con account_id.

¿Prefieres consultar periódicamente o quieres una red de seguridad? GET /events?created_after=… con tu clave y sin Nembol-Account devuelve tus propios eventos y los de todas tus empresas en un solo flujo (cada uno con account_id); añade account=acct_… para una sola empresa. Los eventos se conservan 30 días.

Una integración ERP típica

1. Empresa: POST /accounts cuando un cliente se da de alta en tu ERP; guarda el acct_… junto a tu propio id de cliente (reference guarda el tuyo).
2. Canales: POST /channel_connections → envía el enlace → el vendedor vuelve a tu return_url (ver arriba).
3. Productos: busca un producto por SKU (GET /products?sku=…) y después PATCH /products/{id} o POST /products. Cada variante necesita su propio SKU, y los productos con opciones necesitan todas las combinaciones (S/M × Rojo/Azul = 4).
4. Publicar: POST /listings (o /listings/batch para muchos) con la cuenta de canal. Un producto necesita al menos una imagen. Sigue el estado con el webhook listing.status_changed.
5. Stock: POST /inventory/batch con SKU + cantidad (hasta 100 elementos).
6. Pedidos: webhook order.created, con GET /orders como red de seguridad (ver más abajo). Un pedido contiene todas sus líneas.
7. Envío: POST /orders/{id}/fulfillment con el seguimiento.

Las reglas que la integración debe conocer están reunidas en Reglas y límites.

5. Facturación

• Una factura al mes para todas tus empresas: cada una en su plan, a tu tarifa (un descuento sobre nuestro precio de lista o un precio fijo por plan).
• GET /partner/statement?month=2026-10 muestra cada empresa, su plan, los días en que fue facturable y el importe. Coincide con la factura.
• Paga con tarjeta (cargo automático) o mediante factura (30 días). También puedes pagar meses por adelantado (p. ej. por transferencia): el crédito se usa en las siguientes facturas y GET /partner/billing muestra cuánto queda (credit_balance).
• 14 días después de una factura impagada, tus empresas pasan a solo lectura (los pedidos y el stock se siguen sincronizando, no se elimina nada) hasta que se pague.

6. Cerrar una empresa

POST /accounts/{id}/close detiene su facturación hoy. Sus anuncios se quedan en los canales y sus datos se conservan, como con cualquier usuario de Nembol que se va. No se puede volver a abrir.

Cerrar no se puede deshacer, 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 a la persona. 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.

Lo que las empresas no pueden hacer

• /billing en una empresa responde 409 billed_by_partner.
• Las escrituras en una empresa suspendida o cerrada responden 409 account_suspended / account_closed; las lecturas siguen funcionando, así que puedes exportar los productos, pedidos y clientes de una empresa cerrada.
• La cabecera Nembol-Account solo funciona con una clave que tenga accounts:manage. Cualquier otra clave recibe 403 insufficient_scope en toda solicitud que lleve la cabecera, antes de leer nada: no des accounts:manage a una clave de informes o de un solo uso y no podrá acceder a ninguna empresa.
• Crear productos por encima del límite del plan responde 409 product_limit_reached.

Última actualización el 22 de octubre de 2026