Xero 연동 가이드 SkyPlanner APS를 활용한 생산 스케줄링
이 가이드는 Xero 자문 담당자, 컨설턴트, IT 팀을 대상으로 Xero와 SkyPlanner APS를 연결하는 방법을 설명합니다. SkyPlanner는 Xero Accounting API와 Projects API를 통해 Xero와 양방향으로 연동됩니다.
- 연락처, 현재고 수량이 포함된 재고 추적 품목, 승인된 견적서, 입고일이 포함된 구매 발주서를 가져옵니다.
- 완료 예정일은 각 견적서의 이력에 메모로 전송됩니다.
- 완료된 주문은 견적서의 항목과 참조 정보를 포함한 매출 청구서 초안으로 전송되며, 견적서 상태는 Invoiced로 변경됩니다.
- 프로젝트 작업에 기록한 시간은 Xero Projects의 시간 기록으로 전송됩니다.
- Xero 웹훅은 연락처와 청구서의 변경을 알리고, SkyPlanner 웹훅은 일정이 변경될 때마다 이를 즉시 전송합니다.
Xero는 회계 소프트웨어이므로 자재 명세서, 공정 순서, 설비, 생산 오더를 보관하지 않습니다. 작업장, 공정 단계, 교대조, 준비 시간은 SkyPlanner에서 관리합니다. SkyPlanner 팀은 온보딩 과정에서 고객의 Xero 조직에 맞춰 연동을 설정하고, 운영 개시 후에도 지원합니다. 이 가이드는 연동 작업에 참여하거나 문서화된 SkyPlanner REST API(API 참조 문서)를 활용해 직접 개발하려는 자문 담당자와 개발자를 위한 자료입니다.
Xero Accounting API
Xero는 하나의 멀티테넌트 클라우드 제품으로, 모든 조직이 동일한 API를 사용합니다. Accounting API는 https://api.xero.com/api.xro/2.0/에서 제공하는 REST API이며 JSON 또는 XML을 사용합니다. 각 호출에서는 Xero-tenant-id 헤더로 대상 조직을 지정합니다. (출처)
스케줄링에 필요한 엔드포인트는 다음과 같습니다.
- 기준정보:
/Contacts(고객 및 공급업체),/Items(Code, IsTrackedAsInventory, QuantityOnHand). - 수요:
/Quotes(Status가 ACCEPTED인 견적서, LineItems). 청구서를 먼저 발행하는 제조 현장에서는 Type이 ACCREC인/Invoices도 사용합니다. - 공급:
/PurchaseOrders(DeliveryDate, ExpectedArrivalDate, ItemCode가 포함된 LineItems). - Xero로 전송:
/Quotes/{QuoteID}/History,/Invoices,/Quotes, 그리고https://api.xero.com/projects.xro/2.0/projects/{projectId}/time의 Projects API.
모든 목록 조회 엔드포인트는 If-Modified-Since 헤더를 지원하므로 동기화할 때마다 변경된 데이터만 읽습니다. 생성과 업데이트는 일괄 처리합니다. 자재 명세서, 공정 순서, 생산 오더용 엔드포인트는 없습니다.
인증, 권한 범위 및 제한
Xero는 OAuth 2.0을 사용합니다. Xero 관리자가 한 번 로그인해 앱을 승인하고 조직을 선택합니다. 앱은 갱신 토큰으로 연결을 유지하기 위해 offline_access를 요청합니다. (출처)
Xero는 포괄적인 권한 범위를 세분화된 범위로 전환하고 있으며, 새 앱에는 세분화된 범위가 적용됩니다. 스케줄링 연동에는 다음 권한 범위가 필요합니다.
accounting.invoices: 견적서, 청구서, 구매 발주서 및 품목accounting.contacts: 고객 및 공급업체accounting.settings.read: 품목 설정projects: 시간 기록offline_access
Xero는 조직별 동시 호출 수, 분당·일일 호출 수와 앱별 호출 수를 제한합니다. 앱이 제한을 초과하면 Retry-After 헤더와 함께 HTTP 429를 반환합니다. 일일 허용량과 연결할 수 있는 조직 수는 앱의 파트너 등급에 따라 달라집니다. 두 항목 모두 Xero의 API 제한 안내 페이지에서 확인할 수 있습니다. 웹훅, If-Modified-Since를 사용한 조회, 일괄 쓰기를 활용하면 스케줄링 연동을 이러한 제한 내에서 여유 있게 운영할 수 있습니다.
SkyPlanner의 REST API는 Authorization-Token 헤더에 API 토큰을 넣어 인증합니다(SkyPlanner Settings > API). API 문서는 Swagger/OpenAPI로 제공됩니다. 연동 튜토리얼에서 첫 API 호출 과정을 단계별로 안내합니다.
웹훅
“Webhooks allow you to subscribe to certain events that happen in Xero.”(웹훅을 사용하면 Xero에서 발생하는 특정 이벤트를 구독할 수 있습니다.) (출처) 스케줄링에 관련된 이벤트는 Contact와 Invoice이며, 각각 CREATE와 UPDATE 이벤트를 제공합니다.
웹훅은 다음과 같이 동작합니다.
- 앱당 하나의 웹훅으로 연결된 모든 조직을 처리합니다.
- 각 전송에는 리소스 ID와 이벤트 유형이 담긴 이벤트 배열이 포함됩니다. 수신 측은 이를 받은 뒤 해당 리소스를 조회합니다.
- 모든 전송에는 앱의 웹훅 키로 생성한 서명이
x-xero-signature헤더에 포함됩니다. Xero는 전송을 시작하기 전에 “Intent to receive”(수신 의사 확인) 검사를 보냅니다. - Xero는 전송에 실패하면 재시도하고, 계속 실패하는 웹훅은 비활성화합니다. 따라서 수신 측은 먼저 신속하게 응답한 뒤 실제 작업을 처리합니다.
견적서, 품목, 구매 발주서에는 웹훅 이벤트가 없습니다. SkyPlanner는 If-Modified-Since를 사용해 짧은 주기로 폴링하여 이를 조회합니다. 변경 사항이 없을 때는 엔터티당 한 번의 호출이 필요합니다.
데이터 매핑
| Xero 객체(엔드포인트) | SkyPlanner 객체 | 방향 | 주기 |
|---|---|---|---|
Contact, IsCustomer(/Contacts) | Customer(external_identifier, delivery_priority) | Xero → SkyPlanner | 최초 가져오기 후 웹훅 수신 시 |
재고 추적 여부와 관계없이 QuantityOnHand가 포함된 Item(/Items) | 제품 및 자재, 재고 | Xero → SkyPlanner | 최초 가져오기 후 If-Modified-Since로 조회 |
Status가 ACCEPTED이며 LineItems가 포함된 Quote(/Quotes) | Order(external_order_number, delivery_date), 항목별 작업 | Xero → SkyPlanner | If-Modified-Since로 폴링 |
Type이 ACCREC인 Invoice(청구서를 먼저 발행하는 제조 현장)(/Invoices) | 주문 및 작업 | Xero → SkyPlanner | 웹훅을 통한 실시간 처리 |
ExpectedArrivalDate 또는 DeliveryDate가 포함된 PurchaseOrder(/PurchaseOrders) | 입고 예정 자재(estimated_delivery_date) | Xero → SkyPlanner | If-Modified-Since로 폴링 |
견적서 이력 메모(PUT /Quotes/{QuoteID}/History) | 완료 예정일 | SkyPlanner → Xero | 일정 변경 시 |
Invoice, Type은 ACCREC, Status는 DRAFT, Reference = 견적서 번호(POST /Invoices) | 완료된 주문 | SkyPlanner → Xero | 주문 완료 시 |
Quote의 Status를 INVOICED로 변경(POST /Quotes) | 완료된 주문 | SkyPlanner → Xero | 청구서 생성 시 |
Projects 시간 기록(POST /projects/{projectId}/time) | Mobile Confirmations, 시간 기록 | SkyPlanner → Xero | 작업을 기록할 때마다 |
| Xero에서 관리하지 않음 | 작업장, 공정 단계, 교대조, 부재, 준비 시간 매트릭스, 공구, 작업자 수, 대체 작업장 | SkyPlanner에서 관리 | 온보딩 중 설정 |
연동 방식
1. 기준정보 최초 가져오기. 연락처와 품목을 페이지 단위로 조회한 다음, 미결 구매 발주서와 승인된 견적서를 조회합니다. Xero ContactID를 external_identifier로 지정해 SkyPlanner에 고객을 생성하고, 품목 코드를 키로 사용해 제품과 자재를 생성합니다. 이어서 Xero에 없는 작업장, 제품별 공정 단계, 교대조, 휴가, 준비 시간을 설정합니다. 공정 단계는 CSV 또는 Excel로 가져오는 것이 가장 빠릅니다.
2. 주문 동기화. If-Modified-Since를 사용해 견적서를 폴링합니다. 견적서 상태가 ACCEPTED로 바뀌면 SkyPlanner는 견적서 번호를 external_order_number로 지정해 주문을 생성합니다. delivery_date에는 현장에서 약속 납기일을 기록하는 필드의 값을 사용하며, 이 필드는 온보딩 중에 매핑합니다. 각 항목은 해당 제품의 공정 단계에 따라 작업으로 생성됩니다. 구매 발주서 항목은 예상 입고일에 입고될 자재로 반영되므로, 작업은 자재 입고를 기다리게 됩니다. 매일 밤 미결 견적서와 구매 발주서를 전체 조회하여 누락된 내용을 반영합니다.
3. 일정 및 완료 결과를 Xero로 전송. 세 번의 호출로 결과를 Xero에 반영합니다.
- PUT
/Quotes/{QuoteID}/History는 완료 예정일을 담은 메모를 추가합니다. 승인된 견적서는 연락처와 메모만 변경할 수 있으므로, 날짜는 이력 메모에 기록합니다. (출처) - 주문이 완료되면 POST
/Invoices로 매출 청구서를 생성합니다. Type은 ACCREC, Status는 DRAFT로 지정하고, 견적서의 연락처와 항목을 포함하며, Reference에는 견적서 번호를 넣습니다. 회계 담당자가 Xero에서 이를 승인하고 발송합니다. - QuoteID와 Status INVOICED를 지정해 POST
/Quotes를 호출하면 견적서가 마감됩니다. Accounting API에서는 Accepted에서 Invoiced로 상태를 변경할 수 있습니다.
4. 현장 실적 등록 및 프로젝트 작업 시간. 작업자는 SkyPlanner Mobile Confirmations, Production Timer 또는 Quick Log Mode로 작업을 기록합니다. 진행 상황은 일정에 즉시 반영되고, Autopilot이 나머지 일정을 다시 계획합니다. 프로젝트 작업의 경우 SkyPlanner는 Xero 사용자, 날짜, 소요 시간을 포함한 시간 기록을 해당 프로젝트 작업에 전송합니다. (출처)
5. 데이터 관리 주체와 충돌 처리 규칙. 운영을 시작하기 전에 다음 사항을 문서화하세요.
| 데이터 | 관리 주체 |
|---|---|
| 연락처, 품목, 가격, 견적서, 구매 발주서, 청구서, 회계 | Xero |
| 작업장, 공정 단계, 교대조, 부재, 준비 시간 매트릭스, 공구, 대체 자원 | SkyPlanner |
| 작업 순서, 시작 및 종료 시간, 작업별 작업장 | SkyPlanner |
| 견적서의 완료 예정일 메모 | SkyPlanner에서 관리하고 Xero에 기록 |
| 완료된 주문의 청구서 초안, 프로젝트 작업 시간 | SkyPlanner에서 생성하고 승인 후에는 Xero에서 관리 |
일반적인 프로젝트 진행 단계
구축은 보통 온보딩을 시작한 뒤 몇 주 안에 완료됩니다. 그에 앞서 30일 무료 체험에서는 Xero에서 연락처, 제품, 미결 견적을 CSV로 내보내 자사 데이터로 사용해 볼 수 있습니다.
실제 프로젝트는 다음 단계로 진행됩니다.
- 연결. Xero 관리자가 SkyPlanner를 승인하고 조직을 선택합니다.
- 수요 객체. 수락된 견적과 매출 청구서 중 무엇을 기준으로 생산을 시작할지 합의합니다.
- 매핑. 매핑 테이블, 품목 코드, 청구서 계정, 세금 기본값과 데이터 관리 주체에 관한 규칙을 확정합니다.
- 초기 데이터 적재. 연락처, 품목, 미결 구매 주문, 수락된 견적을 가져옵니다.
- 생산 모델. SkyPlanner에서 작업장, 제품별 공정 단계, 교대조, 준비 시간 매트릭스, 공구와 작업자 수를 설정합니다.
- 동기화. 연락처와 청구서에는 웹훅을 사용하고, 견적, 품목, 구매 주문에는
If-Modified-Since폴링을 사용합니다. 매일 밤 데이터도 대조합니다. - Xero에 쓰기. 먼저 견적 메모를, 다음으로 청구서 초안과 견적 상태를 반영합니다. 프로젝트 작업 시간을 사용하는 경우에는 그다음에 반영합니다.
- 병행 테스트 및 정식 운영. SkyPlanner의 날짜를 현재 계획과 비교하고, 회계 담당자가 첫 청구서 초안을 확인한 뒤 Xero로 결과를 전송하는 기능을 활성화합니다.
Xero 연동 시 미리 고려할 사항
- Xero에는 생산 객체가 없습니다. 제품별 공정 단계는 Xero 품목 코드를 키로 삼아 SkyPlanner에서 관리하세요. 품목 코드는 변경하지 않고 유지하세요.
- 견적에는 웹훅이 없습니다. 분당 및 일일 호출 한도 안에서
If-Modified-Since로 짧은 주기로 폴링하세요. - 수락된 견적은 잠깁니다. 수락 후에는 연락처 정보와 메모만 변경할 수 있습니다. 따라서 약속 납기일은 수락 시 한 번 읽어 오고, 완료 예정일은 이력 메모로 기록합니다.
- 재고는 매출·매입 청구서에 따라 변동됩니다. Xero는 재고 추적 품목의 매출 청구서, 매입 청구서, 대변 전표를 통해 보유 수량을 조정합니다. 완제품과 사용 자재의 회계 처리 방식은 회계 담당자와 합의하세요.
- 프로젝트 작업 시간에는 Xero 사용자가 필요합니다. 작업 시간 기록은 Xero 사용자에게 귀속됩니다. 어떤 작업자의 시간을 Xero Projects에 기록할지 정하고, 나머지는 SkyPlanner에서 관리하세요.
- 세분화된 권한 범위. 포괄적인 권한 범위는 단계적으로 폐지되고 있으므로 처음부터 세분화된 권한 범위를 요청하세요.
- 앱 등급. 파트너 등급에 따라 앱이 연결할 수 있는 조직 수와 일일 호출 수가 정해집니다. 공장 수를 고려해 등급을 계획하세요.
Xero 연동은 누가 설정하고 지원하나요?
연동 작업에는 품목, 견적, 구매 주문과 완료된 작업을 청구로 연결하는 방식이 포함됩니다. 여기에 Xero에서 관리하지 않는 작업장, 공정 단계, 교대조, 준비 시간 매트릭스, 공구, 작업자 수, 대체 자원을 추가합니다.
- SkyPlanner 팀이 온보딩 중에 연동을 설정하고 정식 운영 후에도 지원합니다. 제조 현장마다 Xero에서 품목, 견적, 재고를 설정하는 방식이 다릅니다. 이러한 차이에 대응하는 노하우가 설정 과정에 반영됩니다.
- Xero 자문 담당자나 연동 파트너가 구축할 수도 있습니다. SkyPlanner는 REST API, Swagger/OpenAPI 문서와 웹훅을 제공합니다.
- 사내 개발자가 직접 연동을 개발할 수도 있습니다. API 토큰만 있으면 시작할 수 있으며, 필요할 때 SkyPlanner 팀이 지원합니다. 구매 주문 및 제품·자재 API를 포함한 제품 문서는 SkyPlanner 문서에서 확인할 수 있습니다.
SkyPlanner는 작업장 5개를 포함해 월 199 €부터 시작하며 매월 청구됩니다. 연동 비용은 고객의 공정과 요구사항에 맞춰 요금제와 함께 사전에 견적으로 안내하므로, 시작 전에 전체 비용을 확인할 수 있습니다. 요금과 기능을 살펴보고, Xero만으로 가능한 범위는 Xero에 생산 스케줄링 기능이 있나요?에서 확인하세요. 개요는 Xero 페이지에 있으며, 다른 시스템은 전체 연동에서 확인할 수 있습니다.
제조업체의 SkyPlanner 사용 후기
2시간매주 절약
“SkyPlanner 덕분에 Excel 스프레드시트로 생산 계획을 세우던 방식에서 실시간으로 생산을 최적화하는 방식으로 전환했습니다.”
Kalle Kalliomäki, 공급망 전문가
UTU · 배전반 및 개폐장치
생산 계획 업무에서 매주 2시간을 절약하며, 새로운 작업 대기열이 몇 초 만에 생산 라인에 전달됩니다.
+90%생산 효율 향상
“생산 효율이 90% 향상되었습니다.”
Abdul Rucyinga, IT 책임자
Laboratory & Allied · 의약품 제조
생산 효율이 90% 향상되었으며, 모든 작업장을 대상으로 석 달치 최적화 계획을 수립하는 데 30분도 걸리지 않습니다.
감소자재 부족으로 인한 가동 중단
“SkyPlanner의 가치는 일상 업무에서 실질적으로 쓸 수 있는 도구라는 점에 있습니다. 특히 납기일을 정할 때 유용합니다.”
Tommi Männistö, 생산 계획 관리자
Eskomatic · 위탁 기계 가공
부하를 자동으로 스케줄링해 납기일을 더 정확하게 산정하며, 자재 부족으로 인한 생산 중단이 크게 줄었습니다.
1,000s수천 건의 작업 지시 자동 스케줄링
“생산을 관리하는 방식이 달라졌고, 생산능력을 파악하는 수준도 완전히 달라졌습니다.”
Hannu Ryynänen, CEO
Mamec · 산업용 믹서, 펌프 및 첨단 위탁 제조
수천 건의 작업 지시가 자동으로 스케줄링되며, 조직 전체가 생산 현황을 실시간으로 확인합니다.
자주 묻는 질문
Xero에 생산 데이터용 API가 있나요?
Xero에는 Accounting API와 Projects API가 있으며, 둘 다 OAuth 2.0을 사용하는 REST 방식입니다. 연락처, 품목, 견적, 청구서, 구매 주문과 작업 시간 기록을 다룹니다. 작업장과 공정 단계 같은 생산 데이터는 SkyPlanner에서 관리합니다.
SkyPlanner에서 Xero로 데이터를 쓸 수 있나요?
네. SkyPlanner는 각 견적의 이력에 계획 완료일을 추가하고, 주문이 완료되면 견적의 항목으로 매출 청구서 초안을 생성합니다. 견적 상태를 Invoiced로 변경하고 프로젝트 작업 시간도 기록합니다.
Xero는 변경 사항을 실시간으로 전송하나요?
Xero 웹훅은 연락처와 청구서를 지원합니다. SkyPlanner는 If-Modified-Since로 마지막 동기화 이후 변경된 견적, 품목, 구매 주문을 읽어 오고 매일 밤 데이터를 대조합니다. 따라서 새로 수락된 견적이 일정에 빠르게 반영됩니다.
Xero에 없는 자재 명세서, 공정 순서, 기계 정보는 어디서 가져오나요?
SkyPlanner에서 설정합니다. 작업장, 제품별 공정 단계, 교대조와 준비 시간을 직접 입력하거나 CSV 또는 Excel로 가져와 한 번 설정하면 됩니다. 각 제품은 Xero 품목 코드와 연결되므로 새로 수락된 견적이 자동으로 스케줄링됩니다.
