ComposioHQ/NetSuite-Automation

NetSuite 자동화

Oracle NetSuite ERP 작업을 자동화합니다. 고객 및 판매 주문 생성, SuiteQL 쿼리 실행, 외부 ID로 레코드 Upsert, 레코드 메타데이터 조회 등을 통해 포괄적인 비즈니스 관리를 수행합니다.

툴킷 문서: composio.dev/toolkits/netsuite

---

설정

이 스킬을 사용하려면 https://rube.app/mcp에 연결된 Rube MCP 서버가 필요합니다.

도구를 실행하기 전에 netsuite 툴킷에 대한 활성 연결이 있어야 합니다. 활성 연결이 없으면 RUBE_MANAGE_CONNECTIONS를 통해 새 연결을 시작하세요.

---

핵심 워크플로우

1. 판매 주문 생성

품목 참조, 수량, 가격 정보가 포함된 라인 항목으로 고객 주문을 생성합니다.

도구: NETSUITE_CREATE_SALES_ORDER

주요 매개변수:

• entity (필수) -- 고객 참조: {"id": "<내부_ID>"}
• item (필수) -- items 배열을 포함하는 컨테이너, 각 항목:
  • item (필수) -- 품목 참조: {"id": "<내부_ID>"}
  • quantity (필수) -- 주문 수량 (음수 불가)
  • rate -- 단가 (품목에 기본 가격이 있으면 선택 사항)
  • amount -- 총 라인 금액 (rate 대체 가능)
  • taxcode -- 세금 코드 참조: {"id": "<내부_ID>"} (SuiteTax 활성화 시 필수)
  • description -- 라인 항목 메모
• tranDate -- 거래일 (YYYY-MM-DD 형식)
• memo -- 헤더 메모
• orderStatus -- "A" (승인 대기) 또는 "B" (이행 대기)
• otherrefnum -- 외부 참조 또는 구매 주문 번호

예시:

도구: NETSUITE_CREATE_SALES_ORDER
인수:
  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: "1분기 대량 주문"
  orderStatus: "B"

---

2. SuiteQL 쿼리 실행

서버 측 페이징을 지원하는 임시 SQL 쿼리를 NetSuite 데이터에 대해 실행합니다.

도구: NETSUITE_RUN_SUITEQL_QUERY

주요 매개변수:

• q (필수) -- SuiteQL SELECT 문
• limit -- 페이지당 행 수 (기본값은 다양함)
• offset -- 첫 번째 행의 0 기반 인덱스 (limit의 배수여야 함)

예시:

도구: NETSUITE_RUN_SUITEQL_QUERY
인수:
  q: "SELECT id, companyname, email FROM customer WHERE isinactive = 'F' ORDER BY companyname"
  limit: 100
  offset: 0

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

---

3. 고객 생성 및 관리

자회사 할당 및 연락처 세부 정보를 포함한 새 고객 레코드를 생성합니다.

도구:

• NETSUITE_CREATE_CUSTOMER -- 새 고객 생성
• NETSUITE_GET_CUSTOMER -- 내부 ID로 고객 조회
• NETSUITE_UPDATE_CUSTOMER -- 기존 고객 업데이트 (PATCH 방식)

NETSUITE_CREATE_CUSTOMER 주요 매개변수:

• body (필수) -- 고객 데이터가 포함된 JSON 객체. 필수 필드:
  • subsidiary -- id (자회사 내부 ID)를 포함한 객체
  • companyName (법인) 또는 firstName + lastName (개인) 중 하나
  • 선택 사항: email, phone, isPerson (개인인 경우 "T"로 설정), comments
• replace -- 완전히 교체할 하위 목록 이름 (쉼표로 구분, 예: "contacts,addressbook")

예시:

도구: NETSUITE_CREATE_CUSTOMER
인수:
  body: {
    "companyName": "Acme Corp",
    "subsidiary": {"id": "1"},
    "email": "[email protected]",
    "phone": "555-0100"
  }

---

4. 외부 ID로 레코드 Upsert

외부 식별자를 사용하여 레코드를 멱등적으로 생성하거나 업데이트합니다. 동기화 워크플로우에 필수적입니다.

도구: NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID

주요 매개변수:

• record_type (필수) -- 레코드 유형 이름, 예: "customer", "salesorder", "customrecord_myrec"
• external_id (필수) -- 외부 ID 값 (영문자, 숫자, 밑줄, 하이픈만 사용 가능)
• body (필수) -- 레코드 스키마와 일치하는 JSON 객체; 생성 시 필수 필드를 포함해야 함

예시:

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

경고: 멱등성은 일관된 외부 ID 사용에 달려 있습니다. 불일치 시 업데이트 대신 추가 레코드가 생성될 수 있습니다.

---

5. 레코드 메타데이터 조회

레코드를 생성하거나 업데이트하기 전에 사용 가능한 필드, 데이터 유형, 제약 조건 및 요구 사항을 확인합니다.

