# API pública de Ventix

URL: https://ventix.smartbusiness.site/manual/api

La API pública conecta otros sistemas con Ventix: tu tienda en línea, un ERP, un CRM o una automatización. Cubre
facturación, inventario, clientes, compras, contabilidad, reportes y la tienda en línea. Este artículo es para la persona
que programa la conexión; si solo necesitas crear la clave, ve a
[Crear API Keys para tu tienda en línea o tus integraciones](https://ventix.smartbusiness.site/manual/administracion/api-keys-para-tu-tienda).

## Antes de empezar

- La API pública es del plan **Enterprise**. Puedes probarla en los
  [30 días de prueba de Enterprise](https://ventix.smartbusiness.site/manual/administracion/prueba-enterprise-30-dias).
- Solo un usuario **Administrador** crea las API keys.

## Crear la API key

1. Abre **Configuraciones Globales → API Keys** y pulsa **Nueva API Key**.
2. Escribe un **Nombre** que diga dónde la usarás, por ejemplo «ERP».
3. Marca los permisos que necesita ese sistema, módulo por módulo. Qué deja ver cada uno:
   [Elegir los permisos](https://ventix.smartbusiness.site/manual/asistentes-de-ia/elegir-los-permisos).
4. Pulsa **Crear API Key** y copia la clave: Ventix solo la muestra una vez.

El paso a paso con capturas está en
[Crear API Keys para tu tienda en línea o tus integraciones](https://ventix.smartbusiness.site/manual/administracion/api-keys-para-tu-tienda).

> **Importante:** la clave actúa con los roles del usuario que la crea. Si ese usuario no puede hacer algo en Ventix, la
> clave tampoco, aunque tenga el permiso. Y si el usuario se desactiva, la clave deja de funcionar.

## Hacer tu primera llamada

- **URL base:** `https://ventix-api.smartbusiness.site/api/public/v1`
- **Autenticación:** la clave va en el encabezado `X-API-Key` de cada llamada.

Este ejemplo lista los primeros 10 productos. Necesita el permiso **Inventario – Lectura**. Cambia `TU_API_KEY` por tu
clave:

```bash
curl -H "X-API-Key: TU_API_KEY" \
  "https://ventix-api.smartbusiness.site/api/public/v1/integration/Products?pageNumber=1&pageSize=10"
```

La respuesta es JSON. Si algo falla, el código de la respuesta te dice por qué:

| Código | Qué significa | Qué hacer |
| --- | --- | --- |
| 401 | Falta la clave, no es válida o fue revocada. | Revisa el encabezado `X-API-Key` o crea una clave nueva. |
| 403 | La clave no tiene el permiso de esa operación, o el plan de la empresa no la incluye. | Crea una clave con el permiso que falta; los permisos no se cambian después. |
| 429 | Pasaste el límite de llamadas por minuto. | Espera el tiempo que indica el encabezado `Retry-After` y vuelve a intentar. |

## Referencia completa

- **Todas las operaciones**, con sus parámetros y respuestas, están en
  [https://ventix-api.smartbusiness.site/swagger](https://ventix-api.smartbusiness.site/swagger). En **Authorize** pegas
  tu clave y pruebas las llamadas desde el navegador.
- **Guía técnica** para programadores, con ejemplos por módulo:
  [https://app.smartbusiness.site/docs/api](https://app.smartbusiness.site/docs/api).
- **Si programas con un asistente de IA**, dale este contexto:
  [https://app.smartbusiness.site/llms/ventix-public-api.md](https://app.smartbusiness.site/llms/ventix-public-api.md).
  Para conectar el asistente a tu empresa, no para programar, usa
  [Conectar con una API key](https://ventix.smartbusiness.site/manual/asistentes-de-ia/conectar-con-una-api-key).

## Cuidar la clave

- La API key es como una contraseña: no la pegues en chats, correos ni capturas, y no la subas a repositorios. Guárdala
  en un gestor de secretos o en una variable de entorno del servidor.
- Una clave con permisos se usa desde tu servidor, nunca desde el navegador ni desde una app: ahí cualquiera puede
  leerla. La única que va en la página de tu tienda en línea es la clave sin permisos (**Solo tienda online**).
- Marca solo los permisos que ese sistema necesita, y usa una clave por sistema: así puedes revocar una sin afectar a
  las demás.
- Si se filtra, revócala de inmediato en **Configuraciones Globales → API Keys** y crea otra. La revocación es
  inmediata. Ver [Revocar una clave](https://ventix.smartbusiness.site/manual/administracion/api-keys-para-tu-tienda#revocar-una-clave).