Solução de problemas do NetSuite

Erros de conexão

Erro no data center

• Sintoma: Uma conexão NetSuite que anteriormente foi testada com sucesso agora falha com este erro:

  Connector Error: Error getting the data center URL.

  Caused by: org.jitterbit.integration.server.engine.connector.exception.NetSuiteWebServiceRuntimeException: FaultString:

  In this account, you must use account-specific domains with this SOAP web services endpoint. You can use the SOAP getDataCenterUrls operation to obtain the correct domain. Or, go to Setup > Company > Company Information in the NetSuite UI. Your domains are listed on the Company URLs tab.

  Em algumas circunstâncias, este erro pode aparecer:

  You are not requesting the correct data center for your company.

• Causa: 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 específicas do data center. Por exemplo:

  • URL WSDL genérica: https://webservices.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
  • URL WSDL específica do data center: https://webservices.na3.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl

• Solução alternativa: Altere a 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/v2025_1_0/netsuite.wsdl

  Para obter instruções sobre como encontrar o domínio específico da conta NetSuite e usá-lo na URL WSDL, consulte Use um URL WSDL específico da conta NetSuite.

Permissões insuficientes

• Sintoma: Mesmo que o teste de uma conexão NetSuite seja bem-sucedido, você pode receber um erro INSUFFICIENT_PERMISSION ao executar operações que contêm atividades que usam essa conexão.
• Solução alternativa: Ao gerar tokens de acesso, use um papel com Acesso Total ou Administrador, ou garanta que as permissões apropriadas estejam habilitadas para o papel utilizado. Instruções detalhadas estão disponíveis na documentação do NetSuite Getting Started with Token-based Authentication.

Falha na conexão do sandbox após uma atualização do sandbox

• Sintoma: Uma conexão NetSuite configurada para uma conta de sandbox do NetSuite falha com um erro de autenticação depois que o ambiente de sandbox é atualizado.
• Causa: Cada vez que um sandbox do NetSuite é atualizado, todos os tokens de autenticação baseada em token (TBA) associados a esse sandbox são invalidados. A conexão continua usando os tokens antigos, que não são mais aceitos pelo NetSuite.
• Resolução: Depois de cada atualização do sandbox, gere novos tokens de TBA para a conta de sandbox e atualize os campos Chave do token e Segredo do token na conexão NetSuite. Para instruções sobre como obter novos valores de token, consulte Coletar valores para usar o TBA do NetSuite.

Problemas de esquema e de campos

Campos personalizados não aparecem no esquema da atividade

• Sintoma: Campos personalizados de um objeto do NetSuite não estão presentes no esquema de transformação em um agente privado, mesmo que esses campos existam no NetSuite.
• Causa: O conector NetSuite expõe campos personalizados para muitos objetos por padrão, mas alguns objetos exigem configuração explícita no arquivo de configuração do conector NetSuite do agente.
• Resolução: Adicione o objeto ao arquivo de configuração netsuiteconfig.xml no agente privado. Consulte Expor campos personalizados no conector NetSuite para instruções completas, incluindo como lidar com objetos com mais de 1.000 campos personalizados.

Segmentos personalizados não aparecem ou não são suportados em pesquisas avançadas

• Sintoma: Segmentos personalizados não estão visíveis no esquema da atividade, ou segmentos personalizados do tipo Lista/Registro não estão disponíveis em uma pesquisa avançada.
• Causa: Segmentos personalizados exigem permissões específicas na conta de usuário do NetSuite. Além disso, o tipo de segmento Lista/Registro não é suportado em pesquisas avançadas: apenas o tipo Múltipla Seleção é.
• Resolução: Consulte Segmentos personalizados na página da atividade de Pesquisa do NetSuite para requisitos de permissão e limitações conhecidas.

Campos personalizados do corpo não visíveis devido a permissão de função ausente

