Atividades de Consulta do Conector QuickBooks¶

Antes de poder consultar dados QuickBooks do Jitterbit, você precisará ter criado um endpoint QuickBooks no Jitterbit Studio (consulte QuickBooks Connector OAuth 1.0a - Criar Endpoint ou QuickBooks Connector 2.0 - Criar Endpoint). Agora que o Jitterbit tem acesso à sua instância do QuickBooks Online, você pode realizar quatro atividades principais com os dados do QuickBooks : Consultar, Criar, Atualizar ou Excluir.

Esta página se concentra na consulta de dados QuickBooks, usando um exemplo de consulta de dados QuickBooks existentes em um cliente específico por meio de um arquivo XML por meio do Jitterbit. Essas etapas são divididas em iniciar a atividade de Consulta, definir os componentes da Operação e implantar e executar a Operação.

Criando uma Operação de Consulta QuickBooks¶

1. Dentro do seu projeto no Jitterbit Studio, existem várias maneiras de iniciar uma nova atividade de consulta do QuickBooks. Cada uma das opções a seguir iniciará o Assistente de consulta QuickBooks para guiá-lo durante o processo.

   • Vá para Arquivo > Novo > Conectores > Nova consulta QuickBooks.
   • Na árvore à esquerda em Conectores, clique com o botão direito na categoria QuickBooks e selecione Nova consulta de QuickBooks.
   • Na árvore à esquerda em Conectores, clique duas vezes na categoria QuickBooks, clique com o botão direito em Atividades de consulta de QuickBooks e selecione Nova consulta de QuickBooks.
   • Na barra de ferramentas superior, clique no ícone do conector (peça de quebra-cabeça laranja) . No pop-up, selecione QuickBooks e selecione Consulta QuickBooks.

2. A tela Endpoint do QuickBooks Query Wizard solicita que você selecione o endpoint do qual deseja consultar os dados. Você já deve ter configurado endpoints em QuickBooks Connector OAuth 1.0a - Create Endpoint ou QuickBooks Connector 2.0 - Criar Endpoint. Selecione o endpoint apropriado, por exemplo, um endpoint de sandbox ou de produção. Clique em Avançar quando terminar.

   Nota

   O exemplo usado nesta documentação consulta um conjunto de dados de amostra fornecidos em cada nova sandbox do QuickBooks. Para acessar sua sandbox, vá para https://developer.intuit.com/ e faça login em sua conta QuickBooks Online. Depois de fazer login, acesse Documentos e ferramentas > Sandbox > Vá para empresa para ver o sandbox que deseja usar. Dentro da sandbox você verá os dados de amostra disponíveis para fins de teste.

   

3. A tela Object do QuickBooks Query Wizard solicita que você selecione o objeto que deseja consultar. Neste exemplo, usamos a API de contabilidade durante a criação do aplicativo QuickBooks Online e, portanto, temos apenas um objeto para selecionar: Contabilidade. Clique no objeto e depois clique em Avançar para continuar.

   

4. A tela Component do QuickBooks Query Wizard exibe todos os componentes que estão disponíveis para serem consultados em sua instância QuickBooks conectada. Para fins deste passo a passo, consultar um Cliente e, portanto, selecionaremos o componente Cliente. Em seguida, clique no botão Concluir.

   

5. O Jitterbit Studio prosseguirá com a criação de uma estrutura de solicitação e resposta da API QuickBooks que permitirá que os dados sejam consultados em sua instância conectada do QuickBooks Online. Uma nova aba deve aparecer no Studio chamada Atividades de consulta do QuickBooks. Você pode renomear sua consultar aqui, se desejar; no exemplo, o nosso é chamado de "Consulta de QuickBooks do cliente".

   Clique no ícone + na extremidade direita das visualizações da estrutura Solicitação e Resposta para expandir todos os elementos dentro de cada estrutura. Com cada lado agora expandido, você deverá ver uma tela semelhante à imagem mostrada abaixo.

   

6. Em seguida, na mesma tela, clique no botão Criar Operação localizado em Usar em uma Integração no canto superior direito. Isso criará a operação Jitterbit que consultar QuickBooks em busca de dados do cliente.

