API y tokens

La API de Nuvlyx permite que otro sistema, como un bot, un ERP o un script propio, consulte y opere tu tienda sin entrar al panel. Para usarla necesitas un token: una clave que creas en el panel y que solo concede los permisos que tú elijas.

Entra a Integraciones en el menú lateral y abre la pestaña API Tokens.

Nota

La disponibilidad de la API depende de tu plan.

Quién puede crear tokens

Solo el dueño de la tienda (OWNER). La sección Integraciones no aparece para los miembros del staff.

Crear un token

1. Abre el formulario

   Pulsa Crear token. Se abre la ventana Nuevo API Token.

2. Ponle un nombre

   En Nombre escribe algo que te ayude a reconocerlo después, por ejemplo “Bot WhatsApp ventas”. Debe tener entre 2 y 80 caracteres.

3. Elige los permisos

   En Permisos marca al menos uno. Elige solo lo que tu integración necesita: puedes agregar más después sin cambiar el token. Abajo tienes la lista de permisos.

4. Define el vencimiento (opcional)

   En Expira en elige una fecha, como mínimo la de mañana. El token deja de funcionar al terminar ese día. Si dejas el campo vacío, el token no vence.

5. Copia el token

   Pulsa Crear token. En la ventana Token creado aparece el valor completo, con el botón Copiar y un Ejemplo de uso. Guárdalo en un lugar seguro y después pulsa Entendido.

El token se muestra una sola vez

Cuando cierras la ventana Token creado, Nuvlyx no puede volver a mostrarte el token: en la lista solo verás su comienzo (el prefijo). Si lo pierdes, revócalo y crea uno nuevo.

Los permisos

Cada token solo puede hacer lo que le permiten sus permisos. En el formulario cada uno aparece con su código y una descripción:

Permiso	Descripción en el panel
products:read	Leer productos y variaciones
products:write	Crear y actualizar productos
inventory:read	Consultar inventario y stock
inventory:write	Cargar licencias y mover stock
orders:read	Leer pedidos y su estado
orders:write	Crear pedidos en nombre de clientes
customers:read	Leer clientes y sus datos
customers:write	Crear y actualizar clientes
wallet:read	Consultar saldo del monedero
wallet:write	Recargar el monedero de clientes
webhooks:manage	Administrar endpoints de webhooks

Permisos que mueven dinero

Con wallet:write un sistema externo puede acreditar saldo real a tus clientes, y con orders:write puede crear pedidos que se pagan con ese saldo. Dáselos solo a integraciones de tu total confianza.

La lista de tokens

La pestaña muestra todos los tokens de tu tienda con las columnas Nombre (con el prefijo), Permisos, Último uso, Creado y Estado:

• Activo: funciona normalmente.
• Expirado: pasó su fecha de vencimiento y ya no funciona.
• Revocado: lo desactivaste para siempre.

Usa el buscador (“Buscar por nombre o prefijo…”) para encontrar uno. En el celular, los tokens se ven como tarjetas.

Editar un token

En Acciones, pulsa Editar para cambiar el nombre, los permisos o la fecha de vencimiento. El token no cambia, así que tus integraciones siguen funcionando. Si vacías Expira en, quitas el vencimiento. También sirve para darle una fecha nueva a un token Expirado. Pulsa Guardar cambios.

Revocar un token

En Acciones, pulsa Revocar y confirma en la ventana Revocar token. Cualquier integración que lo esté usando deja de funcionar de inmediato, y la acción no se puede deshacer. El token queda en la lista con el estado Revocado.

Buenas prácticas

• Crea un token por integración. Así puedes revocar uno sin afectar a los demás.
• Da solo los permisos necesarios y ponle vencimiento a las integraciones temporales.
• No compartas el token por chat ni lo muestres en capturas. Si crees que se filtró, revócalo y crea otro.

Qué puedes hacer con la API

Con los permisos adecuados, un sistema externo puede:

• Consultar tus productos activos, su detalle y los precios de cada variación (también el precio según el nivel del cliente), y crear productos nuevos, que quedan como borrador.
• Cargar licencias a una variación y consultar el stock.
• Listar pedidos con filtros, ver el detalle de cada uno (con las credenciales, si ya se entregaron) y crear pedidos que se pagan con el saldo del cliente.
• Consultar clientes por su identificador o por su teléfono, en este caso solo los que vincularon su WhatsApp.
• Consultar el saldo de un cliente y acreditarle recargas.
• Administrar webhooks (ver abajo).

La referencia completa, con cada ruta, sus parámetros, los errores y ejemplos, está publicada en nuvlyx.com/api. También la abres desde Ver documentación, en la pestaña API Tokens.

Cada petición lleva el token en el encabezado Authorization, como en el ejemplo que te muestra el panel al crearlo:

curl https://api.nuvlyx.com/api/v1/external/products \
  -H "Authorization: Bearer TU_TOKEN"

Si el token está vencido o revocado, o si le falta el permiso que exige la petición, la API la rechaza con un mensaje que lo explica. Si falta un permiso, agrégalo con Editar.

Webhooks

Un webhook avisa a tu sistema cuando pasa algo en tu tienda. Hoy los webhooks se registran, se consultan y se eliminan solo a través de la API, con un token que tenga el permiso webhooks:manage. No hay una pantalla en el panel para verlos.

Al registrar un webhook, la respuesta incluye su clave secreta una sola vez: guárdala. Los eventos disponibles y el formato de cada aviso están en la referencia de nuvlyx.com/api.

Relación con otras secciones

• Los permisos de los tokens son distintos de los del equipo. Para dar acceso al panel a una persona, usa Staff y permisos.
• Las licencias que cargues por la API aparecen en Inventario, y los pedidos, en Órdenes.
• La mensajería por WhatsApp no usa tokens de API: se conecta en WhatsApp (Mosend).