• Sintoma: Campos personalizados do corpo de transações (por exemplo, campos adicionados a um registro Sales Order ou outro registro de transação) não aparecem no esquema de saída da atividade de Pesquisa do NetSuite, mesmo que os campos existam na instância do NetSuite e o teste de conexão seja bem-sucedido.
• Possível causa: O papel do NetSuite usado pela integração não tem permissão de View para Custom Body Fields. O conector NetSuite chama a ação SOAP getList para recuperar as definições de campos personalizados; uma violação de permissão nessa chamada faz com que os campos sejam totalmente omitidos do esquema.
• Resolução:
  1. Na sua conta do NetSuite, abra o papel atribuído ao usuário de integração e conceda pelo menos acesso de View à permissão Custom Body Fields.
  2. Salve o papel e aguarde alguns minutos para que a alteração de permissão tenha efeito.
  3. No Studio, crie uma nova atividade de Pesquisa do NetSuite ou importe o projeto para um novo ambiente de projeto para limpar o esquema em cache. Os campos personalizados do corpo devem agora aparecer no esquema de saída.

Erros de configuração de atividade

Pesquisas salvas não aparecem no menu suspenso

• Sintoma: Ao configurar uma atividade de Pesquisa do NetSuite usando um tipo de pesquisa Pesquisa Salva, o menu suspenso Selecionar uma Pesquisa Salva aparece vazio ou não lista todas as pesquisas salvas esperadas.
• Causa: A API do NetSuite limita as respostas a 1.000 registros por solicitação. Quando um objeto tem mais de 1.000 pesquisas salvas, o menu suspenso não consegue listar todas elas e pode aparecer vazio.
• Resolução: Use a opção Fornecer ID do Script da Pesquisa Salva para ignorar o menu suspenso:
  1. Na seção Selecionar uma Pesquisa Salva da configuração da atividade, selecione Fornecer ID do Script da Pesquisa Salva.
  2. Insira diretamente o ID do script da pesquisa salva de destino. O ID do script pode ser encontrado na interface do NetSuite, na página de detalhes da pesquisa salva.

Pesquisa expandida: O botão Testar Consulta está desativado

• Sintoma: Ao configurar uma pesquisa expandida na atividade de Pesquisa do NetSuite, o botão Testar Consulta aparece acinzentado e não pode ser clicado.
• Causa: Uma pesquisa expandida requer uma condição de consulta em um objeto relacionado. O botão Testar Consulta é desativado quando nenhuma condição em um objeto relacionado foi adicionada.
• Resolução: Adicione pelo menos uma condição que filtre em um objeto relacionado. Se a pesquisa precisar filtrar apenas nos próprios campos do objeto atual, use o tipo Pesquisa Básica em vez de uma pesquisa expandida.

Campos de fórmula da pesquisa salva estão ausentes na saída da atividade

• Sintoma: Uma atividade de Pesquisa do NetSuite que usa uma pesquisa salva retorna a contagem de registros esperada em Testar Consulta, mas colunas baseadas em fórmula ou de junção complexa (por exemplo, campos customSearchJoin) estão ausentes na saída da atividade e no mapeamento da transformação, mesmo que essas colunas apareçam na pesquisa salva na interface do NetSuite.
• Causa: Colunas de pesquisa salva baseadas em fórmula são calculadas no nível da interface do NetSuite e não estão incluídas na resposta SOAP que o conector lê. Como resultado, esses valores não aparecem na saída da atividade mesmo que a pesquisa retorne registros.
• Resolução:
  1. Quando possível, reconstrua a pesquisa salva usando campos armazenados (não baseados em fórmula), já que valores calculados por fórmula podem não ser retornados pela API.
  2. No Studio, abra a atividade de Pesquisa do NetSuite e, na primeira página de configuração, selecione a opção Pesquisa Salva (usar definição de pesquisa reutilizável anteriormente salva no NetSuite).
  3. Selecione a pesquisa salva no menu suspenso Selecionar uma Pesquisa Salva.
  4. Percorra as páginas restantes e execute a operação para recuperar os dados completos.

Testar Consulta retorna erro de análise quando o filtro usa uma variável de projeto

