Guía de integración de QuickBooks Online para programar la producción con SkyPlanner APS

QuickBooks Online es un único producto en la nube con arquitectura multiinquilino, y todas las empresas utilizan la misma Accounting API. Es una REST API en su versión v3. Cada llamada se dirige a una empresa mediante su realm ID: https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}. Para las pruebas se utiliza un servidor sandbox independiente. Las solicitudes y las respuestas están en formato JSON, y el parámetro minorversion selecciona la versión del esquema. (fuente)

Entidades necesarias para programar la producción:

• Datos maestros: Customer, Item (Inventory, NonInventory, Service), Employee, Vendor.
• Demanda: Estimate (TxnStatus Accepted, líneas, ShipDate) y, para los talleres que facturan antes de producir, Invoice o SalesReceipt.
• Aprovisionamiento: PurchaseOrder (POStatus Open, líneas con artículos y cantidades), Bill.
• Escritura de datos en QuickBooks: Estimate, Invoice, TimeActivity, InventoryAdjustment.

Las lecturas utilizan el endpoint de consultas, por ejemplo select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'. Las actualizaciones pueden ser parciales, por lo que SkyPlanner envía solo los campos que modifica. La Accounting API no tiene entidades para pedidos de venta, rutas de fabricación, centros de trabajo ni órdenes de producción.

Los webhooks de QuickBooks notifican a la aplicación cuando cambian los datos de una empresa conectada. «Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.» (Los webhooks te avisan automáticamente cuando cambian los datos de los archivos de empresa de QuickBooks Online del usuario final). (fuente) Estas son las entidades relevantes para la programación de la producción:

• Customer, Item, Employee
• Estimate, Invoice, SalesReceipt
• PurchaseOrder, Bill
• TimeActivity

Las operaciones incluyen Create, Update, Delete, Merge y Void. Cada notificación contiene el nombre de la entidad, su ID, la operación y la fecha y hora de la última actualización, no el registro completo. El receptor lee el registro después.

La captura de cambios (GET /cdc?entities=...&changedSince=...) devuelve todos los cambios producidos desde una marca de tiempo, dentro de un intervalo reciente. SkyPlanner la utiliza para una conciliación nocturna, de modo que un webhook perdido nunca deja un pedido desactualizado. TimeActivity no está incluido en la captura de cambios, por lo que se concilia mediante una consulta. (fuente)

1. Carga inicial de datos maestros. Consulta por páginas los clientes, artículos, empleados y pedidos de compra abiertos mediante el endpoint de consultas. Crea los clientes en SkyPlanner con el ID de QuickBooks como external_identifier, y los productos y materiales con el ID del artículo como clave. Después, configura lo que QuickBooks no almacena: estaciones de trabajo, etapas del proceso de cada producto, turnos, permisos y vacaciones, y tiempos de preparación. La importación mediante CSV o Excel es la vía más rápida para las etapas del proceso.

2. Sincronización de pedidos. Suscríbete a los webhooks de Estimate, Invoice, Item y PurchaseOrder. Cuando un presupuesto pasa al estado Accepted, SkyPlanner lo lee y crea un pedido con el número de presupuesto como external_order_number y la fecha de envío como delivery_date. Cada línea genera tareas correspondientes a las etapas del proceso del producto. Las líneas de pedidos de compra abiertos se convierten en material pendiente de recibir, de modo que las tareas esperan a la entrega. La captura de cambios nocturna recupera cualquier evento que se haya perdido.

3. Envío a QuickBooks del programa y de los trabajos terminados. Cuatro llamadas escriben los resultados en QuickBooks:

• Una actualización parcial de Estimate escribe el campo ShipDate, de modo que la fecha comprometida en QuickBooks se ajusta al plan.
• Al terminar el pedido, POST /invoice crea la factura con las líneas del presupuesto y un LinkedTxn que la vincula a él. Intuit permite vincular una factura por presupuesto, por lo que el tratamiento de las entregas parciales se acuerda durante la definición del alcance.
• POST /timeactivity guarda las horas registradas por cada operario, asociándolas al empleado, al cliente y a un artículo de servicio. Las horas facturables pueden añadirse después a la factura en QuickBooks.
• POST /inventoryadjustment aumenta las existencias de productos terminados y reduce las de materiales consumidos. Intuit ofrece esta entidad en QuickBooks Online Plus y Advanced en Estados Unidos. (fuente)

4. Confirmaciones en planta. Los operarios registran el trabajo con SkyPlanner Mobile Confirmations, Production Timer o Quick Log Mode. El avance actualiza de inmediato el programa de producción y Autopilot reprograma el resto. Las horas se envían a QuickBooks como actividades de tiempo. Si el taller sigue utilizando QuickBooks Time para las nóminas, elige un único canal para las horas de las tareas durante la definición del alcance.

5. Responsabilidad sobre los datos y reglas para resolver conflictos. Déjalas por escrito antes de la entrada en producción:

• Los pedidos de venta se quedan en las pantallas de QuickBooks. Plus y Advanced incluyen pedidos de venta en la aplicación, pero la integración lee los presupuestos aceptados o las facturas, en el caso de las fábricas que facturan primero. Acuerda un único desencadenante para que todos los pedidos entren de la misma forma.
• QuickBooks no contiene rutas de fabricación. Mantén las etapas del proceso de cada producto en SkyPlanner, vinculadas mediante la clave del artículo de QuickBooks.
• Una factura vinculada por presupuesto. Las entregas parciales necesitan una regla, como crear un presupuesto por entrega.
• Ajustes de inventario según el plan y la región. Plus y Advanced los admiten en Estados Unidos. En otras regiones, acuerde con su contable cómo registrar los productos terminados en QuickBooks.
• Órdenes de fabricación de Intuit Enterprise Suite. Si las utiliza, decida qué sistema será la referencia para los montajes y las reservas de componentes.
• Los paquetes son de solo lectura a través de la API. Los artículos de tipo Group no se pueden crear a través de la API, por lo que debe mantener los paquetes en QuickBooks.
• Rotación del token de actualización. Guarde el token de actualización más reciente tras cada renovación; de lo contrario, se perderá la conexión.