Desarrolladores: claves y registros

La pestaña Desarrolladores es donde la tienda se conecta a un sistema externo por la API: tu SaaS, un ERP, un CRM o un script tuyo. Ahí creas las claves que el sistema usa para entrar y ves el registro de cada llamada que hizo. Lo que el sistema puede hacer con la clave, y cómo programar la integración, está en la sección para desarrolladores, a partir de Visión general para desarrolladores.

Abrir la pestañaCopiar enlace de la sección

Abre General›Configuración › Desarrolladores. La pestaña tiene dos partes: las claves de API y los registros de solicitudes.

Claves de APICopiar enlace de la sección

Una clave de API es la contraseña que tu sistema usa para hablar con la tienda. Quien tiene la clave accede a los datos de la tienda, así que trátala como una contraseña.

Crear una claveCopiar enlace de la sección

1. Haz clic en el botón de crear clave.
2. Dale un nombre que diga dónde se va a usar, como "ERP" o "Servidor de producción".
3. Elige los alcances: lectura permite consultar clientes, suscripciones, pedidos, ofertas y productos; escritura va a permitir crear y modificar datos cuando se lancen los endpoints de escritura. Para un sistema que solo lee, marca solo lectura.
4. Copia la clave, que empieza con vk_live_. Aparece una sola vez: si cierras la ventana, ya no se puede ver. Si la pierdes, revócala y crea otra.

Pásale la clave a quien va a programar la integración por un canal seguro, nunca por correo ni mensaje en texto plano. Quien programa debe guardarla en una variable de entorno, como explica Autenticación y claves de API.

La lista de clavesCopiar enlace de la sección

Cada clave muestra el nombre, los últimos cuatro caracteres (el resto no se guarda), los alcances, la versión de la API en que fue creada, cuándo fue creada y cuándo se usó por última vez. La fecha de último uso dice si la integración está viva y, al cambiar una clave, si la antigua ya dejó de usarse.

Revocar una claveCopiar enlace de la sección

Usa la acción de revocar en la fila de la clave. La clave deja de funcionar al instante y el sistema que la usaba empieza a recibir un error de autenticación. No se puede deshacer. Para cambiar una clave sin detener la integración: crea la nueva, pide que la publiquen, espera a que la antigua quede sin uso y recién entonces revoca la antigua.

Registros de solicitudesCopiar enlace de la sección

Cada llamada que un sistema hace a la API queda registrada: la fecha y la hora, qué clave usó, el método y la ruta (como GET /v1/orders), el código de respuesta, la duración y, cuando falló, el tipo y el código del error. Cada fila tiene un identificador req_…, el mismo valor que la API devuelve en el encabezado Request-Id.

Los registros sirven para:

• Confirmar que la integración está llamando a la API, y con qué clave.
• Ver por qué falló una llamada sin necesitar acceso a los registros del otro sistema. El código del error está explicado en Errores.
• Localizar una llamada específica por el req_… que el desarrollador o el soporte te indicó.

Los registros se guardan por 30 días y después se borran. Las llamadas hechas sin una clave válida no aparecen: sin la clave, Vipter no sabe de qué tienda sería la llamada.

Los registros muestran lo que se pidió y el resultado, no el contenido de las respuestas. Los datos de los clientes no quedan duplicados aquí.

Qué significa "API desactivada"Copiar enlace de la sección

La API viene activa en toda tienda activa; no hay nada que solicitar. Vipter puede apagarla para una tienda concreta, por abuso o por una pendencia en la cuenta. En ese caso la pestaña muestra el aviso, no se pueden crear claves y cualquier llamada, incluso con una clave válida, recibe el error 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.

Problemas comunesCopiar enlace de la sección

• La integración recibe un error de autenticación justo después de crear la clave

  Revisa que la clave se copió entera, sin espacios al principio o al final, y que la API no fue desactivada para la tienda. Si la clave aparece como revocada en la lista, crea otra.

• La clave aparece como nunca usada, pero el sistema dice que está llamando

  El sistema puede estar llamando a otra dirección o con otra clave. Compara la dirección y los últimos cuatro caracteres de la clave en el sistema con la lista. La fecha de último uso puede tardar hasta un minuto en aparecer.

• Una llamada aparece con error 403 insufficient_scope

  La clave no tiene el alcance que exige la llamada. Crea una clave con el alcance correcto y cámbiala en el sistema.

• Muchas llamadas con error 429

  El sistema superó el límite de 100 solicitudes cada 2 segundos por clave. Quien programa debe respetar el encabezado Retry-After; consulta Límites de solicitudes.

Qué hacer despuésCopiar enlace de la sección

• Pásale a quien va a programar la Visión general para desarrolladores y la referencia de la API.
• Para recibir avisos de Vipter en tu sistema, en vez de consultar, configura un webhook.