• Sintoma: Quando um filtro de uma atividade de Pesquisa do NetSuite usa uma variável de projeto para um valor de data ou data/hora (como lastModifiedDate), clicar em Testar Consulta na configuração da atividade retorna um erro 500 referenciando um formato de data inválido. A mesma operação é executada com sucesso em tempo de execução.

  Connector Error: FaultString: java.text.ParseException: Invalid dateTime format: [lastModifiedDate]
  

• Causa: Testar Consulta não resolve variáveis de projeto. Ele envia a referência literal da variável (por exemplo, [lastModifiedDate]) como o valor do filtro, que o NetSuite rejeita como uma data inválida. Em tempo de execução, o agente substitui o valor real da variável, então a própria operação é bem-sucedida.

• Resolução: Para testar ou salvar alterações na atividade sem remover a variável, adicione um valor padrão temporário à referência da variável na condição de filtro:
  1. No filtro, altere a referência da variável de [my_date_variable] para [my_date_variable{2023-01-01T00:00:00.000Z}] (usando a data/hora ISO 8601 apropriada como padrão).
  2. Clique em Testar Consulta. O teste agora é bem-sucedido porque uma data válida é substituída no lugar da variável não resolvida.
  3. Salve quaisquer outras alterações na atividade. O valor padrão pode permanecer; em tempo de execução, o agente sempre usa o valor atual da variável de projeto.

Pesquisa Salva com campos de resultado como saída requer agente 11.49 ou posterior

• Sintoma: Na atividade de Pesquisa do NetSuite, a opção Pesquisa Salva com campos de resultado como saída está visível na interface da atividade, mas as operações que a utilizam falham com um erro 500 quando executadas em um agente privado mais antigo.
• Causa: O recurso Pesquisa Salva com campos de resultado como saída foi introduzido na versão 11.49 do agente. Agentes privados em versões anteriores exibem a opção na interface, mas não têm suporte em tempo de execução para executá-la.
• Resolução:
  1. Confirme a versão do agente na página Agentes do Management Console.
  2. Atualize os agentes privados para a versão 11.49 ou posterior para usar essa opção. Os agentes de nuvem são mantidos atualizados automaticamente.
  3. Se não for possível atualizar o agente privado, reconfigure a atividade para usar Pesquisa Salva em vez disso. Esse modo é suportado em versões de agente anteriores.

A atividade Atualização retorna INVALID_KEY_OR_REF quando o XML de origem perde internalId

• Sintoma: Uma atividade Atualização do NetSuite é concluída sem gerar uma exceção, mas nenhum registro é atualizado no NetSuite. O payload de resposta contém o status SOAP INVALID_KEY_OR_REF. O problema geralmente aparece quando um script de transformação usa GetXMLString para construir o payload de atualização a partir de uma resposta de pesquisa anterior.

  <writeResponse>
    <platformCore:status isSuccess="false">
      <platformCore:statusDetail type="ERROR">
        <platformCore:code>INVALID_KEY_OR_REF</platformCore:code>
        <platformCore:message>The specified key is invalid.</platformCore:message>
      </platformCore:statusDetail>
    </platformCore:status>
    <baseRef>
      <platformCore:RecordRef type="invoice"></platformCore:RecordRef>
    </baseRef>
  </writeResponse>
  

• Causa: GetXMLString serializa um nó XML, mas não preserva atributos no elemento raiz. Quando o internalId do registro de origem é mantido como um atributo no nó raiz do registro do NetSuite (por exemplo, no elemento Invoice), ele é removido da string resultante e a atividade Atualização vê uma referência de registro vazia.

• Resolução: Capture o internalId do registro de origem separadamente e, em seguida, adicione-o de volta ao XML serializado antes de passar o payload para a atividade Atualização:

  1. No script de transformação, atribua o internalId de origem a uma variável.
  2. Chame GetXMLString para construir o XML do registro.

  3. Use Replace para injetar internalId="..." no elemento raiz. Para um registro Invoice:

     <trans>
     $invoiceInternalId = searchResponse$searchResult$recordList$record.Invoice$internalId;
     $MyRecord = GetXMLString([searchResponse$searchResult$recordList$record.]);
     $MyRecord = Replace($MyRecord, "<Invoice>", '<Invoice internalId="' + $invoiceInternalId + '">');
     </trans>
     

  4. Passe MyRecord para a próxima etapa.

