QuickBooks Online 연동 가이드 SkyPlanner APS로 생산 스케줄링하기

QuickBooks Online은 하나의 멀티테넌트 클라우드 제품이며, 모든 회사가 동일한 Accounting API를 사용합니다. 이 API는 v3 버전의 REST API입니다. 각 호출은 realm ID로 하나의 회사를 지정합니다: https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}. 테스트용 샌드박스 호스트는 별도로 제공됩니다. 요청과 응답은 JSON 형식이며, minorversion 매개변수로 스키마 버전을 선택합니다. (출처)

생산 스케줄링에 필요한 엔터티는 다음과 같습니다.

• 기준정보: Customer, Item(Inventory, NonInventory, Service), Employee, Vendor.
• 수요: Estimate(TxnStatus가 Accepted인 견적서의 상세 항목, ShipDate). 먼저 대금을 청구하는 제조업체는 Invoice 또는 SalesReceipt도 사용합니다.
• 공급: PurchaseOrder(POStatus가 Open인 구매 주문, 품목과 수량이 포함된 상세 항목), Bill.
• 역전송: Estimate, Invoice, TimeActivity, InventoryAdjustment.

데이터를 읽을 때는 query 엔드포인트를 사용합니다. 예를 들면 select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'입니다. 일부 필드만 업데이트할 수 있으므로 SkyPlanner는 변경한 필드만 전송합니다. Accounting API에는 판매 주문, 공정 순서, 작업 센터, 생산 주문 엔터티가 없습니다.

QuickBooks 웹훅은 연결된 회사의 데이터가 변경되면 앱에 알립니다. “Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.”(최종 사용자의 QuickBooks Online 회사 파일에서 데이터가 변경될 때마다 웹훅이 자동으로 알려줍니다.) (출처) 생산 스케줄링에 중요한 엔터티는 다음과 같습니다.

• Customer, Item, Employee
• Estimate, Invoice, SalesReceipt
• PurchaseOrder, Bill
• TimeActivity

작업 유형에는 Create, Update, Delete, Merge, Void가 있습니다. 알림에는 전체 레코드가 아니라 엔터티 이름, ID, 작업 유형, 마지막 업데이트 시각이 포함됩니다. 수신 측은 알림을 받은 뒤 해당 레코드를 읽습니다.

변경 데이터 캡처(GET /cdc?entities=...&changedSince=...)는 조회 가능한 최근 기간 내에서 지정한 시각 이후의 모든 변경 사항을 반환합니다. SkyPlanner는 이를 사용해 매일 밤 데이터를 대조하므로 웹훅을 놓쳐도 주문이 갱신되지 않은 채 남는 일이 없습니다. TimeActivity는 변경 데이터 캡처 대상이 아니므로 쿼리로 대조합니다. (출처)

1. 기준정보 최초 일괄 로드. query 엔드포인트로 고객, 품목, 직원, 미결 구매 주문을 페이지 단위로 조회합니다. QuickBooks ID를 external_identifier로 사용해 SkyPlanner 고객을 생성하고, 품목 ID를 키로 사용해 제품과 자재를 생성합니다. 그런 다음 QuickBooks에 없는 작업장, 제품별 공정 단계, 교대조, 휴가, 준비 시간을 설정합니다. 공정 단계는 CSV 또는 Excel로 가져오는 것이 가장 빠릅니다.

2. 주문 동기화. Estimate, Invoice, Item, PurchaseOrder 웹훅을 구독합니다. 견적서 상태가 Accepted로 바뀌면 SkyPlanner가 이를 읽어 주문을 생성합니다. 이때 견적서 번호는 external_order_number로, 출하일은 delivery_date로 설정합니다. 각 상세 항목은 제품의 공정 단계에 따라 작업으로 생성됩니다. 미결 구매 주문의 상세 항목은 입고 예정 자재로 반영되므로, 작업은 자재가 도착할 때까지 대기합니다. 매일 밤 실행하는 변경 데이터 캡처가 누락된 이벤트를 찾아냅니다.

3. 일정 및 완료 결과 역전송. 네 가지 호출로 결과를 QuickBooks에 반영합니다.

• Estimate의 ShipDate를 부분 업데이트하여 QuickBooks의 약속 납기를 계획에 맞춰 반영합니다.
• 주문이 완료되면 POST /invoice 호출로 견적서의 상세 항목과 해당 견적서를 가리키는 LinkedTxn을 포함한 청구서를 생성합니다. Intuit는 견적서 하나당 청구서 연결을 하나만 허용하므로, 분할 납품 처리 방식은 범위 산정 단계에서 합의합니다.
• POST /timeactivity 호출로 각 작업자가 기록한 작업 시간을 직원, 고객, 서비스 품목에 연결해 저장합니다. 이후 청구 가능한 작업 시간을 QuickBooks의 청구서에 추가할 수 있습니다.
• POST /inventoryadjustment 호출로 완제품 재고를 늘리고 사용한 자재 재고를 줄입니다. Intuit는 미국의 QuickBooks Online Plus 및 Advanced에서 이 엔터티를 제공합니다. (출처)

4. 생산 현장 실적 등록. 작업자는 SkyPlanner Mobile Confirmations, Production Timer 또는 Quick Log Mode로 작업을 기록합니다. 진행 상황이 일정에 즉시 반영되고, Autopilot이 나머지 일정을 다시 계획합니다. 작업 시간은 작업 시간 내역으로 QuickBooks에 전송됩니다. 급여 처리를 위해 QuickBooks Time을 계속 사용하는 제조업체는 범위 산정 단계에서 작업 시간 기록 경로를 하나로 정해야 합니다.

5. 데이터 관리 주체 및 충돌 처리 규칙. 정식 운영 전에 다음 사항을 문서화하세요.

• 판매 주문은 QuickBooks 화면에서 관리합니다. Plus와 Advanced 앱에는 판매 주문 기능이 있으며, 연동에서는 수락된 견적을 읽습니다. 선청구 방식으로 운영하는 업체라면 청구서를 읽습니다. 모든 주문이 같은 방식으로 들어오도록 시작 기준을 하나로 합의하세요.
• QuickBooks에는 공정 순서가 없습니다. 제품별 공정 단계는 QuickBooks 품목 키와 연결해 SkyPlanner에서 관리하세요.
• 견적 하나에 청구서 하나를 연결합니다. 분할 납품에는 납품 건마다 견적을 하나씩 만드는 등의 규칙이 필요합니다.
• 재고 조정 지원 여부는 요금제와 지역에 따라 다릅니다. 미국의 Plus와 Advanced에서는 재고 조정을 지원합니다. 그 외 지역에서는 완제품을 QuickBooks에 반영하는 방법을 회계 담당자와 합의하세요.
• Intuit Enterprise Suite의 제조 주문. 이 기능을 사용한다면 생산과 부품 재고 예약을 어느 시스템에서 관리할지 정하세요.
• API에서 번들은 읽기 전용입니다. API로는 그룹 품목을 생성할 수 없으므로 번들은 QuickBooks에서 관리하세요.
• 갱신 토큰 교체. 토큰을 갱신할 때마다 최신 갱신 토큰을 저장하세요. 그렇지 않으면 연결이 끊깁니다.