도구: NETSUITE_GET_RECORD_METADATA

주요 매개변수:

• record_type (필수) -- 예: "customer", "salesorder", "invoice", "vendor", "employee", "item"
• accept -- "application/schema+json" (기본값, JSON Schema) 또는 "application/swagger+json" (OpenAPI 3.0)

예시:

도구: NETSUITE_GET_RECORD_METADATA
인수:
  record_type: "salesorder"

---

6. 레코드 목록 조회 및 필터링

선택적 필터링 및 페이징을 사용하여 여러 레코드를 검색합니다.

도구: NETSUITE_LIST_RECORDS

주요 매개변수:

• recordType (필수) -- 예: "customer", "salesorder"
• q -- N/query 연산자를 사용한 필터 표현식, 예: "email START_WITH \"barbara\""
• limit -- 페이지당 최대 레코드 수 (1~1000, 기본값 1000)
• offset -- 0 기반 인덱스 (limit으로 나누어 떨어져야 함)

보조 도구:

• NETSUITE_FILTER_RECORD_COLLECTION -- 대체 필터링 (SuiteQL에 비해 보조적)
• NETSUITE_GET_RECORD_SELECTED_FIELDS -- 특정 필드만 검색 (페이로드 감소)

---

권장 실행 계획

1. NETSUITE_GET_RECORD_METADATA를 사용하여 레코드 스키마를 조사하여 필수 필드를 파악합니다.
2. NETSUITE_RUN_SUITEQL_QUERY를 사용하여 기존 레코드를 검색하여 중복을 방지합니다.
3. SuiteQL로 이메일을 통해 고객을 조회합니다. 발견되면 NETSUITE_GET_CUSTOMER로 세부 정보를 가져옵니다.
4. 필요 시 NETSUITE_CREATE_CUSTOMER를 사용하여 고객을 생성합니다 (subsidiary 설정 확인).
5. NETSUITE_LIST_RECORDS 또는 SuiteQL을 사용하여 품목 내부 ID를 검증합니다.
6. 검증된 참조를 사용하여 NETSUITE_CREATE_SALES_ORDER로 판매 주문을 생성합니다.
7. 동기화 워크플로우의 경우 NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID를 사용하여 선택적으로 외부 ID로 Upsert합니다.
8. NETSUITE_GET_RECORD_SELECTED_FIELDS를 사용하여 결과를 확인하고 가격/합계를 확인합니다.

---

알려진 문제점

문제점	설명
잘못된 품목 ID	NETSUITE_CREATE_SALES_ORDER가 품목 내부 ID가 잘못된 경우 USER_ERROR를 발생시킵니다. NETSUITE_LIST_RECORDS 또는 NETSUITE_RUN_SUITEQL_QUERY로 사전 검증하세요.
필수 필드 누락	NETSUITE_CREATE_CUSTOMER가 필수 필드(예: subsidiary) 누락 시 400 오류를 반환합니다. 항상 NETSUITE_GET_RECORD_METADATA로 먼저 조사하세요.
SuiteQL 필드 이름	계정별 쿼리 차이로 인해 결과가 비어 있을 수 있습니다. 결과가 이상할 때 NETSUITE_GET_RECORD_METADATA로 필드 이름을 확인하세요.
필터 표현식 제한	NETSUITE_FILTER_RECORD_COLLECTION이 지원되지 않는 필터 구문으로 실패할 수 있습니다. SuiteQL에 비해 보조적으로 사용하세요.
외부 ID 멱등성	NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID는 일관된 외부 ID에 의존합니다. 불일치 시 업데이트 대신 중복 레코드가 생성됩니다.
SuiteTax 라인 항목	SuiteTax가 활성화된 계정은 모든 라인 항목에 taxcode가 필요합니다. 누락 시 생성이 실패합니다.

---

빠른 참조

도구 슬러그	설명
NETSUITE_CREATE_SALES_ORDER	라인 항목이 포함된 새 판매 주문 생성
NETSUITE_RUN_SUITEQL_QUERY	페이징 지원 임시 SuiteQL 쿼리 실행
NETSUITE_CREATE_CUSTOMER	새 고객 레코드 생성
NETSUITE_GET_CUSTOMER	내부 ID로 고객 조회
NETSUITE_UPDATE_CUSTOMER	기존 고객 업데이트 (PATCH)
NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID	외부 ID로 레코드 생성 또는 업데이트
NETSUITE_GET_RECORD_METADATA	레코드 스키마 및 필드 정의 조회
NETSUITE_LIST_RECORDS	필터링 및 페이징으로 레코드 목록 조회
NETSUITE_FILTER_RECORD_COLLECTION	대체 레코드 필터링
NETSUITE_GET_RECORD_SELECTED_FIELDS	레코드에서 특정 필드 검색

---

Composio 제공