API Pública

Integra Renaska con tus sistemas

Accede a productos, inventario, clientes, pedidos, cotizaciones, pagos y envíos desde cualquier servicio externo. La API es server-to-server: la clave vive en tu servidor, nunca en el navegador.

Solo server-to-serverTu API Key es un secreto. Nunca la incluyas en código frontend, apps móviles ni variables de entorno públicas.
Ir a Configuración → Claves de API

Inicio rápido

Autentícate con tu clave en el header Authorization:

# Ejemplo: listar clientes
curl https://bk.renaska.com/api/external/v1/clients \
  -H "Authorization: Bearer rnk_live_<key>"

URL base: https://bk.renaska.com/api/external/v1

La especificación OpenAPI es pública y no requiere clave — agrega ?lang=es o ?lang=en para obtenerla en tu idioma.

Scopes y permisos

Cada clave otorga uno o más scopes con el formato resource:action (por ejemplo orders:write).

Usa * para acceso total o resource:* para leer y escribir un recurso completo.

Grupos de recursos

Cada grupo se controla con su propio scope.

ProductsLectura y escritura
InventoryLectura y escritura
InputsLectura y escritura
ClientsLectura y escritura
OrdersLectura y escritura
QuotationsLectura y escritura
PaymentsLectura y escritura
ShippingLectura y escritura

Además: GET /catalog y GET /ping como endpoints de utilidad.

  • Una clave de API llega a todas las sedes de la cuenta: las claves no tienen alcance por sede, así que hasta un miembro del equipo limitado a una sola sede queda más restringido que cualquier clave. Así está diseñado.
  • Las lecturas de pedidos incluyen las ventas del POS y sus precios unitarios. El panel se los oculta a los roles no administradores; la API no.

Efectos que debes conocer

  • POST /orders y POST /quotations/:id/convert descuentan stock y generan el asiento contable — no notifican al cliente.
  • POST /shipments no descuenta stock.

Detalles operativos

  • Envía un header Idempotency-Key (máx. 255 caracteres) para evitar duplicados: es opcional en POST /orders y otros POST más antiguos, y OBLIGATORIO en las rutas de escritura de productos, inventario e insumos, y en PATCH /orders/:id/status y PATCH /orders/:id/stage, que responden 400 si falta. En PUT y PATCH actúa como candado de concurrencia, no como caché: un reintento posterior vuelve a ejecutarse.
  • Límites por clave: 120 lecturas/min y 30 escrituras/min.
  • Las listas se paginan con data + meta (page, limit, total, totalPages) — 20 elementos por página por defecto, máximo 100.
  • Los errores responden con un objeto error (code, message) — por ejemplo 403 insufficient_scope, 429 rate_limited o 409 conflict.

Referencia de endpoints

Explora todos los endpoints y descarga la spec OpenAPI 3.1.

Descargar OpenAPI 3.1 (JSON)