7. Uma nova aba deverá abrir no Studio chamada Operations, contendo uma representação gráfica da atividade Query. Salve sua operação clicando no ícone de disco único para salvar apenas esta operação ou no ícone de vários discos para salvar todas as alterações em seu projeto de integração. Você deverá ver o asterisco na aba Operações e o título da Operação desaparecer à medida que sua nova atividade de consulta for criada e salva em seu projeto.

Definindo os Componentes da Operação¶

Agora precisamos definir os outros componentes da Operação que aparecem na representação gráfica, incluindo Fonte, Solicitação, Resposta e Destino. Para fins deste passo a passo, fornecemos os seguintes exemplos para referência acima: Jitterpak QuickBooksExample.jpk e arquivos acompanhantes QuickBooksSampleRequestFiles.zip.

• Fonte (opcional): No exemplo, o XML a seguir é uma solicitação de entrada para buscar um Cliente com o primeiro nome, ou GivenName como é conhecido em QuickBooks, de 'Mark':

  CustomerQueryRequest.xml

  <ns:INPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions">
  <Customer>
  <Fields></Fields>
  <Condition>GivenName='Mark'</Condition>
  </Customer>
  </ns:INPUT>
  

  Nota

  No exemplo acima, os Campos são deixados em branco, o que irá buscar todos os campos do Cliente. Se apenas alguns campos forem necessários, use um delimitador "," (vírgula) entre os nomes dos campos (por exemplo, campo1,campo2,campo3). Em seguida, para aplicar Condições à consultar, especifique a cláusula desejada em Condições como no exemplo abaixo.

  A partir da versão 8.25, o campo Condição também pode conter uma cláusula ORDERBY e/ou as palavras-chave STARTPOSITION e MAXRESULTS individualmente ou em combinação. Por exemplo:

  <Fields>Name,GivenName,FullyQualifiedName,AccountType</Fields> <Condition>GivenName='Mark' ORDERBY Name STARTPOSITION 0 MAXRESULTS 10</Condition>

  Para usar o arquivo XML, primeiro clique duas vezes no ícone Fonte e selecione um novo tipo de Fonte. Neste exemplo, estamos usando um Agente Privado com arquivos locais habilitados e, portanto, selecione um Tipo de "Arquivo Local" e, em seguida, Procurar até o local. Se você estiver usando os arquivos de exemplo e extraídos para o local recomendado C:\, a Pasta será 'C:\projects\quickbooks' e Obter Arquivos será 'CustomerQueryRequest.xml'.

  Nota

  Você pode optar por ignorar o uso de uma Fonte clicando com o botão direito do mouse no ícone Fonte e selecionando Remover do Gráfico. Se você fizer isso, ao especificar a solicitação, escolha uma origem como "Nenhum" e, em vez disso, poderá clicar duas vezes nas variáveis no lado direito (lado do destino) do mapeamento para especificar valores. Essas opções mais avançadas são abordadas em Transformações.

• Alvo: Clique duas vezes no ícone Alvo. No exemplo, queremos gravar em um arquivo XML com a saída da consultar, então selecionaremos novamente um Tipo de "Arquivo Local" e Navegar até um local no Agente Privado onde queremos salve os dados. No exemplo, a Pasta é 'C:\projects\quickbooks' e o Nome do arquivo é 'CustomerQueryResponse.xml'.

• Solicitação: Clique duas vezes no ícone Solicitação e selecione Criar Nova Transformação. Ou clique no botão Criar solicitação na aba Atividades de consulta do QuickBooks. Isso abrirá o Assistente de Transformação, que orientará você na criação da Solicitação.

  1. Na primeira tela, Nome, selecione o tipo de fonte usado acima. Para o exemplo escolhemos XML. Deixe o Destino como padrão.
  2. Na próxima tela, Fonte, escolha o botão para Selecionar uma estrutura XML existente. No menu suspenso, selecione “Esquemas QuickBooks ”. Em seguida, selecione 'QuickBooksQueryRequest.xsd' para usar como seu arquivo de estrutura. Na próxima tela, clique em Concluir.
  3. A aba Transformações deve abrir onde você pode completar seu mapeamento. Clique e arraste "Campos" do lado esquerdo (lado de origem) para "Campos" no lado direito (lado de destino). Faça o mesmo com “Condição”. Sua tela de mapeamento agora deve ser semelhante à mostrada abaixo.

