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

Katana는 단일 멀티테넌트 클라우드 제품이므로 모든 고객이 동일한 API를 사용합니다. REST API v1의 주소는 https://api.katanamrp.com/v1이며, OpenAPI 3.0 명세는 https://api.katanamrp.com/v1/openapi.json에서 확인할 수 있습니다. 관련 문서는 Katana Developer Hub에 있습니다.

스케줄링에 필요한 엔드포인트는 다음과 같습니다.

• 기준정보: /products, /materials, /variants, /recipe_rows, /bom_rows, /product_operation_rows.
• 오더: /manufacturing_orders, /manufacturing_order_operation_rows, /manufacturing_order_recipe_rows, /manufacturing_order_productions.
• 작업 순서: /manufacturing_order_rerank.
• 수급: /inventory, /purchase_orders, /purchase_order_rows, /sales_orders, /sales_order_rows.

/resources 엔드포인트는 없습니다. 자원 정보는 제품 공정 행과 제조 오더 공정 행의 resource_id 및 resource_name에 담겨 있습니다.

POST /webhooks에 HTTPS URL과 필요한 이벤트를 지정해 웹훅을 등록하세요. (출처) 스케줄링에 유용한 이벤트는 다음과 같습니다.

• manufacturing_order.created, .updated, .deleted, .in_progress, .blocked, .done
• manufacturing_order_operation_row.created, .updated, .in_progress, .paused, .completed
• current_inventory.material_updated, .material_out_of_stock
• 입고 이벤트를 포함한 purchase_order.* 및 purchase_order_row.*
• product.*, product_recipe_row.* 및 sales_order.*

페이로드에는 자원 유형, 동작, href만 담깁니다. 수신 측은 href에서 전체 객체를 가져옵니다. 전송할 때마다 검증용 x-sha2-signature 헤더(HMAC SHA-256)가 포함됩니다. 엔드포인트는 10초 이내에 20X로 응답해야 합니다. Katana는 30초, 2분, 15분 후에 총 세 번 재시도합니다.

1. 기준정보 최초 적재. 호출 제한을 넘지 않도록 속도를 조절하면서 제품, 자재, 변형 제품, 레시피 행, 제품 공정 행을 페이지 단위로 가져오세요. 공정 행에 있는 자원을 중복 없이 추출해 SkyPlanner 작업장을 만들고, 1:1로 대응하는 키를 유지하세요. Katana에는 자원 캘린더가 없으므로 SkyPlanner에서 작업장별로 교대 근무, 휴가, 초과 근무를 설정하세요.

2. 오더 동기화. 제조 오더, 공정 행, 재고, 구매 오더 이벤트를 구독하세요. 이벤트가 발생할 때마다 href에서 객체를 가져와 작업을 업데이트하세요. SkyPlanner는 발주한 자재를 구매 오더의 납품일에 사용 가능한 것으로 간주하며, 입고가 처리되면 재고를 업데이트합니다. 매일 밤 수정일 필터로 데이터를 대조하면 누락된 이벤트를 확인할 수 있습니다.

3. 스케줄 반영. 다음 두 번의 호출로 계획을 Katana에 반영합니다.

• POST /manufacturing_order_rerank는 “moves one or more manufacturing orders to an exact place in the production schedule”(하나 이상의 제조 오더를 생산 스케줄의 정확한 위치로 이동)하는 기능입니다. 요청당 미완료 제조 오더를 최대 250개까지 지정할 수 있으며, 맨 위나 맨 아래 또는 특정 제조 오더의 앞이나 뒤에 배치합니다. (출처)
• PATCH /manufacturing_orders/{id}는 production_deadline_date를 설정합니다. Katana는 해당 공장 위치의 마감일 자동 계산이 꺼져 있을 때만 이 값을 허용합니다. (출처)

순위 재조정은 목록의 표시 순서만 바꾸는 것이 아닙니다. Katana에서는 “higher-priority MOs reserve required materials and subassemblies first”(우선순위가 높은 제조 오더가 필요한 자재와 하위 조립품을 먼저 예약)하므로, SkyPlanner에서 정한 순서는 Katana에서 어떤 제조 오더에 재고를 할당할지도 결정합니다.

4. 생산 현장 실적 보고. 작업자는 SkyPlanner Mobile Confirmations, Production Timer 또는 Quick Log Mode로 작업을 기록합니다. SkyPlanner는 제조 오더 공정 행에 상태와 실제 소요 시간을 기록합니다. 공장에서 Katana Shop Floor App을 계속 사용하는 경우에는 SkyPlanner가 공정 행 이벤트를 읽어옵니다. 공장마다 실적 보고 채널을 하나로 정하세요.

5. 데이터 관리 주체와 충돌 처리 규칙. 운영을 시작하기 전에 다음 사항을 문서로 정리하세요.

• 마감일 모드에 따라 기존 날짜가 사라집니다. “Once automatic mode is enabled, all manual deadlines will be overwritten and cannot be restored.”(자동 모드를 활성화하면 수동으로 지정한 모든 마감일이 덮어써지며 복원할 수 없습니다.) 프로젝트 착수 시 사용할 모드를 한 번에 확정하세요.
• 자원별 캘린더가 없습니다. 단일 Weekly throughput 값으로 교대 근무를 산출하지 마세요. SkyPlanner에서 작업장별로 설정하세요.
• 자원은 공정 행에만 있습니다. Katana의 자원 이름은 SkyPlanner 작업장과 연결하는 키이므로 일관되게 유지하세요.
• 시간 단위. planned_time_parameter의 단위는 초입니다. per-unit 공정에서는 단위당 시간이며, process, setup, fixed 유형에서는 총시간입니다. 유형을 올바르게 매핑하지 않으면 소요 시간이 수량에 해당하는 배수만큼 커지거나 작아집니다.
• 수주생산 그룹. 순서를 재배치할 때 동일한 판매 주문에 연결된 MO는 함께 묶여 이동하므로 그룹 단위로 순서를 지정하세요.
• 순서 재배치 동작이 변경되었습니다. 2026년 10월 7일부터 rerank 엔드포인트는 요청한 위치에 정확히 주문을 배치합니다. 이전 동작을 기준으로 개발한 연동은 다시 테스트해야 합니다. (출처)