ComposioHQ/NetSuite-Automation

Automação NetSuite

Automatize operações do Oracle NetSuite ERP, incluindo criação de clientes e pedidos de venda, execução de consultas SuiteQL, upsert de registros por ID externo e inspeção de metadados de registros para gerenciamento empresarial abrangente.

Documentação do toolkit: composio.dev/toolkits/netsuite

---

Configuração

Esta skill requer o servidor MCP Rube conectado em https://rube.app/mcp.

Antes de executar qualquer ferramenta, certifique-se de que existe uma conexão ativa para o toolkit netsuite. Se nenhuma conexão estiver ativa, inicie uma via RUBE_MANAGE_CONNECTIONS.

---

Fluxos de Trabalho Principais

1. Criar Pedidos de Venda

Crie pedidos de clientes com itens de linha incluindo referências de itens, quantidades e preços.

Ferramenta: NETSUITE_CREATE_SALES_ORDER

Parâmetros Principais:

• entity (obrigatório) -- Referência do cliente: {"id": "<id_interno>"}
• item (obrigatório) -- Contêiner com array items, cada um contendo:
  • item (obrigatório) -- Referência do item: {"id": "<id_interno>"}
  • quantity (obrigatório) -- Unidades a pedir (não negativo)
  • rate -- Preço unitário (opcional se o item tiver preço padrão)
  • amount -- Valor total da linha (alternativa ao rate)
  • taxcode -- Referência do código de imposto: {"id": "<id_interno>"} (obrigatório se SuiteTax estiver ativado)
  • description -- Anotações do item de linha
• tranDate -- Data da transação no formato AAAA-MM-DD
• memo -- Memorando do cabeçalho
• orderStatus -- "A" (Aguardando Aprovação) ou "B" (Aguardando Atendimento)
• otherrefnum -- Referência externa ou número do pedido de compra

Exemplo:

Ferramenta: NETSUITE_CREATE_SALES_ORDER
Argumentos:
  entity: {"id": "1234"}
  item: {
    "items": [
      {"item": {"id": "56"}, "quantity": 10, "rate": 25.00},
      {"item": {"id": "78"}, "quantity": 5, "rate": 50.00}
    ]
  }
  tranDate: "2026-02-11"
  memo: "Pedido em lote Q1"
  orderStatus: "B"

---

2. Executar Consultas SuiteQL

Execute consultas SQL ad-hoc contra dados do NetSuite com paginação no servidor.

Ferramenta: NETSUITE_RUN_SUITEQL_QUERY

Parâmetros Principais:

• q (obrigatório) -- Instrução SELECT SuiteQL
• limit -- Linhas por página (padrão varia)
• offset -- Índice baseado em zero da primeira linha (deve ser múltiplo de limit)

Exemplos:

Ferramenta: NETSUITE_RUN_SUITEQL_QUERY
Argumentos:
  q: "SELECT id, companyname, email FROM customer WHERE isinactive = 'F' ORDER BY companyname"
  limit: 100
  offset: 0

Ferramenta: NETSUITE_RUN_SUITEQL_QUERY
Argumentos:
  q: "SELECT id, entitystatus, total FROM transaction WHERE type = 'SalesOrd' AND trandate >= '2026-01-01'"
  limit: 50

---

3. Criar e Gerenciar Clientes

Crie novos registros de cliente com atribuição de subsidiária e detalhes de contato.

Ferramentas:

• NETSUITE_CREATE_CUSTOMER -- Criar um novo cliente
• NETSUITE_GET_CUSTOMER -- Recuperar cliente por ID interno
• NETSUITE_UPDATE_CUSTOMER -- Atualizar cliente existente (semântica PATCH)

Parâmetros Principais para NETSUITE_CREATE_CUSTOMER:

• body (obrigatório) -- Objeto JSON com dados do cliente. Campos obrigatórios:
  • subsidiary -- Objeto com id (ID interno da subsidiária)
  • companyName (para empresas) ou firstName + lastName (para pessoas físicas)
  • Opcionais: email, phone, isPerson (definir como "T" para pessoas físicas), comments
• replace -- Nomes de sublistas separados por vírgula para substituir completamente (ex.: "contacts,addressbook")

Exemplo:

Ferramenta: NETSUITE_CREATE_CUSTOMER
Argumentos:
  body: {
    "companyName": "Acme Corp",
    "subsidiary": {"id": "1"},
    "email": "[email protected]",
    "phone": "555-0100"
  }

---

4. Upsert de Registros por ID Externo

Crie ou atualize registros de forma idempotente usando um identificador externo. Essencial para fluxos de sincronização.

Ferramenta: NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID

Parâmetros Principais:

• record_type (obrigatório) -- Nome do tipo de registro, ex.: "customer", "salesorder", "customrecord_myrec"
• external_id (obrigatório) -- Valor do ID externo (apenas letras, números, sublinhado, hífen)
• body (obrigatório) -- Objeto JSON correspondente ao esquema do registro; inclua campos obrigatórios ao criar

Exemplo:

