Conector REST do NetSuite

Documentação da API

O REST API Browser do NetSuite documenta os endpoints de registros, e a referência do SuiteQL documenta a linguagem de consulta que este conector usa para extrair dados tabulares.

Dica

Para um passo a passo completo — configuração no lado do NetSuite, criação da conexão, teste e montagem da etapa de extração — siga o guia Conectar ao NetSuite. Esta página é a referência de campos e receitas por trás dele.

Como funciona a autenticação

O conector se autentica com credenciais de cliente OAuth 2.0 usando uma declaração de cliente JWT PS256; não há login interativo nem token de atualização. Você gera um par de chaves RSA, envia o certificado público ao NetSuite e fornece ao PlaidCloud a chave privada correspondente mais três IDs. A cada extração, o PlaidCloud cria e assina uma declaração de curta duração, troca-a por um token de acesso e chama a API REST.

Cuidado

Os detalhes de função, escopo e permissão abaixo seguem o formato documentado do NetSuite e são confirmados na virada para produção. Se uma troca de token ou uma consulta for rejeitada, o erro do NetSuite exibido indica a causa (escopo, função ou consulta), para que você ajuste exatamente esse ponto.

Configuração no lado do NetSuite

Faça isto no NetSuite antes de criar a conexão no PlaidCloud. É necessário ser administrador, e esta etapa está no caminho crítico.

1. Ative o recurso

Ative OAuth 2.0 e SuiteTalk (SOAP and REST Web Services) em Setup > Company > Enable Features > SuiteCloud.

2. Crie o par de chaves RSA

Gere um par de chaves RSA de 2048 bits (ou maior) com um digest compatível com PS256. Por exemplo, com o OpenSSL:

openssl genrsa -out plaidcloud_netsuite.pem 2048
openssl rsa -in plaidcloud_netsuite.pem -pubout -out plaidcloud_netsuite_public.pem

Mantenha a chave privada (plaidcloud_netsuite.pem) em segredo: ela vai para o PlaidCloud, nunca para o NetSuite.

3. Envie o certificado público → ID do certificado

Em Setup > Integration > OAuth 2.0 Client Credentials (M2M) Setup, associe o certificado público a uma integração, uma entidade e uma função. O NetSuite retorna um ID do certificado para a chave pública enviada; ele é o kid do JWT e não é um segredo. Anote-o.

4. Crie o registro de integração → ID do cliente

Em Setup > Integration > Manage Integrations > New, crie uma integração com OAuth 2.0 ativado e a concessão Client Credentials selecionada. O NetSuite emite um ID do cliente (consumer key). Anote-o. Não há segredo do cliente no fluxo de credenciais de cliente com declaração.

5. Função e permissões

Atribua à função usada no mapeamento M2M um conjunto de permissões que cubra o que você vai ler:

• REST Web Services (Setup) — necessária para qualquer chamada REST.
• SuiteAnalytics Workbook — necessária se o seu SuiteQL acessar dados de análise/workbook.
• Log in using OAuth 2.0 Access Tokens — necessária para a troca de token.
• Permissões de visualização em nível de registro para todo tipo de registro que suas consultas leem (transações, contas, entidades e assim por diante).

6. ID da conta

Encontre o ID da sua conta em Setup > Company > Company Information (o campo Account ID). Ele define o host da API:

Ambiente	Formato do ID da conta	Host da API
Produção	1234567	1234567.suitetalk.api.netsuite.com
Sandbox	1234567_SB1	1234567-sb1.suitetalk.api.netsuite.com

O PlaidCloud deriva o host do ID da conta automaticamente (convertendo para minúsculas e trocando _ por -). Informe o ID da conta exatamente como o NetSuite o mostra, incluindo o sufixo _SB1 em um sandbox.

Configuração

Crie a conexão com o tipo de conexão NetSuite (não com o tipo REST genérico: somente o tipo NetSuite deriva o host e injeta o comportamento de paginação do SuiteQL). Estes campos aparecem no formulário:

Identificação

Campo	Tipo	Descrição
Nome	Texto	Nome de exibição desta conexão.
Alias	Texto (várias linhas)	Alias ou observações opcionais sobre a conexão.
Está ativa	Alternância	Indica se a conexão está ativada. Desative para pausá-la sem excluí-la.
Banco somente leitura	Alternância	Restringe a conexão a operações somente leitura.
Tipo de acesso	Seleção	Nível de acesso desta conexão: somente leitura, somente gravação ou leitura e gravação.

Credenciais do NetSuite

Campo	Tipo	Descrição
ID do cliente	Texto	O ID do cliente do registro de integração (etapa 4).
ID do certificado	Texto	O ID do certificado (kid do JWT) retornado quando você enviou o certificado público (etapa 3). Não é um segredo.
ID da conta do NetSuite	Texto	O ID da conta (etapa 6), por exemplo 1234567 ou 1234567_SB1.
Certificado privado do NetSuite	Texto (PEM)	A chave privada (etapa 2), colada como um bloco PEM completo de várias linhas. Armazenada de forma criptografada e nunca retornada em texto claro.

Nota

O campo Certificado privado do NetSuite oculta a chave enquanto você a cola. Ele fica em branco quando você reabre uma conexão salva: deixe-o em branco para manter a chave salva ou cole uma nova para substituí-la.

Extrair dados com SuiteQL

A API de registros do NetSuite retorna apenas {id, links} por linha, por isso o PlaidCloud extrai dados tabulares com SuiteQL por meio da etapa Solicitação REST. Configure a etapa com a conexão do NetSuite:

