Claves de API y Webhooks

Iraca puede conectarse con tus otros sistemas de dos formas. Las claves de API permiten que un script o servicio externo extraiga datos de Iraca. Los webhooks permiten que Iraca envíe una notificación a tus sistemas en el momento en que algo sucede. Ambos se encuentran en Configuración, y ambos están limitados a propietarios y administradores.

¿Quieres preguntarle a un asistente de IA sobre tus datos?

Las claves de API son para scripts e integraciones. Para conectar Claude u otro asistente de IA, usa Habla con Iraca: sus claves de conexión son de solo lectura, siguen el rol de cada persona y solo funcionan con asistentes de IA.

---

Claves de API

Una clave de API autentica un script o herramienta externa como tu espacio de trabajo, sin que una persona inicie sesión. Están pensadas para extraer datos de reportes hacia otro sistema — una herramienta de BI, una exportación programada, un panel interno.

Crear una clave

Abre Configuración → Claves de API → Crear clave de API e indica:

• Nombre — algo que identifique qué la está usando (p. ej. "Panel de Looker," "Script de exportación nocturna").
• Permisos — read (lectura) y/o write (escritura). Una solicitud que modifica datos (cualquiera que no sea GET) se rechaza a menos que la clave tenga write.
• Vencimiento (opcional) — una fecha después de la cual la clave deja de funcionar por sí sola.

Haz clic en Crear, y el valor en texto plano de la clave se muestra una sola vez. Cópialo de inmediato — Iraca lo guarda cifrado (hash) y no puede volver a mostrártelo. Si lo pierdes, elimina la clave y crea una nueva.

Usar una clave

Envíala como un token Bearer, junto con el ID de tu espacio de trabajo:

Authorization: Bearer <tu-clave>
X-Tenant-ID: <tu-id-de-espacio-de-trabajo>

A qué puede acceder una clave

Las claves de API están deliberadamente restringidas a un conjunto reducido y fijo de endpoints — actualmente el resumen del panel y los endpoints de reportes de Canopy (valoración de inventario, velocidad de ventas, eficiencia de producción, COGS, diario, balance de comprobación, bloqueos de período). Esta lista crece solo cuando integraciones reales lo necesitan, así que una clave expuesta no puede usarse para explorar o modificar datos fuera de los reportes.

Bueno saberlo

• Eliminar una clave la revoca de inmediato. No hay forma de deshabilitarla temporalmente — elimínala y, si es necesario, crea un reemplazo.
• Las claves aplican a todo el espacio de trabajo, no están limitadas a la persona que las creó. Cualquier clave puede leer todo lo que cubre la lista permitida, sin importar quién la creó o su rol.
• Una sesión iniciada normalmente (la forma habitual de usar Iraca) no se ve afectada por nada de esto — estas restricciones solo aplican a las claves de API.

---

Webhooks

Un webhook es la dirección inversa: Iraca envía un POST HTTP firmado a una URL que tú controlas cada vez que algo sucede en tu espacio de trabajo, para que tus sistemas no tengan que consultar constantemente si hubo cambios.

Configurar uno

Abre Configuración → Webhooks → Agregar endpoint e indica:

• URL del endpoint — a dónde envía Iraca la notificación.
• Eventos — elige los eventos específicos que quieres recibir, o deja todos sin marcar para recibirlos todos (incluidos los que se agreguen en el futuro).
• Activo — desactiva un webhook para pausar los envíos sin perder su configuración.

El endpoint debe ser una dirección pública en el puerto estándar: https:// en el 443 (o http:// en el 80), sin usuario ni contraseña en la URL. Las direcciones de una red privada o interna, como localhost, 10.x.x.x o 192.168.x.x, se rechazan al guardar y de nuevo antes de cada envío. Iraca no sigue redirecciones, así que apunta el webhook a la URL final.

Verificar un envío

Cada envío incluye dos encabezados:

• X-Webhook-Event — el nombre del evento, p. ej. order.fulfilled.
• X-Signature — sha256=<hmac>, un HMAC-SHA256 del cuerpo de la solicitud usando el secreto de firma de tu endpoint.

El secreto de firma se muestra una sola vez, justo después de crear el endpoint. Si no lo guardaste, elimina el webhook y crea uno nuevo — actualmente no hay forma de volver a ver el secreto de uno existente.

Para verificar que un envío realmente proviene de Iraca, calcula el HMAC tú mismo y compáralo:

$expected = 'sha256=' . hash_hmac('sha256', $rawRequestBody, $yourStoredSecret);
if (! hash_equals($expected, $request->header('X-Signature'))) {
    abort(401);
}

Todo envío tiene el mismo formato:

{
  "event": "order.fulfilled",
  "timestamp": "2026-09-19T14:32:00+00:00",
  "payload": { "...": "campos específicos del evento" }
}

Usa el botón Enviar prueba en un endpoint para disparar un evento test puntual y confirmar que tu receptor está disponible y responde con éxito.

Reintentos de envío

Si tu endpoint no responde con éxito, Iraca reintenta hasta 3 veces con un retraso creciente (30s, 60s y luego 120s) antes de descartar ese envío.

Eventos y sus campos

Evento	Campos de payload
order.created	order_id, type, source, status
order.status_changed	order_id, status, previous_status
order.fulfilled	order_id, source
inventory.adjusted	product_id, product_name, sku, warehouse_id, type, quantity_on_hand
inventory.low_stock	product_id, warehouse_id, quantity_on_hand, reorder_point
production_run.completed	production_run_id, recipe_id, recipe_name, actual_quantity
tenant.created	tenant_id, tenant_slug, plan_slug
tenant.plan_changed	tenant_id, before, after
tenant.status_changed	tenant_id, before, after
tenant.shipping_updated	tenant_id, before, after
tenant.subscription_created	plan, interval
tenant.subscription_updated	status, stripe_status
tenant.subscription_deleted	stripe_subscription_id
tenant.payment_failed	invoice_id, amount_due, currency, attempt
tenant.trial_expiring	tenant_id, tenant_slug, trial_ends_at, days_remaining
tenant.trial_expired	tenant_id, tenant_slug, trial_ends_at, plan_slug

inventory.low_stock se dispara una vez cuando un producto cruza hacia stock bajo — no vuelve a dispararse en cada venta posterior mientras se mantenga bajo. Usa la misma definición que la lista de stock bajo de tu panel (un punto de reorden mayor a cero, el producto activo, y las notificaciones de stock bajo habilitadas), así que ambos nunca se contradicen.

Bueno saberlo

• Deja los eventos sin marcar para suscribirte a todos, incluidos los que Iraca agregue después de configurar el webhook.
• El secreto de firma de un webhook es único para ese endpoint. Si tienes varios endpoints, verifica cada envío contra el secreto del endpoint que lo recibió.
• Los envíos ocurren en segundo plano — crear un endpoint o un pedido no esperará a que tu servidor responda.