Centro de ayuda

Guías paso a paso de cada parte de Ozom: qué hace cada botón, ejemplos reales y qué hacer si algo sale mal.

API keys de tu empresa

Credenciales para que un sistema externo, un script o un agente de inteligencia artificial hable con tu cuenta sin usar tu usuario y contraseña.

Normalmente entras a Ozom con tu correo y tu contraseña. Eso crea una sesión: el sistema sabe que eres tú, con tu usuario y tu rol. Pero a veces quieres que un programa, un script, o un agente de inteligencia artificial (un programa que puede hacer acciones por su cuenta, como Claude) use tu cuenta sin que haya una persona escribiendo su correo y contraseña cada vez. Para eso existen las API keys.

Una API key (también le puedes decir "llave de API" o "credencial de API") es un código secreto que funciona como una contraseña hecha específicamente para máquinas, no para personas. Cualquier sistema que tenga esa key puede hablar directamente con tu cuenta — sin abrir el panel, sin escribir tu contraseña — usando la API: la vía técnica por la que un programa externo le pide cosas a Ozom (API son las siglas de "interfaz de programación de aplicaciones", pero lo único que importa es que es la forma en que dos programas se comunican entre sí).

Ejemplo: imagina que tienes una tienda de pinturas y usas un programa aparte para llevar tu inventario. Si le das una API key a ese programa, puede consultar tu catálogo de Ozom y mantenerlo actualizado él solo, sin que nadie tenga que copiar productos a mano todos los días.

Cada API key se crea con permisos (en inglés se les llama scopes) que tú eliges al momento de crearla. Un permiso es la autorización para hacer una sola cosa concreta — por ejemplo, "ver el catálogo" es un permiso distinto de "crear pedidos", y ese es distinto de "hacer reembolsos". La key solo puede hacer exactamente lo que esos permisos autorizan. Cualquier otra acción que intente, el sistema la rechaza automáticamente, aunque la key en sí sea válida.

Catálogo: ver o modificar tus productos y precios.
Clientes: ver o modificar los datos de tus clientes.
Cotizaciones: ver o crear cotizaciones.
Pedidos: ver, crear pedidos, o cancelar pedidos (los propios, o cualquiera).
Pagos: ver pagos, hacer reembolsos, o exportar reportes de pagos — son permisos distintos entre sí.
Conversaciones (chat): leer o responder los mensajes de WhatsApp que llegan al agente.
Notificaciones e integraciones: ver o configurar avisos y conexiones con otros sistemas.
Auditoría: ver la bitácora de cambios de la cuenta.
Administración: invitar usuarios, gestionar membresías, o crear y revocar otras API keys — estos son los permisos más delicados, porque le dan a la key control sobre la cuenta misma, no solo sobre el catálogo o las ventas.

Si no sabes qué permisos darle a algo, dale los mínimos que necesita para funcionar y nada más. Por ejemplo, si solo quieres que un sistema lea tu catálogo, no le des permiso de pagos ni de administración aunque "por si acaso" suene más práctico. Así, si esa key algún día se filtra, el daño posible ya queda limitado desde el principio.

Cómo crear una API key

Paso 1: Ve a Admin → API keys, dentro de la administración de tu empresa.
Paso 2: Haz clic en el botón "Nueva API key".
Paso 3: Se abre un panel llamado "Nueva API key" con tres campos que llenar.
Paso 4: En "Nombre" escribe algo que te ayude a identificarla después (por ejemplo "Integración con mi sistema de inventario" o "Bot de WhatsApp"). Tiene un límite de 100 caracteres.
Paso 5: En "Permisos" marca solamente las casillas de lo que esa key va a necesitar hacer, agrupadas por área (catálogo, clientes, pedidos, pagos, etc.).
Paso 6: En "Expira en (días)" decide su vigencia: déjalo vacío si quieres que nunca expire, o escribe un número de días (por ejemplo 90) si quieres que deje de funcionar sola después de ese tiempo.
Paso 7: Haz clic en "Crear API key".

El secreto se muestra una sola vez

Justo después de crearla aparece un aviso que dice "Copia esta key ahora: no se muestra de nuevo", con el secreto completo (empieza con npk_...) y un botón "Copiar". Ese es el único momento en toda la vida de la key en que vas a poder ver el secreto completo. Cópialo de inmediato y guárdalo en un lugar seguro — un gestor de contraseñas, no un chat de WhatsApp ni una nota sin protección. Cuando termines, haz clic en "Ya la guardé" para cerrar el aviso.

Si pierdes el secreto, no hay forma de recuperarlo: por seguridad, Ozom nunca guarda el secreto en texto legible, solo una huella cifrada que le sirve para comprobar que el secreto es correcto, pero no para reconstruirlo. Si lo perdiste, la única opción es revocar esa key (dejarla inválida para siempre) y crear una nueva desde cero.

Después de creada, la key ya no aparece en la lista con su secreto completo — solo con su prefijo (la parte que empieza con npk_ seguida de unos caracteres, suficiente para reconocerla, pero inútil sin el resto del secreto que ya no se muestra).

Columna	Qué significa
Nombre	El nombre que le pusiste al crearla.
Prefijo	La parte visible del secreto (npk_...); nunca el secreto completo.
Permisos	Qué puede hacer esa key.
Creada	Cuándo se generó.
Expira	La fecha en que deja de funcionar, o "Sin vencimiento" si nunca expira.
Último uso	La última vez que se usó para llamar a la API, o "Nunca" si no se ha usado.

Para revocar una key (dejarla inválida de inmediato, por ejemplo porque ya no la usas o crees que se filtró), entra a esa misma lista, busca la key y revócala desde ahí. Cualquier sistema que siga usando ese secreto empieza a recibir errores de inmediato — no hay periodo de gracia.

Ejemplo de un permiso mal calculado: si le das a una key solo permiso de leer el catálogo, y el programa que la usa intenta crear un pedido, el sistema rechaza esa acción con un error de permisos. No importa que la key sea válida — cada acción se revisa por separado contra los permisos que tiene.

Sigue leyendo

Conectar por MCP (Claude u otro agente)

¿No resolviste tu duda? Escríbenos y te ayudamos.

Ir a Soporte hola@tupla.dev