Ferramenta: NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID
Argumentos:
  record_type: "customer"
  external_id: "CRM-CUST-42"
  body: {
    "companyName": "Acme Corp",
    "subsidiary": {"id": "1"},
    "email": "[email protected]"
  }

Aviso: A idempotência depende do uso consistente do ID externo. Inconsistências criam registros adicionais silenciosamente em vez de atualizar.

---

5. Inspecionar Metadados de Registro

Descubra campos disponíveis, tipos de dados, restrições e requisitos antes de criar ou atualizar registros.

Ferramenta: NETSUITE_GET_RECORD_METADATA

Parâmetros Principais:

• record_type (obrigatório) -- ex.: "customer", "salesorder", "invoice", "vendor", "employee", "item"
• accept -- "application/schema+json" (padrão, JSON Schema) ou "application/swagger+json" (OpenAPI 3.0)

Exemplo:

Ferramenta: NETSUITE_GET_RECORD_METADATA
Argumentos:
  record_type: "salesorder"

---

6. Listar e Filtrar Registros

Recupere múltiplos registros com filtros opcionais e paginação.

Ferramenta: NETSUITE_LIST_RECORDS

Parâmetros Principais:

• recordType (obrigatório) -- ex.: "customer", "salesorder"
• q -- Expressão de filtro usando operadores N/query, ex.: "email START_WITH \"barbara\""
• limit -- Máx. registros por página (1--1000, padrão 1000)
• offset -- Índice baseado em zero (deve ser divisível por limit)

Ferramentas de Apoio:

• NETSUITE_FILTER_RECORD_COLLECTION -- Filtragem alternativa (secundária ao SuiteQL)
• NETSUITE_GET_RECORD_SELECTED_FIELDS -- Recuperar apenas campos específicos (payload reduzido)

---

Plano de Execução Recomendado

1. Inspecione o esquema do registro usando NETSUITE_GET_RECORD_METADATA para descobrir campos obrigatórios
2. Pesquise registros existentes usando NETSUITE_RUN_SUITEQL_QUERY para evitar duplicatas
3. Consulte cliente por e-mail usando SuiteQL; busque detalhes com NETSUITE_GET_CUSTOMER se encontrado
4. Crie cliente se necessário usando NETSUITE_CREATE_CUSTOMER (certifique-se de definir subsidiary)
5. Valide IDs internos de itens usando NETSUITE_LIST_RECORDS ou SuiteQL
6. Crie o pedido de venda usando NETSUITE_CREATE_SALES_ORDER com referências validadas
7. Opcionalmente, faça upsert por ID externo usando NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID para fluxos de sincronização
8. Verifique os resultados usando NETSUITE_GET_RECORD_SELECTED_FIELDS para confirmar preços/totais

---

Armadilhas Conhecidas

Armadilha	Detalhe
IDs de item inválidos	NETSUITE_CREATE_SALES_ORDER lança USER_ERROR quando o ID interno do item é inválido. Pré-valide via NETSUITE_LIST_RECORDS ou NETSUITE_RUN_SUITEQL_QUERY.
Campos obrigatórios ausentes	NETSUITE_CREATE_CUSTOMER retorna 400 quando campos obrigatórios (ex.: subsidiary) estão faltando. Sempre inspecione com NETSUITE_GET_RECORD_METADATA primeiro.
Nomes de campos SuiteQL	Diferenças de consulta por conta podem causar resultados vazios. Confirme os nomes dos campos via NETSUITE_GET_RECORD_METADATA quando os resultados parecerem errados.
Limites de expressão de filtro	NETSUITE_FILTER_RECORD_COLLECTION pode falhar se a sintaxe do filtro não for suportada. Trate como secundário ao SuiteQL.
Idempotência de ID externo	NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID depende de IDs externos consistentes. Inconsistências criam duplicatas silenciosamente em vez de atualizar.
Itens de linha com SuiteTax	Contas com SuiteTax ativado exigem taxcode em cada item de linha. Omiti-lo causa falhas na criação.

---

Referência Rápida

Slug da Ferramenta	Descrição
NETSUITE_CREATE_SALES_ORDER	Criar um novo pedido de venda com itens de linha
NETSUITE_RUN_SUITEQL_QUERY	Executar consultas SuiteQL ad-hoc com paginação
NETSUITE_CREATE_CUSTOMER	Criar um novo registro de cliente
NETSUITE_GET_CUSTOMER	Recuperar um cliente por ID interno
NETSUITE_UPDATE_CUSTOMER	Atualizar um cliente existente (PATCH)
NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID	Criar ou atualizar um registro por ID externo
NETSUITE_GET_RECORD_METADATA	Inspecionar esquema do registro e definições de campo
NETSUITE_LIST_RECORDS	Listar registros com filtragem e paginação
NETSUITE_FILTER_RECORD_COLLECTION	Filtragem alternativa de registros
NETSUITE_GET_RECORD_SELECTED_FIELDS	Recuperar campos específicos de um registro

---

Fornecido por Composio