Autenticación
Cómo autenticar peticiones usando API keys
Cada petición a la Business API debe incluir una API key válida en el header X-API-Key.
Obtener una API Key
Las API keys se gestionan desde el Dashboard de YaVendio — no existe un endpoint programático para la gestión de keys.
- 1
Navegar a configuración de APIs
Inicia sesión en el Dashboard de YaVendio y ve a Configuración → Claves API.
- 2
Crear una nueva key
Haz clic en "Crear API Key". Asigna un nombre descriptivo (ej. "Integración ERP").
- 3
Copiar tu key
La key completa se muestra solo una vez al momento de crearla. Cópiala y guárdala de forma segura. Después el dashboard solo conserva su prefijo (
yv_live_v1_Xk3Rt9pQz...) para identificarla.
Formato de la Key
Una key tiene la forma yv_live_v1_ seguida de 43 caracteres aleatorios:
yv_live_v1_Xk3Rt9pQzL7mN2vB8cD4fG6hJ1kM5nP0rS9tU3wY7xZEl dashboard crea siempre keys de tipo live. No existe un ambiente sandbox: una key
de prueba operaría sobre los mismos datos productivos, así que no hay una versión "segura"
de la credencial con la que experimentar.
Usar la API Key
Incluye la key en cada petición mediante el header X-API-Key:
curl -H "X-API-Key: yv_live_v1_tu_api_key" \
https://api.ya.onl/v1/ordersAlcances (Scopes)
Una key creada en el dashboard tiene acceso a todos los endpoints salvo la creación de pedidos: se crea sin alcances asignados, y eso le da todos menos orders:write.
El modelo de alcances sí está implementado en la API. Cada endpoint declara el suyo — orders:read, orders:write, products:read, products:write, conversations:read, contacts:read, company:read, webhooks:read, webhooks:write, outbound:send, outbound:read — y la página de referencia de cada uno indica cuál le corresponde.
orders:write permite registrar ventas con POST /v1/orders, y es el único alcance que una key no tiene por defecto: sólo lo tiene la key a la que se le otorgó explícitamente al crearla. Una key a la que le falta el alcance que el endpoint requiere recibe 403 Forbidden:
{
"type": "ForbiddenError",
"detail": "Missing required scope: orders:read"
}Trata cada key como una credencial de acceso total: crea una por integración y elimínala cuando dejes de usarla. Una key con orders:write además registra ventas a nombre de tu tienda: otórgalo sólo a la integración que las envía.
Estados de la Key
Las keys visibles en el dashboard tienen dos estados posibles:
| Estado | Significado |
|---|---|
| Activa | La key es válida y acepta peticiones |
| Revocada | La key fue desactivada y todas las peticiones son rechazadas con 401 |
Información en el Dashboard
La tabla de API keys en el dashboard muestra:
- Nombre — el nombre que asignaste al crear la key
- Alcance — hoy muestra siempre "Órdenes y Productos", porque todas las keys se crean con acceso completo
- Estado — Activa o Revocada
- Secret Key — solo el prefijo (
yv_live_v1_Xk3Rt9pQz...) - Creada — cuándo se creó la key
- Último uso — fecha de la última petición realizada con la key
Para eliminar una key, haz clic en el ícono de papelera junto a ella. Esta acción es irreversible — cualquier integración que use la key comenzará a recibir errores 401 inmediatamente.
Respuestas de Error
| Status | Cuándo |
|---|---|
401 Unauthorized |
API key faltante, inválida, expirada o revocada |
403 Forbidden |
La key es válida pero no tiene el alcance que el endpoint requiere. Con una key del dashboard sólo lo verás en POST /v1/orders, si la key no tiene orders:write |
{
"type": "UnauthorizedError",
"detail": "Invalid or missing API key"
}Buenas Prácticas
Nunca expongas tu API key en código del lado del cliente (JavaScript en el navegador, apps móviles). Siempre llama a la API desde tu backend.
- Usa variables de entorno para almacenar API keys — nunca las escribas directamente en el código fuente.
- Crea keys separadas para cada integración o ambiente (desarrollo, staging, producción).
- Rota las keys periódicamente — elimina la key anterior y crea una nueva desde el dashboard.
