Conectar QuickBooks Online: pedidos, clientes, facturas, pagos e inventario
Tome el Realm ID (Company ID) en QuickBooks en el icono de engranaje → Account and settings → Billing & subscription, obtenga un access token en el OAuth2 playground de Intuit Developer para su app, complete ambos en Integration, pruebe, mapee y active. El token caduca tras 1 hora, así que una prueba fallida suele significar solo que hace falta un token nuevo.
El conector de QuickBooks Online trabaja con su empresa de QuickBooks en ambos sentidos: trae pedidos de venta, clientes, facturas, productos y pagos, puede devolver clientes, facturas, productos y pagos, y consulta el inventario por artículo. Un pago enviado a QuickBooks puede vincularse a su factura para saldarla. La conexión se identifica con su Realm ID (Company ID) y un access token que usted pega. Ese token caduca tras 1 hora: cuando algo deja de funcionar de repente, obtenga primero un token nuevo antes de cambiar cualquier otra cosa.
Requisitos previos#
- Una empresa de QuickBooks Online a la que pueda acceder, con permiso para abrir Account and settings.
- Una app en Intuit Developer, para poder ejecutar su OAuth2 playground y obtener un access token para esa empresa.
- Sabe en qué entorno vive la empresa: production para una empresa real, sandbox para una empresa sandbox de Intuit Developer.
- Tiempo para terminar sin demora tras obtener el token: el access token caduca tras 1 hora, así que obténgalo al final, justo antes de completarlo y probar.
Obtener credenciales#
- Obtenga el Realm ID dentro del propio QuickBooks: inicie sesión en QuickBooks, haga clic en el icono de engranaje ⚙ de arriba a la derecha, abra Account and settings, vaya a Billing & subscription y copie el Company ID que aparece allí: ese Company ID es el Realm ID.
- Obtenga el access token en Intuit Developer: abra Intuit Developer, abra su app y abra su OAuth2 playground.
- En el OAuth2 playground, ejecute el flujo OAuth2 para la misma empresa y el mismo entorno (production o sandbox) y copie el access token que devuelve.
- Pase directamente al paso de completar: este access token caduca tras 1 hora. Refrescar un token usa el Client ID y el Client Secret de esa misma app de Intuit Developer, así que tenga también a mano esos valores de la app.
Completar en Integration#
- Abra Integration → Marketplace → QuickBooks Online → Nueva conexión.
- realm_id, obligatorio, Realm ID (Company ID): pegue el Company ID copiado de QuickBooks → icono de engranaje ⚙ → Account and settings → Billing & subscription, por ejemplo 123456789.
- environment, opcional, Environment: complete production para una empresa real, o sandbox para una empresa sandbox de Intuit Developer. Si lo deja vacío, se usa production.
- access_token, obligatorio, Access token: pegue el access token de Intuit Developer → su app → OAuth2 playground, completo y de inmediato, porque caduca tras 1 hora. Es un campo de tipo contraseña y se guarda como secreto.
Probar la conexión#
Haga clic en Probar la conexión. Con su token como credencial bearer, la prueba lee la información de su empresa desde QuickBooks: en production llama a la información de la empresa para su realm_id, y en sandbox usa en su lugar la dirección sandbox. Una respuesta correcta devuelve el nombre de su empresa, que es como sabe que el token y el Realm ID pertenecen a la empresa que espera. Si falta realm_id, la prueba se detiene con MISSING_REALM_ID; si falta access_token, se detiene con MISSING_TOKEN, sin enviar ninguna solicitud. Una respuesta 401 se informa como INVALID_TOKEN: el token no es válido o, lo más frecuente, simplemente pasó su 1 hora. La prueba espera 12 segundos antes de informar TEST_TIMEOUT.
Mapping / elegir plantilla#
Elija el mapping estándar de QuickBooks Online. Cubre los objetos con los que trabaja esta conexión: pedidos de venta, clientes, facturas, productos (items), pagos y cantidades de inventario por artículo. Tras aprobar la prueba, ejecute una extracción y compare un registro real lado a lado (un número de pedido o de factura, el cliente, las líneas y los importes) y envíe un cliente o un producto y confirme que aparece en QuickBooks, antes de activar. Si un nombre de su empresa difiere del objeto estándar, ajuste ese campo en el mapping en lugar de renombrar nada en QuickBooks.
Activar#
Tras activar, la conexión trae pedidos de venta, clientes, facturas, productos y pagos de QuickBooks Online según la frecuencia definida, devuelve clientes, facturas, productos y pagos cuando esos flujos se ejecutan, y responde a las consultas de inventario por artículo. Vigile las primeras ejecuciones en Runs / Logs y compárelas con QuickBooks antes de dejar la conexión sin supervisión.
Mantenga el token fresco: caduca tras 1 hora, así que cuando una ejecución empiece a fallar con un error de token, vuelva a Intuit Developer → su app → OAuth2 playground, obtenga un access token nuevo para la misma empresa y el mismo entorno, péguelo en access_token y pruebe de nuevo. Nada más en la conexión necesita cambiar para una renovación rutinaria del token.
Preguntas frecuentes#
La prueba falla con INVALID_TOKEN (401)
QuickBooks rechazó el access token. La causa más común, con diferencia, es el tiempo: el token caduca tras 1 hora, así que un token que funcionaba al pegarlo ya puede estar caducado cuando prueba o cuando arranca una ejecución posterior. Un token obtenido para otra empresa o para otro entorno es rechazado de la misma manera.
No cambie primero realm_id ni environment. Vaya a Intuit Developer → su app → OAuth2 playground, ejecute el flujo de nuevo para la misma empresa y el mismo entorno, pegue el access token nuevo en access_token, guarde y pruebe de nuevo enseguida.
La prueba se detiene con MISSING_REALM_ID o MISSING_TOKEN
Uno de los dos valores de identificación está vacío y la prueba no envía ninguna solicitud sin ambos. MISSING_REALM_ID significa que realm_id está vacío; MISSING_TOKEN significa que access_token está vacío, o que el token que pegó quedó recortado y no se guardó nada utilizable.
Complete realm_id desde QuickBooks → icono de engranaje ⚙ → Account and settings → Billing & subscription → Company ID, y pegue completo un access token nuevo del OAuth2 playground. Guarde y pruebe de nuevo de inmediato, antes de que el token nuevo envejezca.
La prueba falla con MISSING_SCOPE
El token fue aceptado como token, pero no lleva el ámbito contable que esta conexión necesita (com.intuit.quickbooks.accounting), así que QuickBooks no le deja leer la información de la empresa.
En el OAuth2 playground, ejecute el flujo de nuevo asegurándose de que el ámbito contable está incluido para su app, copie el access token nuevo, péguelo en access_token y vuelva a probar.
La prueba devuelve un nombre de empresa distinto del esperado
El token y el Realm ID no describen la misma empresa. El nombre de empresa del resultado de la prueba viene de la empresa a la que el token y el realm_id apuntan de verdad: a menudo una empresa sandbox cuando usted esperaba production, o el token se obtuvo en el playground para otra empresa.
Revise los tres valores juntos: realm_id de la empresa pretendida en icono de engranaje ⚙ → Account and settings → Billing & subscription → Company ID, environment en production o sandbox según esa empresa, y un token del playground ejecutado para esa misma empresa y ese mismo entorno. Corrija el que no coincide y vuelva a probar.
Todo funcionaba, y una hora después las ejecuciones empezaron a fallar
Ese momento es la vida del token, no un mapping roto ni una empresa cambiada. El access token caduca tras 1 hora, así que una conexión que probó bien fallará en ejecuciones posteriores con un error de token hasta que se pegue un token nuevo.
Obtenga un access token nuevo en Intuit Developer → su app → OAuth2 playground para la misma empresa y el mismo entorno, péguelo en access_token y pruebe. Refrescar un token usa el Client ID y el Client Secret de esa app: tenga esos valores de la app listos para que la renovación sea rápida.
La prueba informa TEST_TIMEOUT o CONNECTION_FAILED
La solicitud de información de la empresa no terminó. TEST_TIMEOUT significa que no llegó una respuesta completa en 12 segundos; CONNECTION_FAILED significa que la solicitud a QuickBooks no salió. Antes de culpar a la red durante mucho tiempo, recuerde el orden de sospecha aquí: un token caducado o de un entorno equivocado sigue siendo lo primero que hay que descartar en esta conexión.
Primero pegue un access token nuevo para la misma empresa y compruebe que environment coincide con él (production o sandbox), y después pruebe de nuevo. Si un token nuevo y bien emparejado sigue agotando el tiempo, inténtelo de nuevo tras una breve espera y revise Runs / Logs para ver el error exacto antes de cambiar realm_id.