Claves de API y webhooks

Las claves de API y los webhooks te permiten conectar Bizaldo con sistemas externos para sincronización con ERP, paneles personalizados, automatización de inventario o herramientas internas sin compartir las credenciales de inicio de sesión del personal.

Dónde encontrarlo: En la barra lateral del panel de Bizaldo, abre Settings. Usa la pestaña API Keys para crear claves y la pestaña Webhooks para registrar endpoints. La sección General en la parte superior de Settings muestra tu Company ID y Branch ID actuales, que muchas integraciones necesitan junto con la clave.

Quién puede gestionar las integraciones

Solo los usuarios con el rol de Admin o Super Admin ven las pestañas de API Keys y Webhooks. Otros roles (Manager, Cashier, Staff) pueden usar Settings para las opciones de perfil y de la página de pedidos, pero no pueden crear ni revocar claves.

Empresa y sucursal

Las claves de API y los webhooks se crean para la empresa y la sucursal seleccionadas en el encabezado del panel en el momento en que los creas. Selecciona la empresa y sucursal correctas antes de crear credenciales. Copia Company ID y Branch ID desde Settings → General al configurar tu integración.

12345

Figura 1 — Pestaña API Keys de Settings con los ID de empresa y sucursal

Elementos de la pantalla

Pestaña API Keys

Abre Settings y selecciona API Keys para gestionar las credenciales de integración.

Company ID

Copia el ID de la empresa para tu integración. Coincide con la empresa seleccionada en el encabezado del panel.

Branch ID

Copia el ID de la sucursal para tu integración. Coincide con la sucursal seleccionada en el encabezado del panel.

Create API Key

Inicia el flujo de creación de clave.

Estadísticas de uso

Claves totales, claves activas, solicitudes totales y solicitudes de hoy.

Claves de API

Qué contiene una clave de API

Cada clave de API tiene:

Campo	Descripción
Nombre	Etiqueta legible para humanos (mínimo 3 caracteres), por ejemplo, `Production ERP`
Descripción	Nota opcional sobre lo que hace la integración
Clave pública	Identificador que puedes referenciar en registros; siempre visible en el panel
Clave secreta	Credencial usada para autenticar las solicitudes de API; oculta por defecto, muéstrala con el icono de ojo
Permisos	Alcances detallados (ver abajo)
Estadísticas de uso	Solicitudes totales y marca de tiempo de último uso

El panel muestra estadísticas agregadas: Total Keys, Active Keys, Total Requests y Requests Today.

Crear una clave de API

Inicia sesión con una cuenta Admin o Super Admin.
Selecciona la empresa y sucursal correctas en el encabezado del panel.
Ve a Settings → API Keys.
Haz clic en Create API Key.
Introduce un nombre (al menos 3 caracteres) y una descripción opcional.
Selecciona los permisos. Concede solo lo que la integración necesita (privilegio mínimo).
Haz clic en Create Key.
Copia la clave pública y la clave secreta de inmediato. Guarda el secreto en un gestor de contraseñas o variable de entorno (por ejemplo, `BIZALDO_API_SECRET`). Nunca confirmes secretos en el control de versiones ni los incorpores en código del lado del cliente.

Modal Create API Key con nombre, descripción y permisos

1234

Figura 2 — Create API Key: nombre, descripción y alcances de permiso

Elementos de la pantalla

Key Name

Etiqueta obligatoria para la clave (mínimo 3 caracteres).

Description

Nota opcional que describe lo que hace esta integración.

Permissions

Selecciona los alcances por grupo de entidad. Concede solo lo que la integración necesita.

Create Key

Genera el par de clave pública y secreta.

Permisos disponibles

Los permisos se agrupan por entidad. Activa un grupo completo o alcances individuales:

Entidad	Permisos
Productos	View, Create, Update, Delete, Manage Stock, Manage Pricing
Categorías	View, Create, Update, Delete, Manage Hierarchy
Pedidos	View, Create, Update, Delete, Manage Status, Process Payments, Manage Refunds
Mesas (solo restaurante)	View, Create, Update, Delete, Manage Reservations, Manage Status
Reservas (solo restaurante)	View, Create, Update, Delete
Cliente	View, Create
Recompensas	View, Create, Update, Delete, Manage Points, Manage Redemptions
Usuarios	View, Create, Update, Delete, Manage Roles, Manage Access
Inventario	View
Informes y análisis	View, Export, Create Custom Reports, Manage Scheduled Reports
Configuración del sistema	View, Update, Manage Integrations, Manage API Keys

Las empresas tipo restaurante también ven los grupos de permisos Tables y Bookings. Las de retail y otros sectores no.

Usar una clave de API

Envía solicitudes de servidor a servidor al servidor de la API abierta de Bizaldo usando tu clave secreta:

GET /api/v1/products HTTP/1.1
Host: openapi.bizaldo.com
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json

Incluye la empresa y sucursal de tu selección del panel:

x-company-id: YOUR_COMPANY_ID
x-branch-id: YOUR_BRANCH_ID

Casos de uso típicos:

Sincronización de catálogo: Extrae o envía productos y categorías
Automatización de inventario: Reacciona a los cambios de nivel de stock
Informes personalizados: Crea informes a partir de los datos de tu sucursal
Exportaciones nocturnas: Extrae los pedidos completados a herramientas de contabilidad

Gestionar claves existentes

