Conector NetSuite avançado no Jitterbit Design Studio
Introdução
Esta página aborda dicas de solução de problemas, tutoriais e funcionalidades avançadas relacionadas às integrações do NetSuite.
Solução de problemas e tutoriais
Esta seção descreve problemas e soluções alternativas para problemas comuns enfrentados com integrações do NetSuite e fornece informações sobre alterações do NetSuite que podem afetar sua integração.
URL WSDL específica da conta NetSuite
Durante a configuração de um endpoint NetSuite, você deve fornecer uma URL WSDL específica da conta no campo URL de download do WSDL. Esta seção mostra como obter essa URL encontrando o domínio específico da conta do NetSuite e, em seguida, usando o domínio específico da conta na URL WSDL.
Encontrando o domínio específico da conta NetSuite
Estas etapas devem ser executadas por um administrador do NetSuite ou outro usuário com a permissão Configurar empresa:
-
Efetue login na instância do NetSuite.
-
Vá para Configuração > Empresa > Informações da empresa (ou pesquise por Informações da empresa).
-
Na página Company Information, vá para a subguia Company URLs. O domínio específico da conta está sob o título SuiteTalk (SOAP and REST Web Services):
Para obter mais informações, consulte URLs para domínios específicos da conta.
Construindo a URL WSDL
Depois de obter o domínio específico da conta, use-o para construir o URL WSDL:
https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl
https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2024_1_0/netsuite.wsdl
https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2023_2_0/netsuite.wsdl
https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2023_1_0/netsuite.wsdl
https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2022_2_0/netsuite.wsdl
https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2022_1_0/netsuite.wsdl
Durante a configuração de um endpoint NetSuite, insira esta URL WSDL específica da conta no campo URL de download do WSDL.
Informações sobre quais versões do agente Jitterbit são necessárias para uso com as versões WSDL acima são fornecidas em Pré-requisitos no endpoint do conector NetSuite página.
Alterar a versão do WSDL
Atualizar periodicamente a versão WSDL usada pelo seu endpoint NetSuite para sempre usar uma versão totalmente suportada é uma boa prática recomendada. As etapas abaixo descrevem a melhor maneira de fazer a alteração, garantindo uma atualização perfeita.
-
Crie um novo endpoint.
-
Para cada operação do NetSuite, troque o endpoint antigo pelo novo.
-
Atualize a função.
-
Atualize as transformações.
-
Repita as etapas 2 a 4 para cada operação do NetSuite.
Nota
Embora seja possível simplesmente editar a URL WSDL de um endpoint existente e reconfigurar as atividades existentes, essa é uma prática desencorajada. Em tal cenário, nenhum erro de validade é relatado e é possível implantar o projeto, inadvertidamente substituindo operações bem-sucedidas por aquelas que falham no tempo de execução devido às incompatibilidades de WSDL dentro dos esquemas.
Erro no data center do NetSuite
Devido a alterações feitas pelo NetSuite, alguns formatos de URL WSDL que eram permitidos anteriormente não são mais aceitos, incluindo URLs WSDL genéricas e URLs específicas de data center. O Jitterbit recomenda sempre usar uma URL WSDL específica da conta.
Um endpoint NetSuite pode ter sido testado com sucesso anteriormente, mas agora falha com este erro:
Erro do conector: erro ao obter a URL do data center.
Causado por: org.jitterbit.integration.server.engine.connector.exception.NetSuiteWebServiceRuntimeException: FaultString:
Nesta conta, você deve usar domínios específicos da conta com este endpoint de serviços web SOAP. Você pode usar a operação SOAP getDataCenterUrls para obter o domínio correto. Ou vá para Configuração > Empresa > Informações da empresa na IU do NetSuite. Seus domínios são listados na aba URLs da empresa.
Em algumas circunstâncias, este erro pode aparecer:
Você não está solicitando o data center correto para sua empresa.
Esses erros podem resultar do uso de um URL de download WSDL incorreto na configuração de uma conexão NetSuite. Devido a alterações feitas pelo NetSuite, alguns formatos de URL WSDL que eram permitidos anteriormente não são mais aceitos, incluindo URLs WSDL genéricas e URLs específicas de data center. Por exemplo:
- URL WSDL genérico:
https://webservices.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl
- URL WSDL específica do data center:
https://webservices.na3.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl
Para resolver, altere o URL do WSDL para usar um domínio específico da conta:
- URL WSDL específica da conta:
https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl
Para obter instruções sobre como encontrar o domínio específico da conta NetSuite e, em seguida, usar o domínio específico da conta no URL WSDL, consulte URL WSDL específico da conta NetSuite.
Autenticação de dois fatores NetSuite (TFA ou 2FA)
Aqueles que usam a autenticação de dois fatores do NetSuite (TFA ou 2FA) não devem usar o tipo de autenticação de logon único (SSO) ao configurar seu endpoint do NetSuite no Jitterbit. Isso pode fazer com que seu endpoint NetSuite falhe. Em vez disso, é recomendado que esses usuários habilitem a autenticação baseada em token (TBA) em sua conta NetSuite e configurem seu endpoint NetSuite no Jitterbit adequadamente.
Nota
O tipo de autenticação SSO está sendo descontinuado pelo NetSuite e agora é recomendado que todos os usuários utilizem o TBA.
URL WSDL da sandbox do NetSuite
A partir de janeiro de 2018, o NetSuite usa a mesma URL para seus domínios de produção e sandbox. Para Design Studio e Agente versões 9.2 e superior, nenhuma ação é necessária para usuários do Jitterbit com endpoints NetSuite existentes configurados para o domínio sandbox, desde que o sandbox tenha sido atualizado desde essa alteração.
O número da conta NetSuite agora é usado para determinar se a conta está em produção ou sandbox. Por exemplo, o ID da conta pode ser anexado com _SB1, _SB2, etc. Como o NetSuite não usa mais uma URL de sandbox separada, e o sandbox agora é indicado pelo ID da conta, a caixa de seleção Sandbox foi removida nas versões 9.2 e superiores do Design Studio.
Se o seu sandbox do NetSuite não tiver sido atualizado desde que essas alterações do NetSuite foram implementadas, talvez seja necessário usar um URL WSDL específico do sandbox.
Dica
Mais informações podem ser encontradas na documentação do NetSuite Sobre contas de sandbox no domínio NetSuite.
Erro de permissão para TBA
Se você receber um INSUFFICIENT_PERMISSION
erro ao executar operações usando um endpoint NetSuite configurado com autenticação baseada em token (TBA), talvez seja necessário usar uma papel diferente para gerar os tokens de acesso ou adicionar permissões à papel que você está usando no momento. Nesse caso, o teste do endpoint parece bem-sucedido, mas, no tempo de execução da operação, a exceção ocorre.
Para resolver, ao gerar tokens de acesso, certifique-se de gerá-los em uma papel de Acesso Total ou Administrador ou certifique-se de que as permissões apropriadas sejam concedidas para a papel.
Dica
Instruções detalhadas estão disponíveis na documentação do NetSuite Introdução à autenticação baseada em token.
Erro inesperado para TBA
Se você receber um UNEXPECTED_ERROR
erro ao testar a conexão com um endpoint NetSuite configurado com autenticação baseada em token (TBA), é recomendado verificar para certificar-se de que você está usando o URL WSDL correto. O erro conterá o seguinte texto:
FaultString: Ocorreu um erro inesperado. O Suporte Técnico foi alertado sobre esse problema.
Este erro pode ocorrer por vários motivos; no entanto, sabe-se que esse erro é resultado de uma URL WSDL incorreta ao usar agentes que são versão 9.2 para 9.5. Na versão Agents 9.6 e superior, o texto da mensagem de erro descreve o problema com mais precisão.
Governança de simultaneidade do NetSuite
Em 18 de agosto de 2017, a Netsuite introduziu "Concurrency Governance" em sua versão 2017.2. Se você usa serviços web e/ou RESTlets, saiba mais sobre como isso pode afetar sua integração em NetSuite 2017.2 concurrency governança.
Limitações de pesquisa salvas do NetSuite
Ao usar a pesquisa salva do NetSuite, se você estiver tentando pesquisar em objetos que têm mais de 1.000 pesquisas salvas, pode aparecer no Jitterbit Studio como se não houvesse pesquisas salvas disponíveis no objeto. Nesse caso, o menu suspenso de pesquisa salva no Jitterbit Studio não será preenchido com nenhuma pesquisa salva. Isso ocorre devido a um limite de 1.000 registros imposto NetSuite em solicitações de API.
Confirmação de limitação
Para confirmar que o problema é com a limitação do NetSuite, você pode verificar o Web Services Usage Log dentro da sua instância do NetSuite. Para um erro desse tipo, o log terá uma entrada semelhante à seguinte:
<platformCore:code>MAX_RCRDS_EXCEEDED</platformCore:code>
<platformCore:message>The maximum number ( 1000 ) of records allowed for a READ operation has been exceeded.</platformCore:message>
Solução alternativa para limitação
Como solução alternativa, é recomendável limpar as pesquisas salvas do NetSuite que não estão mais sendo usadas para reduzir o número de pesquisas salvas para menos de 1.000. Após o número de pesquisas ser reduzido, você poderá selecionar uma pesquisa salva no menu suspenso no Jitterbit Studio.
Uma alternativa para reduzir o número de pesquisas salvas é executar a pesquisa salva via SOAP, referenciando a pesquisa salva por ID. Observe que esta alternativa não faz uso do conector NetSuite e pode resultar em problemas ao migrar ambientes.
Funcionalidade avançada
Esta seção fornece informações sobre os recursos do Jitterbit que permitem que você aproveite mais sua integração com o NetSuite.
Usando funções do NetSuite
Funções específicas do NetSuite disponíveis no Formula Builder em Funções > Funções do conector estão listadas abaixo. Para obter mais informações sobre como usar essas funções, consulte Funções do conector.
NetSuiteGetSelectValue
: Recupera os valores da lista de opções para um campo do NetSuite.NetSuiteGetServerTime
: Obtém o horário do servidor do NetSuite.NetSuiteLogin
: Obtém a sessão do NetSuite.
Usando a configuração assíncrona
Por padrão, as chamadas de API para o NetSuite são executadas de forma síncrona; ou seja, após uma solicitação ser feita, a conexão é mantida aberta. Se algumas solicitações expirarem durante uma pesquisa síncrona, você pode querer ativar a configuração assíncrona. Com essa configuração, após a solicitação ser enviada, o Jitterbit pesquisará periodicamente para ver se a solicitação foi concluída. Isso é mais útil com grandes quantidades de dados.
Para ativar a opção assíncrona, defina $jitterbit.netsuite.async=true
em um script que esteja, por exemplo, no início da operação ou dentro da cadeia de operação (veja Criando um script). Para obter informações adicionais, consulte a documentação do NetSuite em Processamento de solicitação síncrona versus assíncrona.
Passando valores nulos para campos personalizados
Uma limitação da API do NetSuite é que você não pode passar valores NULL ou em branco (string vazia) para campos personalizados no NetSuite.
De acordo com a documentação do NetSuite sobre CustomFieldList, os campos personalizados podem ser definidos como NULL enviando o campo no NetSuite nullFieldList
.
No Design Studio, você não verá nullFieldList
como um campo ou opção.
Em vez disso, você pode passar valores NULL ou em branco (string vazia) para campos personalizados mapeando o campo de origem para ambos externalId
e name
campos de um campo de destino.
Usando segmentos personalizados do NetSuite
Segmentos personalizados em objetos NetSuite padrão e personalizados são suportados para o NetSuite Connector Criar, Atualizar, ObterLista, Inserir, e Pesquisar atividades usando um endpoint NetSuite com um NetSuite WSDL que seja versão 2016.2 ou superior. Você deve estar usando versão 9.4 ou superior do Design Studio e do Agents para usar este recurso.
Ao configurar qualquer um dos tipos de atividade listados acima, você verá cada segmento personalizado exibido na estrutura de resposta ou solicitação do NetSuite:
Depois que a atividade for usada em uma transformação, você poderá mapear de ou para qualquer um desses segmentos personalizados, assim como faz para outros campos. Os segmentos personalizados estão localizados em um nó chamado customFieldList
que está presente dentro do seu respectivo nó de objeto.
Nota
Se seus segmentos personalizados não estiverem sendo exibidos, verifique se sua conta de usuário do NetSuite usada no seu endpoint do NetSuite tem as permissões apropriadas para interagir com o segmento personalizado e o objeto ao qual ele está associado.
Limitação
Em uma pesquisa avançada do NetSuite, segmentos personalizados do tipo Lista/Registro conforme definido no NetSuite não são suportados. No entanto, observe que o tipo Seleção Múltipla é suportado em uma Pesquisa avançada do NetSuite. Para determinar qual tipo está sendo usado, verifique o Tipo definido no NetSuite em seu Segmento Personalizado:
Essa limitação não se aplica a outros tipos de atividades do NetSuite; ou seja, os tipos Lista/Registro e Seleção Múltipla são suportados em Criar, Atualizar, ObterLista, Inserir, Pesquisa básica, Pesquisa expandida e Pesquisa salva atividades.
Usando a pesquisa de transações do NetSuite por status
Ao pesquisar transações do NetSuite com base em um status específico, você precisará especificar o valor correto do filtro de pesquisa que corresponde ao status desejado. Você pode determinar o valor do filtro de pesquisa correspondente conforme fornecido na tabela abaixo.
Por exemplo, se você quiser que os critérios de pesquisa limitem os registros de Item Fulfillment somente àqueles em que Ship Status = Shipped, em vez de usar o enum para Shipped (_shipped), você precisaria usar o valor a de ItemShip:C conforme fornecido na tabela abaixo. Traduções semelhantes se aplicam a uma variedade de objetos NetSuite.
Status | Filtro de Pesquisa |
---|---|
Venda à vista: Pagamento não aprovado | Venda à vista: A |
Venda à vista:Não depositado | Venda à vista:B |
Venda à vista:Depositado | Venda à vista:C |
Cheque:Anulado | Cheque:V |
Cheque: Pagamento de contas on-line pendente de aprovação contábil | Cheque: Z |
Comissão: Pagamento pendente | Comissão: A |
Comissão:Pagamento excessivo | Comissão:O |
Comissão:Aprovação de Contabilidade Pendente | Comissão:P |
Comissão: Rejeitado pela Contabilidade | Comissão: R |
Comissão:Pago integralmente | Comissão:X |
Declaração de cobrança:Aberto | CustChrg:A |
Cobrança de extrato: pago integralmente | Cobrança de cliente: B |
Nota de crédito: Aberto | CustCred: A |
Nota de crédito: totalmente aplicada | CustCred: B |
Depósito do cliente: Não depositado | CustDep: A |
Depósito do cliente: Depositado | CustDep: B |
Depósito do cliente: Totalmente aplicado | CustDep: C |
Fatura:Aberta | ClienteInvc:A |
Fatura: Pago integralmente | CustInvc: B |
Pagamento: Pagamento não aprovado | CustPymt: A |
Pagamento: Não depositado | CustPymt: B |
Pagamento: Depositado | CustPymt: C |
Reembolso do cliente: anulado | Resposta do cliente: V |
Cotação:Aberto | Estimativa:A |
Cotação:Processado | Estimativa:B |
Cotação:Fechado | Estimativa:C |
Citação:Anulada | Estimativa:V |
Cotação:Expirado | Estimativa:X |
Relatório de Despesas: Em andamento | ExpRept: A |
Relatório de Despesas: Aguardando Aprovação do Supervisor | ExpRept:B |
Relatório de Despesas: Aprovação Contábil Pendente | ExpRept:C |
Relatório de Despesas: Rejeitado pelo Supervisor | ExpRept: D |
Relatório de Despesas: Rejeitado pela Contabilidade | ExpRept: E |
Relatório de Despesas: Aprovado pela Contabilidade | ExpRept: F |
Relatório de Despesas: Aprovado (Substituído) pela Contabilidade | ExpRept:G |
Relatório de Despesas: Rejeitado (Substituído) pela Contabilidade | ExpRept:H |
Relatório de Despesas: Pago na Integralidade | ExpRept: I |
Contagem de inventário:Aberto | InvCount:A |
Contagem de inventário:Iniciado | InvCount:B |
Contagem de inventário: Concluído/Aprovação pendente | InvCount: C |
Contagem de inventário: Aprovado | InvCount: D |
Atendimento do item: Selecionado | Item Enviado: A |
Atendimento do item: embalado | Envio do item: B |
Atendimento do item: Enviado | ItemEnviado: C |
Revista:Aprovação pendente | Revista:A |
Diário:Aprovado para publicação | Diário:B |
Cheque de Responsabilidade da Folha de Pagamento: Anulado | LiabPymt:V |
Oportunidade:Em andamento | Oportunidade:A |
Oportunidade: Estimativa emitida | Oportunidade: B |
Oportunidade:Fechada - Ganha | Oportunidade:C |
Oportunidade:Fechada - Perdida | Oportunidade:D |
Salário:Indefinido | Salário:A |
Salário:Cálculo de imposto pendente | Salário:C |
Salário: Compromisso Pendente | Salário: D |
Salário:Comprometido | Salário:F |
Salário:Prévia | Salário:P |
Salário:Revertido | Salário:R |
Ordem de compra: Aguardando aprovação do supervisor | Ordem de compra: A |
Ordem de compra:Recebimento pendente | Ordem de compra:B |
Ordem de compra: Rejeitada pelo supervisor | Ordem de compra: C |
Ordem de compra: parcialmente recebida | Ordem de compra: D |
Ordem de compra:Faturamento pendente/Recebido parcialmente | Ordem de compra:E |
Ordem de compra:Fatura pendente | Ordem de compra:F |
Ordem de compra: Totalmente faturada | Ordem de compra: G |
Ordem de compra:Fechada | Ordem de compra:H |
Autorização de Retorno: Aprovação Pendente | RtnAuth:A |
Autorização de devolução:Recibo pendente | RtnAuth:B |
Autorização de Retorno:Cancelado | RtnAuth:C |
Autorização de Retorno: Parcialmente Recebida | RtnAuth: D |
Autorização de devolução: Reembolso pendente/Recebido parcialmente | RtnAuth:E |
Autorização de devolução: Reembolso pendente | RtnAuth:F |
Autorização de devolução: Reembolsado | RtnAuth: G |
Autorização de Retorno:Fechado | RtnAuth:H |
Ordem de venda: Aprovação pendente | Ordem de venda: A |
Ordem de venda:Aguardando atendimento | OrdemVenda:B |
Ordem de venda: Cancelada | OrdemVenda: C |
Ordem de venda: parcialmente atendida | Ordem de venda: D |
Ordem de venda: Faturamento pendente/Parcialmente atendido | OrdemDeVenda:E |
Ordem de venda: Faturamento pendente | OrdemDeVenda: F |
Ordem de venda:Faturada | OrdemVenda:G |
Ordem de venda:Fechada | OrdemVenda:H |
Cheque de Responsabilidade Fiscal: Anulado | TaxLiab: V |
Pagamento de imposto sobre vendas: anulado | TaxPymt:V |
Pagamento de imposto sobre vendas: Pagamento de contas on-line pendente de aprovação contábil | TaxPymt:Z |
Tegata a pagar:Endossado | TegPybl:E |
Tegata a Pagar:Emitido | TegPybl:Eu |
Tegata Pagável:Pago | TegPybl:P |
Contas a Receber Tegata: Cobrado | TegRcvbl:C |
Tegata Receivables:Descontado | TegRcvbl:D |
Recebíveis Tegata: Aprovado | TegRcvbl:E |
Contas a Receber Tegata: Holding | TegRcvbl:H |
Ordem de Transferência: Aprovação Pendente | TrnfrOrd:A |
Ordem de Transferência:Aguardando Cumprimento | TrnfrOrd:B |
Ordem de Transferência: Rejeitada | TrnfrOrd: C |
Ordem de Transferência: Parcialmente Cumprida | TrnfrOrd: D |
Ordem de Transferência: Recebimento Pendente/Parcialmente Cumprido | TrnfrOrd:E |
Ordem de Transferência:Recebimento Pendente | TrnfrOrd:F |
Ordem de Transferência:Recebido | TrnfrOrd:G |
Ordem de Transferência:Fechada | TrnfrOrd:H |
Autorização de devolução do fornecedor: Aprovação pendente | VendAuth:A |
Autorização de devolução do fornecedor: Devolução pendente | VendAuth:B |
Autorização de devolução do fornecedor: Cancelado | VendAuth: C |
Autorização de devolução do fornecedor: parcialmente devolvido | VendAuth:D |
Autorização de devolução do fornecedor: Crédito pendente/Devolvido parcialmente | VendAuth:E |
Autorização de devolução do fornecedor: Crédito pendente | VendAuth:F |
Autorização de devolução do fornecedor:Credenciado | VendAuth:G |
Autorização de devolução do fornecedor:Fechado | VendAuth:H |
Conta:Aberta | VendBill:A |
Conta:Pago integralmente | VendBill:B |
Bill:Cancelado | VendBill:C |
Bill:Aprovação pendente | VendBill:D |
Bill: Rejeitado | VendBill: E |
Pagamento em dinheiro: Anulado | VendPymt: V |
Pagamento em dinheiro: Pagamento de contas on-line pendente de aprovação contábil | VendPymt:Z |
Ordem de serviço: Construção pendente | Ordem de serviço: B |
Ordem de Serviço:Cancelado | Ordem de Serviço:C |
Ordem de Serviço: Em Processo | Ordem de Serviço: D |
Ordem de Serviço:Construído | Ordem de Serviço:G |
Ordem de Serviço:Fechada | Ordem de Serviço:H |
Fonte: http://blog.prolecto.com/2013/08/30/netsuite-searchfilter-transaction-internal-status-list/
Padrões de design
Os seguintes padrões de design podem ser úteis para integrações do NetSuite:
-
Capturando alterações de dados com uma API do API Manager ou endpoint HTTP
-
Capturando alterações de dados com valores de campo de origem
-
Capturar alterações de dados com alterações de tabela ou arquivo
-
Capturando alterações de dados com consultas baseadas em timestamp
-
Vinculando registros de origem ou destino usando IDs compartilhados
-
Dados persistentes para processamento posterior usando Armazenamento Temporário
-
Executando as próximas operações condicionalmente usando cadeias de operação