# Generar claves API
## ¿Para qué sirve la API?
Para conectar **sistemas externos** con gestionUltimate vía REST API:
- Integrar tu propia app móvil
- Conectar con sistemas contables externos
- Integrar con e-commerce custom (no Woocommerce ni ML)
- Conectar con CRM externo
- Webhooks bidireccionales
- BI / Data warehouses
## Acceso
Menú lateral → **Configuración → API → Tokens**
## Generar un token de API
**Tokens → Nuevo token**
| Campo | Notas |
|-------|-------|
| **Nombre** | Descriptivo (ej: "App móvil iOS") |
| **Usuario asociado** | El token actúa "como" este usuario (hereda sus permisos) |
| **Scopes** | Qué endpoints puede usar (ver abajo) |
| **Expiración** | 30 días / 90 días / nunca |
| **IPs permitidas** | (opcional) restringir a IPs específicas |
Al crear, el token se muestra **una sola vez**. Guardarlo.
## Scopes (alcances)
Granulares para limitar qué puede hacer:
| Scope | Permite |
|-------|---------|
| `read:products` | Listar y ver productos |
| `write:products` | Crear/modificar productos |
| `read:sales` | Listar ventas |
| `write:sales` | Crear ventas |
| `read:contacts` | Listar clientes/proveedores |
| `write:contacts` | Crear/modificar contactos |
| `read:stock` | Consultar stock |
| `read:reports` | Generar reportes |
| `admin:all` | Acceso total (solo para integraciones internas) |
> ⚠️ Siempre dar el **mínimo de scopes necesarios**. Si una app solo lee productos, no le des `admin:all`.
## Usar el token
Cada request incluye el token en el header:
```
Authorization: Bearer YOUR_TOKEN_HERE
```
Ejemplo cURL:
```bash
curl -X GET https://tudominio.com/api/v1/products \
-H "Authorization: Bearer abc123xyz789"
```
## Endpoints principales
| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/api/v1/products` | GET | Listar productos |
| `/api/v1/products/{id}` | GET | Ver producto |
| `/api/v1/products` | POST | Crear producto |
| `/api/v1/products/{id}` | PUT | Modificar producto |
| `/api/v1/sales` | GET | Listar ventas |
| `/api/v1/sales` | POST | Crear venta |
| `/api/v1/contacts` | GET | Listar contactos |
| `/api/v1/stock/{id}` | GET | Stock por sucursal |
| `/api/v1/reports/sales` | GET | Reporte de ventas |
Documentación completa en: `/api/docs` (Swagger UI).
## Rate limits
Para no saturar el servidor:
- **60 requests/minuto** por token (estándar)
- **300 requests/minuto** para tokens premium
Si superás, devuelve `429 Too Many Requests`. Esperar 60 seg y reintentar.
## Revocar un token
Si sospechás que un token fue comprometido:
**Tokens → fila del token → Acciones → Revocar**
Inmediatamente todas las requests con ese token fallan con `401 Unauthorized`.
## Auditoría
**API → Logs**:
- Cada request loggeada
- Token usado
- IP de origen
- Endpoint llamado
- Status code
- Tiempo de respuesta
Útil para detectar:
- Tokens usados desde IPs raras
- Picos de uso (bug o abuso)
- Errores frecuentes (problema de cliente)