NetSuite에 연결

SuiteQL을 사용해 NetSuite의 재무 및 운영 데이터를 PlaidCloud 테이블로 가져옵니다. 이 가이드는 비어 있는 NetSuite 통합에서 시작하여 예약된 형식 지정 가져오기까지 안내합니다. 세부 필드 참조는 NetSuite REST 커넥터를 참조하십시오.

사전 요구 사항

NetSuite에서 다음이 필요합니다.

• OAuth 2.0 및 REST Web Services가 활성화되어 있어야 합니다(Setup > Company > Enable Features > SuiteCloud).
• RSA 키 쌍: 공개 인증서는 NetSuite에 업로드하고 개인 키는 PlaidCloud용으로 보관합니다.
• 인증서 ID(공개 인증서를 업로드하면 얻는 JWT kid), 클라이언트 ID(통합 레코드에서 확인), 계정 ID(운영 환경은 1234567, 샌드박스는 1234567_SB1).
• REST Web Services, Log in using OAuth 2.0 Access Tokens, SuiteAnalytics Workbook(쿼리가 분석 데이터를 사용하는 경우), 그리고 읽으려는 레코드에 대한 보기 권한이 있는 역할.

키 쌍 생성, 인증서 업로드, 통합 생성 등 NetSuite 쪽 전체 절차는 참조 문서의 NetSuite 측 설정에 있습니다. 먼저 해당 절차를 완료하십시오. 이 가이드는 네 가지 값을 이미 가지고 있다고 가정합니다.

주의

계정 ID는 NetSuite에 표시된 그대로 입력하고, 샌드박스의 경우 _SB1 접미사를 반드시 포함하십시오. PlaidCloud는 이 값으로 API 호스트를 결정하므로 형식이 잘못되면 가져오기가 엉뚱한 계정을 가리키게 됩니다.

연결 만들기

1. Tools > Connections를 열고 New Connection을 클릭합니다.

2. 메뉴에서 NetSuite를 선택합니다.

   주의

   일반 REST 유형이 아니라 NetSuite를 선택하십시오. NetSuite 유형만 계정 ID에서 API 호스트를 결정하고 SuiteQL 헤더와 페이징을 자동으로 추가합니다. 일반 REST 연결은 인증 없이 실행되어 실패합니다.

3. 필드를 입력합니다.

   필드	값
   이름	알기 쉬운 이름(예: NetSuite Prod).
   클라이언트 ID	통합 레코드의 클라이언트 ID.
   인증서 ID	공개 인증서 업로드로 얻은 인증서 ID(kid).
   NetSuite 계정 ID	계정 ID(예: 1234567 또는 1234567_SB1).
   NetSuite 개인 인증서	개인 키 PEM 블록 전체(여러 줄로 붙여넣기).

4. Create를 클릭합니다.

참고

NetSuite 개인 인증서 필드는 붙여넣는 동안 키를 가리며, 저장된 키는 암호화되어 다시 표시되지 않습니다. 연결을 편집할 때 이 필드는 비어 있습니다. 저장된 키를 유지하려면 비워 두고, 교체하려면 새 키를 붙여넣으십시오.

팁

계정 ID에 따라 연결이 도달하는 NetSuite 인스턴스가 결정되므로 샌드박스 계정 ID에는 _SB1 접미사를 유지하십시오(예: 1234567_SB1). 연결 이름에 어느 인스턴스를 가리키는지 나타내거나, 운영 호스트와 샌드박스 호스트를 하나의 연결 아래 두 환경으로 두십시오.

연결 스모크 테스트

그 위에 무언가를 구축하기 전에 자격 증명이 작동하는지 확인합니다.

1. 워크플로에 REST 요청 단계를 추가합니다.

2. 요청 탭에서 연결을 NetSuite 연결로, 메서드를 POST로, 엔드포인트를 /services/rest/query/v1/suiteql로 설정합니다.

3. 본문에 범위가 작은 간단한 쿼리를 입력합니다.

   {"q": "SELECT id FROM account WHERE ROWNUM <= 1"}

4. 테스트 요청 보내기를 클릭합니다.

주의

미리보기 탭이 아니라 테스트 요청 보내기를 사용하십시오. 미리보기 탭은 연결의 서비스 구성을 적용하지 않아 잘못된 결과를 보고합니다. 테스트 요청이 성공(녹색)하면 JWT 서명, 토큰 교환, NetSuite 응답이 모두 정상이라는 뜻입니다. 오류가 나면 메시지에 NetSuite의 상세 내용이 담겨 있으며, 대개 범위, 역할 또는 쿼리 문제입니다. 해당 부분 하나를 고친 후 다시 테스트하십시오.

가져오기 단계 구성

스모크 테스트가 성공했으면 단계를 실제 가져오기로 전환합니다.

1. 본문에 결정적인 ORDER BY를 포함한 SuiteQL 쿼리를 작성합니다. 분개 항목, 시산표, 손익계산서, 재무상태표, 미수금, 판매 주문, 구매 주문, 재고 등 복사해서 바로 쓸 수 있는 예시는 NetSuite SuiteQL 쿼리 예시를 참조하십시오.

   재무 — 기간별 총계정원장 거래 라인:

   {"q": "SELECT tl.transaction AS transaction_id, TO_CHAR(t.trandate, 'YYYY-MM-DD') 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"}

   운영 — 고객별 미결 판매 주문:

   {"q": "SELECT so.tranid AS order_number, so.entity AS customer_id, TO_CHAR(so.trandate, 'YYYY-MM-DD') AS order_date, so.status AS order_status FROM transaction so WHERE so.type = 'SalesOrd' AND so.status = 'SalesOrd:B' ORDER BY so.id"}

