Conectar o QuickBooks Online: pedidos, clientes, faturas, pagamentos e estoque
Pegue o Realm ID (Company ID) no QuickBooks no ícone de engrenagem → Account and settings → Billing & subscription, obtenha um access token no OAuth2 playground do Intuit Developer para seu app, preencha os dois no Integration, teste, mapeie e ative. O token expira após 1 hora, então um teste falho geralmente significa apenas que é preciso um token novo.
O conector do QuickBooks Online trabalha com sua empresa do QuickBooks nos dois sentidos: traz pedidos de venda, clientes, faturas, produtos e pagamentos, pode devolver clientes, faturas, produtos e pagamentos, e consulta o estoque por item. Um pagamento enviado ao QuickBooks pode ser vinculado à sua fatura para quitá-la. A conexão é identificada pelo seu Realm ID (Company ID) e um access token que você cola. Esse token expira após 1 hora: quando algo para de funcionar de repente, pegue primeiro um token novo antes de mudar qualquer outra coisa.
Pré-requisitos#
- Uma empresa do QuickBooks Online à qual você consiga entrar, com permissão para abrir Account and settings.
- Um app no Intuit Developer, para poder executar seu OAuth2 playground e obter um access token para essa empresa.
- Você sabe em qual ambiente a empresa está: production para uma empresa real, sandbox para uma empresa sandbox do Intuit Developer.
- Tempo para terminar sem demora após obter o token: o access token expira após 1 hora, então pegue-o por último, logo antes de preencher e testar.
Obter credenciais#
- Pegue o Realm ID dentro do próprio QuickBooks: entre no QuickBooks, clique no ícone de engrenagem ⚙ no canto superior direito, abra Account and settings, vá para Billing & subscription e copie o Company ID exibido ali: esse Company ID é o Realm ID.
- Pegue o access token no Intuit Developer: abra o Intuit Developer, abra seu app e abra seu OAuth2 playground.
- No OAuth2 playground, execute o fluxo OAuth2 para a mesma empresa e o mesmo ambiente (production ou sandbox) e copie o access token que ele retorna.
- Vá direto para a etapa de preenchimento: este access token expira após 1 hora. Atualizar um token usa o Client ID e o Client Secret desse mesmo app do Intuit Developer, então mantenha também esses valores do app à mão.
Preencher no Integration#
- Abra Integration → Marketplace → QuickBooks Online → Nova conexão.
- realm_id, obrigatório, Realm ID (Company ID): cole o Company ID copiado de QuickBooks → ícone de engrenagem ⚙ → Account and settings → Billing & subscription, por exemplo 123456789.
- environment, opcional, Environment: preencha production para uma empresa real, ou sandbox para uma empresa sandbox do Intuit Developer. Se deixar vazio, production é usado.
- access_token, obrigatório, Access token: cole o access token do Intuit Developer → seu app → OAuth2 playground, completo e de imediato, porque ele expira após 1 hora. É um campo do tipo senha e é guardado como segredo.
Testar a conexão#
Clique em Testar a conexão. Com seu token como credencial bearer, o teste lê as informações da sua empresa no QuickBooks: em production, chama as informações da empresa para seu realm_id e, em sandbox, usa o endereço sandbox. Uma resposta bem-sucedida retorna o nome da sua empresa, que é como você sabe que o token e o Realm ID pertencem à empresa esperada. Se realm_id estiver ausente, o teste para com MISSING_REALM_ID; se access_token estiver ausente, para com MISSING_TOKEN, sem enviar nenhuma solicitação. Uma resposta 401 é informada como INVALID_TOKEN: o token é inválido ou, o mais frequente, simplesmente passou da sua 1 hora. O teste aguarda 12 segundos antes de informar TEST_TIMEOUT.
Mapping / escolher modelo#
Escolha o mapping padrão do QuickBooks Online. Ele cobre os objetos com os quais esta conexão trabalha: pedidos de venda, clientes, faturas, produtos (items), pagamentos e quantidades de estoque por item. Depois que o teste aprovar, execute uma extração e confira um registro real lado a lado (um número de pedido ou de fatura, o cliente, as linhas e os valores) e envie um cliente ou um produto e confirme que ele aparece no QuickBooks, antes de ativar. Se um nome na sua empresa diferir do objeto padrão, ajuste esse campo no mapping em vez de renomear algo no QuickBooks.
Ativar#
Após ativar, a conexão traz pedidos de venda, clientes, faturas, produtos e pagamentos do QuickBooks Online na frequência definida, devolve clientes, faturas, produtos e pagamentos quando esses fluxos rodam, e responde às consultas de estoque por item. Acompanhe as primeiras execuções em Runs / Logs e compare com o QuickBooks antes de deixar a conexão sem supervisão.
Mantenha o token atualizado: ele expira após 1 hora, então quando uma execução começar a falhar com um erro de token, volte ao Intuit Developer → seu app → OAuth2 playground, pegue um access token novo para a mesma empresa e o mesmo ambiente, cole-o em access_token e teste novamente. Nada mais na conexão precisa mudar para uma renovação rotineira do token.
Perguntas frequentes#
O teste falha com INVALID_TOKEN (401)
O QuickBooks recusou o access token. A causa mais comum, de longe, é o tempo: o token expira após 1 hora, então um token que funcionava quando você o colou já pode estar expirado quando você testa ou quando uma execução posterior começa. Um token obtido para outra empresa ou outro ambiente é recusado da mesma forma.
Não mude realm_id ou environment primeiro. Vá ao Intuit Developer → seu app → OAuth2 playground, execute o fluxo novamente para a mesma empresa e o mesmo ambiente, cole o access token novo em access_token, salve e teste de novo imediatamente.
O teste para com MISSING_REALM_ID ou MISSING_TOKEN
Um dos dois valores de identificação está vazio, e o teste não envia nenhuma solicitação sem os dois. MISSING_REALM_ID significa que realm_id está vazio; MISSING_TOKEN significa que access_token está vazio — ou que o token que você colou foi cortado e nada utilizável foi salvo.
Preencha realm_id a partir de QuickBooks → ícone de engrenagem ⚙ → Account and settings → Billing & subscription → Company ID, e cole completo um access token novo do OAuth2 playground. Salve e teste novamente de imediato, antes que o token novo envelheça.
O teste falha com MISSING_SCOPE
O token foi aceito como token, mas não carrega o escopo contábil de que esta conexão precisa (com.intuit.quickbooks.accounting), então o QuickBooks não permite que ele leia as informações da empresa.
No OAuth2 playground, execute o fluxo novamente garantindo que o escopo contábil esteja incluído para seu app, copie o novo access token, cole-o em access_token e teste novamente.
O teste retorna um nome de empresa diferente do esperado
O token e o Realm ID não descrevem a mesma empresa. O nome de empresa no resultado do teste vem da empresa para a qual o token e o realm_id realmente apontam: muitas vezes uma empresa sandbox quando você esperava production, ou o token foi obtido no playground para outra empresa.
Confira os três valores juntos: realm_id da empresa pretendida em ícone de engrenagem ⚙ → Account and settings → Billing & subscription → Company ID, environment em production ou sandbox conforme essa empresa, e um token do playground executado para essa mesma empresa e esse mesmo ambiente. Corrija o que não bate e teste novamente.
Tudo funcionava, e uma hora depois as execuções começaram a falhar
Esse momento é a vida do token, não um mapping quebrado nem uma empresa mudada. O access token expira após 1 hora, então uma conexão que testou bem falhará em execuções posteriores com um erro de token até que um token novo seja colado.
Pegue um access token novo no Intuit Developer → seu app → OAuth2 playground para a mesma empresa e o mesmo ambiente, cole-o em access_token e teste. Atualizar um token usa o Client ID e o Client Secret desse app: mantenha esses valores do app prontos para a renovação ser rápida.
O teste informa TEST_TIMEOUT ou CONNECTION_FAILED
A solicitação de informações da empresa não terminou. TEST_TIMEOUT significa que nenhuma resposta completa chegou em 12 segundos; CONNECTION_FAILED significa que a solicitação ao QuickBooks não passou. Antes de culpar a rede por muito tempo, lembre a ordem de suspeita aqui: um token expirado ou de ambiente errado continua sendo a primeira coisa a descartar nesta conexão.
Primeiro cole um access token novo para a mesma empresa e verifique se environment combina com ele (production ou sandbox), depois teste novamente. Se um token novo e corretamente combinado continuar expirando, tente de novo após uma breve espera e confira Runs / Logs para o erro exato antes de mudar realm_id.