Desempenho e limites de registro

Operações falham devido aos limites de registro da API do NetSuite

• Sintoma: Uma operação que usa o conector NetSuite falha ou processa menos registros do que o esperado porque os dados de origem excedem o limite de registros por chamada imposto pela API do NetSuite.
• Causa: A API do NetSuite impõe limitações de tamanho no número de registros por solicitação. Quando mais registros são enviados em uma única chamada do que o limite permite, o NetSuite rejeita o excesso.
• Resolução:
  1. Habilite o particionamento na operação em Opções de operação. Quando a origem é uma atividade do NetSuite, o particionamento divide os dados durante a transformação, e não na recuperação. Cada pedaço é gravado em um arquivo temporário e os arquivos são combinados no destino final depois que todos os pedaços são processados.
  2. Quando o destino é uma atividade do NetSuite, cada pedaço de origem produz um pedaço de destino, com a transformação aplicada separadamente a cada um. Os pedaços de destino resultantes são então combinados.
  3. Para instruções e melhores práticas, consulte Habilitar Chunking.
  4. Para referência mais detalhada, consulte Informações detalhadas sobre chunking.

Operações falham devido ao limite de solicitações simultâneas

• Sintoma: Operações de alto volume do NetSuite falham com um dos seguintes erros:
  • Solicitações RESTlet: HTTP error code: 400 Bad Request / SuiteScript error code: SSS_REQUEST_LIMIT_EXCEEDED
  • Solicitações de serviços web: ExceededConcurrentRequestLimitFault ou ExceededRequestLimitFault
• Causa: O NetSuite impõe governança de simultaneidade por conta, limitando o total combinado de solicitações simultâneas de serviços web e RESTlet. O limite depende do seu nível de serviço e do número de licenças SuiteCloud Plus. Por exemplo, o Nível de Serviço 1 com cinco licenças SuiteCloud Plus permite 65 solicitações simultâneas (15 + (5 × 10)). Exceder esse limite faz com que o NetSuite rejeite o excesso de solicitações.
• Resolução:
  1. Para agentes privados, defina MaxNumberOfOperationThreads na seção [OperationEngine] do arquivo jitterbit.conf para um valor que mantenha o total de solicitações simultâneas do NetSuite dentro do limite de governança da sua conta.
  2. Projete as operações para serializar solicitações quando possível, ou implemente lógica de nova tentativa que aguarde e tente novamente quando a resposta WS_CONCUR_SESSION_DISALLOWED for recebida.
  3. Revise seus aplicativos cliente NetSuite para confirmar que eles lidam com os códigos de erro de simultaneidade adequadamente.
  4. Para mais detalhes sobre os limites de governança por nível, consulte as notas de versão do NetSuite 2017.2 (páginas 71 e 72).

Alterações de versão e esquema

Operações falham após atualizar a URL WSDL do NetSuite

• Sintoma: Depois de atualizar a URL de download do WSDL em uma conexão NetSuite para referenciar uma versão mais recente do WSDL, todas as operações que usam as atividades dessa conexão falham em tempo de execução.
• Causa: Alterar a URL de download do WSDL atualiza a conexão, mas não atualiza os esquemas de dados usados pelas transformações existentes. As transformações continuam referenciando campos de esquema da versão anterior do WSDL, que são incompatíveis com a nova versão.
• Resolução: Para atualizar a versão do WSDL corretamente, siga as etapas em Alterar a versão do WSDL. Este procedimento atualiza tanto a URL da conexão quanto os esquemas de dados usados por todas as atividades afetadas, evitando falhas em tempo de execução causadas por incompatibilidades de esquema.