• Resposta: Clique duas vezes no ícone Resposta e selecione Criar Nova Transformação. Ou clique no botão Criar resposta na aba Atividades de consulta do QuickBooks. Isso abrirá o Assistente de Transformação, que orientará você na criação da Resposta.

  1. Na primeira tela, Nome, selecione o tipo de alvo usado acima. Para o exemplo escolhemos XML. Deixe a Fonte como padrão.
  2. Na próxima tela, Fonte, escolha o botão para Selecionar uma estrutura XML existente. No menu suspenso, selecione “Esquemas QuickBooks ”. Em seguida, selecione 'QuickBooksQueryResponse.xsd' para usar como seu arquivo de estrutura. Na próxima tela, clique em Concluir.
  3. A aba Transformações deve abrir onde você pode completar seu mapeamento. Clique no + na parte inferior de cada lado da origem e do lado do destino para expandir os itens em cada árvore. Clique e arraste a pasta "OUTPUT" do lado esquerdo (lado de origem) para a pasta "OUTPUT" do lado direito (lado de destino). Sua tela de mapeamento agora deve ser semelhante à mostrada abaixo.

Implantando e Executando a Operação¶

Com a atividade de consulta QuickBooks configurada, estamos prontos para implantar e executar a operação.

Na aba Operações, clique em Implantar ícone. Em seguida, clique em Executar ícone para colocar a Operação na fila para execução.

Na parte inferior da tela, o monitor de Operação deverá indicar que sua Operação foi executada com sucesso. Caso contrário, você pode clicar duas vezes no ícone Status para visualizar quaisquer mensagens de log.

Agora você também deve ver a saída da consultar gerada no destino especificado. Por exemplo, o arquivo agora é criado em 'C:\projects\quickbooks\CustomerQueryResponse.xml':

title-"CustomerQueryResponse.xml" <ns:OUTPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions"> <ns:Customer> <ns:Id>17</ns:Id> <ns:SyncToken>0</ns:SyncToken> <ns:MetaData> <ns:CreateTime>2017-09-17T18:12:16-06:00</ns:CreateTime> <ns:LastUpdatedTime>2017-09-25T13:57:24-06:00</ns:LastUpdatedTime> </ns:MetaData> <ns:GivenName>Mark</ns:GivenName> <ns:FamilyName>Cho</ns:FamilyName> <ns:FullyQualifiedName>Mark Cho</ns:FullyQualifiedName> <ns:DisplayName>Mark Cho</ns:DisplayName> <ns:PrintOnCheckName>Mark Cho</ns:PrintOnCheckName> <ns:Active>1</ns:Active> <ns:PrimaryPhone> <ns:FreeFormNumber>(650) 554-1479</ns:FreeFormNumber> </ns:PrimaryPhone> <ns:PrimaryEmailAddr> <ns:Address>Mark@Cho.com</ns:Address> </ns:PrimaryEmailAddr> <ns:Taxable>0</ns:Taxable> <ns:BillAddr> <ns:Id>17</ns:Id> <ns:Line1>36 Willow Rd</ns:Line1> <ns:City>Menlo Park</ns:City> <ns:CountrySubDivisionCode>CA</ns:CountrySubDivisionCode> <ns:PostalCode>94304</ns:PostalCode> <ns:Lat>37.450412</ns:Lat> <ns:Long>-122.170593</ns:Long> </ns:BillAddr> <ns:ShipAddr> <ns:Id>17</ns:Id> <ns:Line1>36 Willow Rd</ns:Line1> <ns:City>Menlo Park</ns:City> <ns:CountrySubDivisionCode>CA</ns:CountrySubDivisionCode> <ns:PostalCode>94304</ns:PostalCode> <ns:Lat>37.450412</ns:Lat> <ns:Long>-122.170593</ns:Long> </ns:ShipAddr> <ns:Job>0</ns:Job> <ns:BillWithParent>0</ns:BillWithParent> <ns:Balance>314.28</ns:Balance> <ns:BalanceWithJobs>314.28</ns:BalanceWithJobs> <ns:CurrencyRef name="United States Dollar">USD</ns:CurrencyRef> <ns:PreferredDeliveryMethod>Print</ns:PreferredDeliveryMethod> </ns:Customer> </ns:OUTPUT>