Conecte su propio software con claves de API

La API pública permite que su propio software, o el de su desarrollador, lea y escriba sus registros de Kluvan: productos, clientes, existencias, informes, documentos de Contabilidad, personas de RR. HH., CRM, suscripciones y las aplicaciones que tenga. Usted controla cada clave: qué puede hacer, durante cuánto tiempo y para qué sucursal.

Antes de empezar

• Solo el propietario puede crear y revocar claves.
• Una clave nunca abre una aplicación que su organización no tenga, y todas las reglas de su plan, sus aplicaciones y sus sucursales se siguen aplicando.

Pasos

1. Abra Configuración → Acceso para desarrolladores.
2. En Nueva clave, escriba un Nombre que reconozca, por ejemplo "Escáner del almacén".
3. Establezca Válida durante días (1–365). El valor predeterminado es 90.
4. En Sucursal, deje Todas las sucursales o elija una sucursal.
5. En Puede ver, marque cada ámbito que necesite la clave. Cada uno indica Lectura o Escritura, por ejemplo Productos · Lectura.
6. Marque la frase que confirma que autoriza el acceso seleccionado.
7. Pulse Crear la clave.
8. Copie la clave ahora. Se muestra solo esta vez.
9. Entregue la clave a su software. Este la envía en el encabezado Authorization: Bearer.

Llamar a la API

• La dirección es https://api.kluvan.com/v1/public-api. La Guía para desarrolladores (/developers) muestra ejemplos y cada operación con el ámbito que necesita. OpenAPI 3.1 descarga el contrato completo, con los campos de las solicitudes.
• Toda escritura necesita una Idempotency-Key: un UUID nuevo por cambio. Si se pierde la respuesta, envíe la misma solicitud con la misma clave otra vez, durante hasta 7 días; no se aplica dos veces. La misma clave con una solicitud modificada se rechaza.
• Un cambio en un registro existente también envía la versión actual del registro (v), para que una copia más antigua nunca sobrescriba una más reciente.
• Los importes se expresan en la unidad más pequeña de la moneda (150.00 es 15000).
• Las listas de registros de aplicaciones devuelven hasta 50 registros y un valor next; páselo como after para obtener la página siguiente.
• Hasta 120 solicitudes por minuto por clave. Por encima, la respuesta es 429 con Retry-After. Todo error lleva un código (consulte la guía de errores).

Conviene saber

• Los ámbitos de escritura cambian registros reales y pueden ejecutar las acciones de una aplicación, con sus efectos en existencias y contabilidad. Dé a una clave solo los ámbitos que necesita.
• Las claves de sucursal solo leen registros de la sucursal. Las operaciones de catálogo, clientes, CRM, RR. HH. y suscripciones necesitan una clave para todas las sucursales.
• Kluvan solo conserva una huella (hash) de cada clave. ¿Perdió una clave? Revóquela y cree una nueva.
• Revocar detiene una clave al instante. Una clave también se detiene en su último día. Puede tener hasta 20 claves.
• Actividad de la API enumera cada llamada: hora, operación, clave y estado. Los cuerpos de las solicitudes y las claves nunca se registran.
• La API no ofrece facturación, inicio de sesión, cobro de pagos ni webhooks: no hay notificaciones salientes, así que su software lee las listas que necesita.
• Una sesión de navegador con la sesión iniciada no puede llamar a esta API, y las claves para aplicaciones de asistente son independientes: consulte conectar una aplicación de asistente.