2. 페이징 및 파싱 컨트롤과 Prefer/Content-Type 헤더는 그대로 두십시오. NetSuite 연결이 자동으로 추가합니다.

3. 응답 탭에서 대상을 테이블로 유지하고 열을 실제 형식으로 정의합니다. 금액에는 Currency/Decimal, 날짜에는 Date/Datetime, T/F 플래그에는 Boolean을 사용합니다. SuiteQL은 모든 값을 문자열로 반환하므로, 형식이 지정된 열이 PlaidCloud에 값을 변환하는 방법을 알려 줍니다.

   주의

   SuiteQL은 날짜를 계정의 표시 형식(대개 M/D/YYYY)의 텍스트로 반환하는데 이 형식은 모호하므로 PlaidCloud는 추측하지 않습니다. Date/Datetime 형식으로 지정하는 열은 쿼리에서 날짜 형식을 지정하거나(TO_CHAR(trandate, 'YYYY-MM-DD') AS trandate, 날짜 및 시간은 'YYYY-MM-DD HH24:MI:SS'), 열을 Text로 두십시오. 숫자와 T/F 플래그는 이런 처리가 필요 없습니다. 값을 변환할 수 없으면 실행이 실패하고 열과 값을 알려 주는 메시지가 표시됩니다.

주의

ORDER BY가 없으면 오프셋 페이징에서 페이지 사이에 행이 조용히 중복되거나 누락됩니다. 조정하기 전에는 알 수 없는 재무 불일치로 이어집니다. 페이징하는 모든 SuiteQL 쿼리에는 ORDER BY internalid 같은 안정적인 정렬이 필요합니다.

주의

행 한도: NetSuite는 SuiteAnalytics Connect가 없으면 단일 SuiteQL 쿼리를 약 100,000행으로 제한합니다. 이 한도를 넘는 직접 작성한 쿼리는 결과를 조용히 잘라 반환하는 대신, 날짜 범위나 다른 필터를 좁히라는 메시지와 함께 실패합니다. 넓은 범위의 가져오기는 날짜 범위로 나누어 요청하여 한도 이내로 유지하거나, 날짜 범위를 자동으로 나누어 처리하는 기본 제공 NetSuite: 잔액 가져오기 / 총계정원장 상세 단계를 사용하십시오.

주의

다중 통화: transaction/transactionline의 amount는 각 거래의 자체 통화 기준입니다. 자회사 전체에 걸친 SUM(amount)는 연결 기준으로 올바르지 않습니다. 자회사 전체를 합산할 때는 연결 금액 또는 환율 변환 필드를 선택하십시오.

확인 및 일정 설정

1. 단계를 실행하고(워크플로에서 단일 단계 실행 참조) 대상 테이블에서 행 수를 확인하고, 금액/날짜 열이 텍스트가 아닌 지정한 형식으로 들어왔는지 확인합니다.

2. 지속적인 피드가 필요하면 워크플로를 예약합니다.

참고

모든 NetSuite 가져오기는 테이블 전체 교체 방식입니다. 증분 경로가 없으므로 예약된 가져오기는 실행할 때마다 전체 결과를 다시 추출합니다. 실행할 때마다 전체 이력을 가져오지 말고, WHERE 절을 실제로 필요한 범위(예: 롤링 날짜 범위)로 제한하십시오.

문제 해결

증상	가능한 원인
테스트 요청이 범위 또는 역할 메시지와 함께 400 반환	역할에 REST Web Services / OAuth 2.0 로그인 / SuiteAnalytics 권한이 없거나 범위 배열이 거부되었습니다. 표시되는 상세 내용에 원인이 나와 있습니다.
토큰 교환 실패	계정 ID 형식 오류(_SB1 누락), 인증서 ID(kid) 오류, 또는 업로드한 공개 인증서와 일치하지 않는 개인 키.
가져오기 중 형식/변환 오류(열과 값이 표시됨)	형식이 지정된 열에 파싱할 수 없는 값이 들어왔습니다. 대개 SuiteQL이 계정의 표시 형식을 반환한 Date/Datetime 열입니다. 쿼리에서 필드를 TO_CHAR(col, 'YYYY-MM-DD')로 감싸거나 열 형식을 Text로 설정하십시오.
자회사 간 합계가 맞지 않음	amount는 각 거래의 자체 통화 기준입니다. 연결/변환된 필드를 사용하십시오.
대량 가져오기에서 행이 중복되거나 누락됨	오프셋 페이징 쿼리에 결정적인 ORDER BY가 없습니다.

관련 항목

• NetSuite SuiteQL 쿼리 예시 — 분개 항목, 시산표, 손익계산서, 미수금 등을 위한 바로 실행 가능한 쿼리.
• NetSuite REST 커넥터 — 필드 및 SuiteQL 참조.
• REST 요청 단계 — 이 가져오기의 기반이 되는 단계.
• 연결 만들기 및 관리