Autenticación y claves de API
Cómo crear una clave de API en el panel, el formato vk_live_…, los alcances de lectura y escritura, cómo enviar la clave en cada solicitud, cómo revocarla, cómo probar sin modo de prueba y qué significa cada error 401 y 403.
Toda solicitud a la API lleva una clave de API de la tienda. La clave identifica la tienda y dice qué puede hacer la solicitud. No hay usuario, contraseña ni sesión: quien tiene la clave tiene el acceso.
Antes de empezar
- Rol Admin o Dueño en la tienda.
- La API activa para la tienda (viene activa por defecto). Consulta más abajo.
Crear una clave
- Abre GeneralConfiguración › Desarrolladores.
- Crea una clave nueva. Dale un nombre que diga dónde se va a usar, como "ERP" o "Servidor de producción", y elige los alcances.
- Copia el valor completo,
vk_live_…. Aparece una sola vez. Después, el panel muestra solo los últimos cuatro caracteres.
Cada clave queda fijada a una versión de la API, la versión actual del día en que fue creada. Consulta Versión.
El paso a paso con lo que muestra el panel está en Desarrolladores: claves y registros.
Formato de la clave
vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh| Parte | Tamaño | Para qué sirve |
|---|---|---|
vk_live_ | 8 | Prefijo fijo. Distingue una clave de Vipter de una sk_live_ de Stripe en el mismo .env. |
| Identificador | 12 caracteres | Localiza la clave. No es secreto. |
| Secreto | 32 caracteres | La parte que prueba la posesión. Vipter guarda solo un hash de ella. |
Letras y números, sin otros caracteres. Cualquier clave con otro formato se rechaza con 401 invalid_api_key antes de consultar la base de datos.
Solo existe el prefijo live. Vipter no tiene modo de prueba; consulta Probar sin modo de prueba.
Alcances
| Alcance | Qué habilita | Métodos |
|---|---|---|
read | Consultar cuenta, clientes, suscripciones, pedidos, ofertas y productos. | GET |
write | Crear y modificar datos: sesiones de checkout, clientes y sesiones del portal del cliente. | POST, DELETE |
Una clave puede tener uno o los dos alcances. Una solicitud a un endpoint sin el alcance necesario recibe 403 insufficient_scope. Para una integración que solo lee datos, crea la clave solo con read.
Usar la clave
Envía la clave en el encabezado Authorization, como un token Bearer:
curl https://api.vipter.com/v1/account \
-H "Authorization: Bearer vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh"La API también acepta HTTP Basic con la clave como usuario y contraseña vacía, la misma costumbre de los ejemplos de Stripe con -u. Las dos formas son equivalentes:
curl https://api.vipter.com/v1/account \
-u vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh:Los dos puntos al final le dicen a curl que la contraseña está vacía. Sin ellos, curl pide la contraseña en la terminal.
La clave vale para https://api.vipter.com/v1 y para https://app.vipter.com/api/v1; consulta Dirección base.
Guardar la clave
- Guarda la clave en una variable de entorno o en una bóveda de secretos. Nunca en el código fuente, en un repositorio ni en una página servida al navegador.
- Usa una clave por sistema y por entorno. Si una se filtra, revocas solo esa.
- La API no acepta llamadas desde el navegador con la clave: cualquiera que abra la página tendría la clave. Llama a la API desde tu servidor.
- Si una clave apareció en un lugar público, revócala de inmediato y crea otra. Vipter no puede recuperar el valor de una clave: solo queda guardado el hash del secreto.
Revocar una clave
En la lista de claves, usa la acción de revocar. La clave deja de funcionar al instante: la siguiente solicitud con ella recibe 401 api_key_revoked. No se puede deshacer. Para cambiar una clave sin detener la integración, crea la nueva, publica, confirma en la columna de último uso que la antigua dejó de usarse y recién entonces revoca la antigua.
Las claves revocadas siguen en la lista, para el historial. Los registros de solicitudes muestran qué clave hizo cada llamada.
La API viene activa para toda tienda
No hay nada que solicitar: toda tienda activa responde a la API en cuanto tiene una clave. Vipter puede apagar la API de una tienda concreta, por abuso o por una pendencia en la cuenta. En ese caso la pestaña Desarrolladores avisa y toda solicitud, incluso con una clave válida, recibe 403 api_not_enabled. Para reactivarla, habla con el soporte de Vipter e indica el nombre de la tienda. Las claves existentes vuelven a funcionar en cuanto la API se enciende de nuevo.
La API también responde solo para tiendas activas. Una tienda suspendida o en otro estado recibe 403 project_inactive.
Probar sin modo de prueba
Vipter no tiene claves de prueba ni un entorno separado. La prueba ocurre en la misma tienda, con una conexión de prueba del proveedor de pagos:
- En PagosProveedores, crea una conexión con Conexión de prueba activado. Usa el entorno de pruebas del proveedor y no le cobra a nadie de verdad.
- Haz una compra por el checkout con esa conexión. Consulta Probar tu tienda.
- Consulta el pedido por la API. Un pedido que pasó por una conexión de prueba viene con
"livemode": false. Clientes, suscripciones, ofertas y productos no tienen conexión, así que vienen con"livemode": true.
Como la prueba ocurre en la tienda real, los pedidos de prueba aparecen en el panel y en los informes junto con los de verdad. Usa el campo livemode para separarlos en tu sistema.
Errores de autenticación
Todos vienen en el formato estándar de error. Un 401 es sobre la clave; un 403 es sobre lo que la clave puede hacer o sobre la tienda.
| HTTP | type | code | Causa | Qué hacer |
|---|---|---|---|---|
| 401 | authentication_error | api_key_missing | La solicitud no trajo Authorization, o lo trajo en un formato que no es Bearer ni Basic. | Envía Authorization: Bearer vk_live_…. |
| 401 | authentication_error | invalid_api_key | La clave no existe, el secreto está mal, el formato está mal o la tienda fue eliminada. El mensaje es el mismo en todos esos casos, a propósito. | Revisa que copiaste la clave entera, sin espacios. Si hace falta, crea otra. |
| 401 | authentication_error | api_key_revoked | La clave fue revocada en el panel. | Crea una clave nueva. |
| 401 | authentication_error | api_key_expired | La clave pasó su fecha de vencimiento. | Crea una clave nueva. |
| 403 | permission_error | api_not_enabled | La API fue desactivada para la tienda. | Pide la reactivación al soporte. |
| 403 | permission_error | project_inactive | La tienda no está activa. | Regulariza la tienda en el panel. |
| 403 | permission_error | insufficient_scope | La clave no tiene el alcance que exige el endpoint. | Crea una clave con el alcance correcto. |
Las solicitudes sin clave válida se limitan por dirección IP, a 10 por minuto. Pasado eso, la respuesta es 429 rate_limit hasta que la ventana se libere. Esto protege contra intentos de adivinar claves y no afecta a las llamadas autenticadas, que tienen su propio límite.
Qué hacer después
- Lee las convenciones de la API: formato, errores, paginación y límites.
- Haz la primera llamada y consulta cada objeto en la referencia de la API.
Visión general para desarrolladores
Lo que puedes integrar con Vipter hoy (API REST con sesiones de checkout, cobros y acciones en la suscripción, uso medido, eventos y endpoints de webhook; webhooks firmados en dos catálogos; parámetros de URL del checkout; el script de UTMs; y esta documentación en Markdown), lo que viene después y por dónde empezar.
Convenciones de la API
La dirección base, el encabezado de versión, el formato de solicitud y respuesta, cómo se representan dinero, fechas e IDs, la tabla de errores, idempotencia, paginación, límites de solicitudes, el encabezado Request-Id y qué cambia respecto a Stripe.