• Método — POST
• Endpoint — /services/rest/query/v1/suiteql (o caminho literal; o host vem da conexão)
• Corpo — a consulta em JSON: {"q": "SELECT ... FROM ... ORDER BY internalid"}

Cuidado

Sempre use um ORDER BY determinístico em uma consulta SuiteQL paginada por deslocamento (por exemplo, ORDER BY internalid). O NetSuite pagina por deslocamento numérico; sem uma ordenação estável, as páginas duplicam e pulam linhas silenciosamente, o que faz os totais financeiros não fecharem.

Não configure a paginação nem os cabeçalhos à mão

Em uma conexão do NetSuite, a etapa injeta automaticamente os detalhes do SuiteQL:

• Os cabeçalhos Prefer: transient e Content-Type: application/json.
• Paginação por deslocamento sobre os campos items / hasMore da resposta, com o tamanho de página fixado pelo serviço.

Não mexa nos controles de Paginação e análise nem nesses cabeçalhos: a conexão os define. Defina apenas o Endpoint, o Corpo e as colunas (abaixo).

Defina o tipo das colunas de valor e de data

O SuiteQL retorna todos os valores como strings JSON ("1234.56", "2026-01-15", "T"). Defina manualmente as colunas de saída com seus tipos reais — Currency/Decimal para valores, Date/Datetime para datas, Boolean para os indicadores "T"/"F" — e o PlaidCloud converte as strings em colunas tipadas ao gravá-las na tabela. Strings vazias viram null. (A detecção automática de esquema não aplica a configuração de serviço da conexão, então não consegue fazer isso por você: defina as colunas você mesmo.)

Cuidado

O SuiteQL retorna datas no formato de exibição da conta (geralmente M/D/YYYY), que é ambíguo, por isso o PlaidCloud não tenta adivinhá-lo. Para uma coluna Date/Datetime, formate o campo na consulta com TO_CHAR(col, 'YYYY-MM-DD') (ou 'YYYY-MM-DD HH24:MI:SS') ou deixe a coluna como Text. Um valor que não pode ser convertido faz a execução falhar com uma mensagem que indica a coluna e o valor.

Limitações conhecidas

Limitação	O que significa
Colunas manuais obrigatórias	A detecção automática de esquema não aplica a configuração de serviço do NetSuite, então defina à mão as colunas de valor, data e booleanas e seus tipos.
A paginação é fixada pelo serviço	O modo de paginação, os caminhos e o tamanho da página são definidos pela conexão e não podem ser ajustados na etapa.
Apenas substituição da tabela inteira	Cada extração relê todo o resultado; não há caminho incremental/delta. Uma extração agendada relê a tabela inteira a cada execução, então limite a cláusula WHERE ao recorte de que você precisa.
Multimoeda / subsidiárias	Em transaction/transactionline, amount está na moeda própria da transação. Um SUM(amount) simples entre subsidiárias está errado para fins de consolidação: selecione campos consolidados ou convertidos pela taxa de câmbio ao totalizar entre subsidiárias.
Limite de ~100.000 linhas no SuiteQL	O NetSuite limita uma única consulta a cerca de 100.000 linhas sem o SuiteAnalytics Connect. Uma consulta escrita à mão que ultrapasse esse limite falha com clareza, com uma mensagem pedindo um intervalo de datas menor ou outros filtros, em vez de truncar silenciosamente. As etapas prontas NetSuite: Importar saldos / NetSuite: Importar detalhes do razão geral dividem o intervalo de datas em janelas automaticamente para ficar abaixo desse limite.
Contabilidade multilivro	Em uma conta com Multi-Book Accounting, TransactionAccountingLine traz uma linha por livro para cada linha de transação; um SUM sem filtro entre livros conta em dobro (ou N vezes). As etapas de importação prontas usam o livro principal por padrão; uma consulta escrita à mão deve filtrar accountingbook = 1 (ou o livro que você escolher) explicitamente, a menos que um total entre livros seja realmente o que você quer.
Envelope da resposta	O envelope exato da resposta e o escopo/função aceitos são confirmados na virada para produção; o conector segue o formato documentado do NetSuite.

Consultas de exemplo

Financeira — linhas de transação do razão geral para um período, tipadas e ordenadas:

SELECT
    tl.transaction   AS transaction_id,
    t.trandate       AS tran_date,
    a.acctnumber     AS account_number,
    tl.subsidiary    AS subsidiary_id,
    tl.foreignamount AS amount
FROM   transactionline tl
JOIN   transaction     t ON t.id = tl.transaction
JOIN   account         a ON a.id = tl.expenseaccount
WHERE  t.trandate BETWEEN TO_DATE('2026-01-01', 'YYYY-MM-DD')
                      AND TO_DATE('2026-01-31', 'YYYY-MM-DD')
ORDER BY tl.transaction, tl.id

Operacional — pedidos de venda em aberto por cliente:

SELECT
    so.tranid        AS order_number,
    so.entity        AS customer_id,
    so.trandate      AS order_date,
    so.status        AS order_status
FROM   transaction so
WHERE  so.type = 'SalesOrd'
  AND  so.status = 'SalesOrd:B'
ORDER BY so.id

Conectar ao NetSuite (guia)Passo a passo: configuração no lado do NetSuite, criação e teste da conexão e montagem de uma extração SuiteQL financeira e de uma operacional.

Analisar as finanças do NetSuite (tutorial)Passo a passo do primeiro dia: extraia o razão geral e transforme-o em uma DRE mensal e em um aging de contas a receber.

Exemplos de consultas SuiteQL do NetSuiteConsultas para copiar e colar: lançamentos contábeis, balancete, DRE, balanço patrimonial, contas a receber em aberto, pedidos de venda, pedidos de compra e estoque.