오토메타 연동 개발 시나리오

오토메타 커머스 백엔드가 비스캣 코어와 연동해 주문 한 건을 처리하는 흐름입니다. 엔드포인트·페이로드 상세는 연동 API 문서를, 메인은 개발 가이드를 참조하세요.

1. 연동 플로우

아이파크홈 앱은 비스캣 코어와 직접 통신하지 않습니다. 오토메타가 주문을 받아 비스캣 API를 호출하고, 비스캣이 발신하는 상태 통지를 받아 앱·월패드에 표출합니다.

flowchart LR APP["아이파크홈 앱"] AUTOMA["오토메타
커머스 백엔드"] CORE["비스캣 코어
(로봇 관제)"] APP --> AUTOMA AUTOMA -->|"#1~#5 인바운드 (X-Api-Key)"| CORE CORE -->|"#6~#9 콜백 (HMAC 서명)"| AUTOMA AUTOMA --> APP

2. 배송 가능 여부 조회 (주문 이후)

주문 접수 후 실제 배차 요청(#2) 직전에 POST /v1/automata/delivery/availability를 호출합니다. 이때 매장(shopId)·세대(dong·ho)와 필요한 박스 수(boxCount)를 함께 견적에 전달하면, 로봇이 점포·세대까지의 도착 예상시간을 합산하고 박스 수용 가능 여부까지 반영해 가용성을 판정합니다. 비스캣은 그 결과로 가능 여부와 도착 예상시간(etaMinutes, 점포+세대 합, 분)을 반환합니다 — 불가하거나 타임아웃이면 etaMinutes는 null입니다. 이 단계는 미션을 생성하지 않습니다. 견적도 배차(#2)와 동일하게 매장·세대 목적지 노드가 매핑돼 있어야 하며, 없으면 422 DESTINATION_NOT_MATCHED로 거부됩니다(미션 미생성).

3. 배차 요청·PIN 교환

결제 완료 후 POST /v1/automata/dispatch로 실제 배차합니다. 오토메타는 점주 PIN(고정 4자리)을 동봉하고, 비스캣은 미션을 생성·로봇을 점유한 뒤 사용자 PIN(랜덤 4자리)과 배차로봇ID를 응답합니다.

sequenceDiagram participant A as 오토메타 participant C as 비스캣 코어 A->>C: POST /v1/automata/dispatch (ownerPin 동봉, Idempotency-Key) alt 배차 가능 C-->>A: 200 { missionId, robotId, userPin(랜덤), etaMinutes } else 로봇 없음 / 수량 초과 C-->>A: 503 NO_ROBOT_AVAILABLE / 422 DISPATCH_LOAD_EXCEEDED end Note over A: orderId가 후속 호출의 주키 — robotId는 표시·로그용 정보성 필드

유니크 키 (재시도 안전)

배차 요청은 Idempotency-Key 헤더를 필수로 부착합니다. 동일 키로 24시간 내 재시도하면 첫 응답이 그대로 반환되고, 동일 키 + 다른 페이로드는 409 ORDER_DUPLICATE로 거절됩니다. 재시도 시 키를 동일하게 유지하세요.

4. 배송 진행·상태 통지·알림 노티

배차 이후 로봇 진행 상태는 비스캣이 오토메타 콜백 URL로 발신합니다(#6~#8). 별도로 알림 노티(#9)는 상태 식별자 코드만 전달하고, 사용자 표출 문구는 오토메타가 관리합니다.

sequenceDiagram participant C as 비스캣 코어 participant A as 오토메타 C->>A: #6 robot.shop_arrived (매장 도착, 점주PIN 포함) C->>A: #7 delivery.departed (박스 닫힘 = 출발) C->>A: #9 notify.event (code=NOTI_ETA_5MIN) C->>A: #8 delivery.status_changed (arrived) A->>C: #10 unlock (대면, 주문자가 앱에서 개폐) C->>A: #8 delivery.status_changed (unloaded, 하차 완료) Note over A: 각 콜백 수신 → 앱·월패드 표출

#6 매장 도착: 로봇이 매장에 도착. 점주가 박스를 열 점주 PIN을 함께 전달.
#7 배달 출발: 점주 상차 후 박스 닫힘이 출발 트리거.
#8 예정/도착/하차: phase로 예정·도착·하차 완료를 구분.
#9 알림 노티: 도착 5분 전 등 알림 이벤트. 비스캣은 코드만 보내고 문구는 오토메타가 관리.
#10 박스 개폐(하차): 대면 배송(autoDropoff: false)이면 로봇이 고객 위치에 도착(arrived)한 뒤, 주문자가 오토메타 앱(WEB)에서 박스를 엶 → 앱이 POST /v1/automata/dispatch/{orderId}/unlock으로 요청하면 비스캣이 해당 주문 로봇의 박스를 엽니다. 비대면(autoDropoff: true)은 자동 하차로 개폐 호출이 불필요합니다.

5. 위치·도착 예상시간 보완

콜백(#9) 누락·화면 재진입·통신 실패 복구나 지속 갱신(지도 위 로봇 마커 등)을 위해 두 방식을 제공합니다 — 양자택일 권장.

#4-A 위치 단발 조회 (REST): GET /v1/automata/dispatch/{orderId}/tracking — 위치·진행 단계(phase)·ETA(분). 폴링·1회 조회용.
#4-B 위치 스트리밍 (SSE): GET /v1/automata/dispatch/{orderId}/tracking/stream — text/event-stream으로 변경 시점에 push. position/heartbeat/complete/error 이벤트, terminal state(completed·canceled·failed) 진입 시 자동 close, 표준 Last-Event-ID 재연결, connection 30분 한도.
#5 고객 도착 예상시간: GET /v1/automata/dispatch/{orderId}/eta — 고객 도착 예상시간(분).

6. 배차 취소

POST /v1/automata/dispatch/{orderId}/cancel로 배차를 취소합니다. 단 출발 후에는 취소할 수 없습니다(5/22 룰) — 409 DISPATCH_NOT_CANCELABLE.

7. 콜백 재시도·중복 수신 무시

비스캣 콜백(#6~#9)은 2xx 응답을 받지 못하면 지수 백오프로 최대 24회/24시간 재시도합니다. 각 시도는 동일 X-Zeroworks-Delivery ID를 가지므로, 오토메타는 이 ID로 중복 수신을 무시해 중복 표출을 방지해야 합니다.

콜백 수신 시 확인할 헤더

X-Zeroworks-Event — 이벤트 종류(robot.shop_arrived 등)
X-Zeroworks-Signature — HMAC-SHA256(secret, body), 서명 검증 필수
X-Zeroworks-Timestamp — Unix timestamp(초 단위, 예: 1783644212)
X-Zeroworks-Delivery — 재시도 시 동일, 중복 수신 무시용 유니크 키

8. 시뮬레이션 테스트

실 로봇·실배송 없이 운영과 동일한 요청·응답·콜백 계약을 재현하는 시뮬레이터 엔드포인트를 제공합니다. 오토메타는 아래 순서로 연동을 미리 점검할 수 있습니다.

기본 정보

Base URL: https://fms-api.zeroworks.co.kr
시뮬 경로: /dev/automata/... — 운영 /v1/automata/...와 prefix만 다르고 이후 경로·페이로드·응답 계약은 동일합니다.
인증: 운영과 동일. 모든 요청에 X-Api-Key-Id: automata + X-Api-Key: {발급 키} 필수(누락 시 401).
콜백 수신: 콘솔(서비스 설정)에 등록한 콜백 URL로 비스캣이 발신하며, 서명·재시도 규약은 §7과 동일합니다.

테스트 순서

연결·인증 확인: GET /dev/automata/ping → authenticated: true 200.
배송 가능 여부: POST /dev/automata/delivery/availability → { available, etaMinutes }.
배차: POST /dev/automata/dispatch (Idempotency-Key 필수) → { missionId, robotId, userPin, boxSlots, status }. 배차 성공 시점부터 아래 콜백이 자동 발신됩니다.
진행 조회: GET /dev/automata/dispatch/{orderId}/tracking · .../eta — 경과에 따라 phase가 to_shop → at_shop → to_household → at_household로 진행.
박스 개폐(하차): 세대 도착(at_household) 이후 POST /dev/automata/dispatch/{orderId}/unlock → OPENED. 도착 전 호출은 409 UNLOCK_NOT_READY.
배차 취소(선택): POST /dev/automata/dispatch/{orderId}/cancel — 출발 전만 가능.

자동 발신되는 콜백 타임라인

배차 후 경과 시간에 맞춰 아래 콜백을 등록된 콜백 URL로 자동 발신합니다(§4와 동일 이벤트·형식·서명).

배차 후	이벤트(`X-Zeroworks-Event`)	내용
즉시	`notify.event`(NOTI_DISPATCHED) · `delivery.status_changed`(scheduled)	배차됨
~30초	`robot.shop_arrived` (#6)	매장 도착(점주 PIN 포함)
~45초	`delivery.departed` (#7) · `notify.event`(NOTI_PICKED_UP)	상차·출발
~67초	`notify.event`(NOTI_ETA_5MIN)	도착 임박
~90초	`delivery.status_changed`(arrived, #8) · `notify.event`(NOTI_ARRIVED)	세대 도착 → 하차 대기
unlock 호출 시	`delivery.status_changed`(unloaded, #8) · `notify.event`(NOTI_DELIVERED)	하차 완료

대면 배송(autoDropoff: false) 기준. 세대 도착 후 unloaded 콜백은 실제 unlock 호출 시점에 발신되며, 그 전까지 로봇은 문 앞에서 대기합니다.

테스트 시 유의

orderId는 오토메타 시스템의 실제 주문번호를 사용하세요. 콜백이 이 orderId를 그대로 실어 오므로, 미실재 주문번호는 수신부에서 인식·매칭되지 않습니다.
각 콜백의 서명을 검증하세요(§7) — HMAC-SHA256(콜백 서명 키, body 원문).
시뮬은 가상 데이터로 응답하며 미션 상태는 인메모리로만 유지됩니다(서버 재시작 시 소멸). availability·dispatch는 실 체감 재현을 위해 응답까지 최대 10초 소요될 수 있습니다.

시나리오·페이로드가 협의로 바뀌면 본 문서와 연동 API 문서를 함께 갱신하세요.