Acción	Efecto
Copiar pública/secreta	Usa el icono de copiar junto a cada campo de clave
Mostrar/ocultar secreta	El icono de ojo alterna la visibilidad
Regenerar secreta	Crea una nueva clave secreta; la anterior deja de funcionar de inmediato. Actualiza tu integración antes de revocar la clave anterior.
Desactivar	La clave pasa a inactiva; las llamadas a la API con esa secreta fallan
Activar	Reactiva una clave previamente desactivada
Mostrar desactivadas	Activa para listar las claves inactivas para auditoría

Rota las claves de forma segura

Crea una nueva clave, implementa el nuevo secreto en tu integración, confirma que el tráfico funciona correctamente, y luego desactiva o regenera la clave anterior. La regeneración es inmediata. No hay período de gracia.

Webhooks

Los webhooks envían notificaciones HTTP a tu servidor cuando ocurren eventos de Bizaldo, para que no necesites sondear la API.

Eventos admitidos

El panel te permite suscribirte a estos tipos de evento (el mismo conjunto para las industrias de restaurante, retail y predeterminada):

Evento	Cuándo se activa
`product.created`	Se añade un nuevo producto
`product.updated`	Se cambian los detalles del producto
`product.deleted`	Se elimina un producto
`product.stock_updated`	Cambian los niveles de stock
`category.created`	Se añade una nueva categoría
`category.updated`	Se cambian los detalles de la categoría
`category.deleted`	Se elimina una categoría

Selecciona uno o más eventos al registrar o editar un webhook. Se requiere al menos un evento.

Registrar un webhook

Selecciona la empresa y sucursal correctas en el encabezado del panel.
Ve a Settings → Webhooks.
Haz clic en Register Webhook.
Completa el formulario:

Campo	Obligatorio	Notas
URL del endpoint	Sí	URL HTTPS pública, por ejemplo, `https://your-server.com/webhooks/bizaldo`
Descripción	No	Ayuda a identificar el endpoint más tarde
Clave de API	Cadena secreta elegida por ti, usada para verificar las cargas útiles entrantes. Al editar, déjala en blanco para conservar la clave existente.
Eventos	Sí	Uno o más de la tabla anterior

Haz clic en Register Webhook.

Página de configuración de webhooks con formulario de registro de nuevo webhook

12345

Figura 3 — Registra un endpoint de webhook y suscríbete a eventos

Elementos de la pantalla

Pestaña Webhooks

Cambia de API Keys a Webhooks en Settings.

Empresa y sucursal

Contexto actual de empresa y sucursal para el webhook que se está registrando.

Endpoint URL

URL HTTPS pública que recibe las solicitudes POST de eventos.

API Key

Cadena secreta usada para verificar las cargas útiles de webhook entrantes.

Subscribe to events

Elige uno o más tipos de evento para recibir.

Tras el registro, Bizaldo muestra un secreto de firma en un banner amarillo: "API Key - Save this now!" Este valor se muestra solo una vez. Cópialo antes de cerrar el banner.

Usa este secreto para verificar el encabezado `X-Bizaldo-Signature` en cada solicitud de webhook entrante.

Verificar las firmas de webhook

Cada entrega incluye un encabezado `X-Bizaldo-Signature`. Calcula un HMAC del cuerpo de la solicitud en bruto usando tu secreto de firma y compáralo con el valor del encabezado. Rechaza las solicitudes que no coincidan. Tu endpoint debe:

Responder con 2xx en unos segundos
Ser idempotente. El mismo evento puede entregarse más de una vez; elimina duplicados usando el ID de evento si se proporciona en la carga útil
Usar HTTPS en producción

Gestionar webhooks

La lista de Registered Webhooks muestra cada endpoint con:

URL y descripción
Eventos suscritos
Estado Active/Inactive
Fecha de creación

Acciones por webhook:

Acción	Descripción
Editar	Cambia la URL, la descripción, los eventos o la clave de API
Historial de entregas	Consulta los últimos 100 intentos de entrega (nombre del evento, estado HTTP, número de intento, marca de tiempo)
Eliminar	Elimina el webhook y su historial de entregas; los eventos dejan de enviarse

Desarrollo local

Para pruebas locales, expón tu máquina con un túnel (ngrok, Cloudflare Tunnel, etc.) y registra la URL HTTPS del túnel como endpoint del webhook. Usa el historial de entregas en el panel para depurar intentos fallidos.

Mejores prácticas de seguridad

Emite claves separadas por entorno (staging frente a producción) y por integración.
Aplica permisos de privilegio mínimo. Una sincronización de catálogo de solo lectura no necesita `orders:delete`.
Restringe las URL de webhook a HTTPS y valida `X-Bizaldo-Signature` en cada solicitud.
No expongas los secretos de API en JavaScript del navegador, aplicaciones móviles o repositorios públicos.
Habilita la autenticación de dos factores en las cuentas de administrador que pueden gestionar claves.
Si un secreto se ve comprometido, regenera o desactiva la clave de inmediato y revisa las estadísticas de uso recientes.

Documentación relacionada

Configuración de la empresa — Perfil de la empresa, sucursales y facturación
Gestión de pedidos — Ciclo de vida del pedido (independiente del catálogo de eventos de webhook actual)
Descripción general de la plataforma — Arquitectura y aplicaciones de Bizaldo
Preguntas frecuentes — Preguntas comunes de integración

Claves de API y webhooks

Elementos de la pantalla

Elementos de la pantalla

Elementos de la pantalla

Documentación relacionada

En esta página