10. Integraciones

La API

Todo lo que necesita una integración es JSON sobre HTTPS en el propio subdominio de la empresa, autenticado con una clave de API que crea un administrador y que se muestra una sola vez. Los decimales son cadenas: los números de JSON son de coma flotante, y las cantidades y el dinero no lo son. La referencia de la API enumera todos los endpoints.

Una aplicación que usan muchas empresas, como Syncomatic, no pide una clave: envía al usuario a Foudra, el usuario inicia sesión y la autoriza, y la aplicación recibe un token que actúa como ese usuario y que aparece en Aplicaciones conectadas, donde cualquiera puede desconectar lo que ha autorizado.

La regla de diseño en todo momento: la API es la verdad, y las escrituras son prudentes. Los scripts crean borradores que aprueba una persona; las máquinas informan de lo que han hecho; nada de fuera del sistema puede comprometer dinero ni inventarse stock.

Datos personalizados

Cada artículo, puesto de trabajo y orden de fabricación lleva un bloque opaco de JSON que el sistema valida y guarda, pero nunca interpreta. Es para las integraciones: dónde está el G-code de una pieza impresa, la dirección de red de una impresora, la densidad de un filamento. Edítalo en la página Custom data (datos personalizados) de cada elemento o a través de la API, y que el sistema siga sin saber qué contiene.

Tres formas

ETL desde un proveedor. Un script toma la exportación de pedidos de un proveedor, resuelve sus referencias mediante GET /api/sourcing y envía un pedido en borrador con POST /api/purchase-orders. Las referencias desconocidas hacen fallar toda la petición, indicando la línea; asígnalas en aprovisionamiento y vuelve a intentarlo. Tras unos cuantos pedidos, tu tabla de aprovisionamiento es la tabla de equivalencias.

Una máquina que fabrica cosas. Un gestor de granja de impresión consulta GET /api/workstations/{id}/next mientras su impresora está inactiva, inicia el paso, imprime, lo completa con la cantidad (y, pronto, con el filamento realmente usado) y vuelve a poner el puesto como inactivo. Cuando necesita a una persona, pasa a bloqueado y envía una tarea con PUT /api/tasks/{source}. El diseño completo está en el repositorio, en docs/integrations/print-manager.

Sacar datos. Un sistema de ventas que necesita cantidades lee GET /api/stock; un panel externo lee GET /api/parts. Claves de solo lectura para usos de solo lectura.

Recibir avisos

Los webhooks son el sistema llamando hacia fuera cuando ocurre algo: se completa una orden de fabricación, cambia el stock. Un administrador indica una URL y los eventos que quiere; cada mensaje va firmado, se reintenta si el receptor no está disponible y queda registrado. El evento se escribe en la misma transacción que el cambio del que informa, así que nunca se anuncia nada que no haya ocurrido.

Un sistema que pide trabajo y quiere saber cuándo está hecho. El control de misión solicita una revisión con POST /api/work-orders, indicando el casco como referencia de la orden. Cuando se completa el último paso, el webhook work_order.completed devuelve esa referencia, y el barco puede volver al servicio. Foudra nunca llega a saber qué es un casco.

Consultar periódicamente sigue funcionando para todo y siempre es correcto; un webhook solo elimina la espera.

Siguiente: ritmo.