오토메타 연동 API 문서

오토메타 ↔ 비스캣 10종 API의 엔드포인트·페이로드·인증·재시도 규약입니다. 10종 모두 비스캣이 작성·제공합니다. 동작 흐름은 개발 시나리오를 함께 참조하세요.

1. 공통 규약

• Base URL: https://fms-api.zeroworks.co.kr (운영 도메인 통일 — 환경별 분리가 필요한 경우 호스트 별도 안내). 버전 세그먼트 /v1은 각 엔드포인트 경로에 포함됩니다.
• 전송: TLS 1.2+, Content-Type: application/json; charset=utf-8
• 공통 응답 형식: 성공·실패 모두 동일 형식 — { "result": <ResultCode>, "data"?: object|string, "message"?: string }. result는 결과 코드 enum으로, SUCCESS·FAIL(일반 실패) 외 도메인별 구체 코드(SHOP_NOT_FOUND·NO_ROBOT_AVAILABLE·ORDER_DUPLICATE·VALIDATION_FAILED 등)가 사용됨. data·message는 있을 때만 노드 발현. message는 주로 실패 사유 설명에 사용
• 시간: ISO 8601, 타임존 +09:00 (KST) — 비스캣이 응답·콜백으로 내보내는 모든 시각이 동일 표기 (예: 2026-06-04T14:30:00+09:00) · 식별자: UUID v7
• 인바운드 인증: 두 헤더 모두 필수 — X-Api-Key-Id(발급받은 업체 식별자, 예: automata) + X-Api-Key(비스캣이 발급한 고정 키). 서버는 업체별 키 대조로 인증합니다(불일치·미지 식별자 시 401 UNAUTHORIZED). 아래 「API 키 취급 주의」 참조
• 유니크 키 (재시도 안전): 배차 요청은 Idempotency-Key 헤더 필수, 그 외 POST는 권장 (24h 캐시 — 같은 키 재호출 시 첫 응답 그대로 반환)
• 아웃바운드 콜백 인증: X-Zeroworks-Signature = HMAC-SHA256(secret, body), X-Zeroworks-Timestamp, X-Zeroworks-Delivery

2. 10종 API 목록

URL 경로의 {orderId}는 오토메타가 발급한 전역 유니크 요청ID로, 후속 호출(#3·#4·#5·#10)·콜백(#6~#9)의 주키로 사용됩니다. 오토메타는 별도 robotId를 보관할 필요가 없습니다 — 배차 응답으로 내려가는 robotId는 표시·로그용 정보성 필드입니다.

3. 인바운드 (오토메타 → 비스캣)

POST /v1/automata/delivery/availability — #1 배송 가능 여부

shopId(매장, 필수)·dong·ho(세대, 필수)·boxCount(필요 박스 수, 필수)를 견적에 전달하면, 로봇이 점포·세대까지의 도착 예상시간을 합산한 etaMinutes를 산출하고 박스 수용 가능 여부까지 반영해 available을 판정합니다. deliveryType이 trash_pickup(쓰레기 픽업)이어도 세대가 픽업 지점이므로 dong·ho는 동일하게 필수입니다. 견적도 배차(#2)와 동일하게 매장(shopId)·세대(dong·ho) 목적지 노드가 모두 매핑돼야 하며, 없으면 로봇 견적(offer) 전 422 DESTINATION_NOT_MATCHED로 거부됩니다.

{
  "deliveryType": "delivery|trash_pickup", // 구분 (매장/쓰레기)
  "siteId": "APT-1023",                     // 단지코드
  "shopId": "string",                       // 매장(점포) ID (필수)
  "dong": "101",                            // 세대 동 (필수)
  "ho": "1502",                             // 세대 호 (필수)
  "boxCount": 2                             // 필요한 박스 수 (1~4, 필수)
}

{
  "result": "SUCCESS",
  "data": {
    "available": true,
    "etaMinutes": 11           // 점포+세대 도착 예상시간 합(분)
  }
}

available=false이거나 견적 요청이 타임아웃되면 etaMinutes는 null입니다.

POST /v1/automata/dispatch — #2 로봇 배차 요청

주문 필드: orderId · deliveryType · shopId · siteId · dong · ho · boxCount · ownerPin. dong·ho(세대)·boxCount는 #1과 동일한 세대·박스 입력 정책으로 필수이며, 누락 시 422 AUTOMA_INVALID_PAYLOAD로 거부됩니다. 비대면/대면 방식은 배차 로봇의 설정(auto_drop_off)에 따라 비스캣이 결정하며, 그 결과를 응답 autoDropoff로 알려줍니다. 비스캣은 대면 배송 시(autoDropoff: false) 항상 userPin(4자리)을 발행해 응답에 동봉합니다.

{
  "shopId": "string",
  "shopName": "string",
  "orderId": "string",            // 요청ID (외부 식별자)
  "deliveryType": "delivery|trash_pickup",
  "siteId": "APT-1023",           // 단지코드
  "dong": "101",                  // 세대 동 (필수)
  "ho": "1502",                   // 세대 호 (필수)
  "boxCount": 2,                  // 필요한 박스 수 (1~4, 필수) — 주문 수량 기준
  "ownerPin": "4821"              // 점주용 PIN — 고정 4자리, 오토메타가 동봉
}

{
  "result": "SUCCESS",
  "data": {
    "missionId": "uuid",
    "robotId": "uuid",            // 배차로봇ID — 정보성(표시·로그용). 후속 호출 주키는 orderId
    "etaMinutes": 7,              // 도착 예상시간(분) — 점포+세대 도착 예상시간 합(#1 견적과 동일 집계)
    "autoDropoff": false,         // 배차 로봇의 비대면 하차 가능 여부 — true=비대면(자동 하차), false=대면(userPin 필요)
    "userPin": "7390",            // 사용자 PIN — 비스캣 생성 랜덤 4자리 (대면 배송 시 항상 발행)
    "boxSlots": [1, 3],           // 적재할 박스 번호 배열 (관제 할당, 1~4)
    "status": "CREATED",
    "expiresAt": "2026-06-04T14:30:00+09:00"
  }
}

POST /v1/automata/dispatch/{orderId}/cancel — #3 배차 취소

{ "shopId": "string" }                  // orderId는 URL 경로

{ "result": "SUCCESS", "data": { "missionId": "uuid", "status": "ABORTED" } }

GET /v1/automata/dispatch/{orderId}/tracking — #4-A 위치기반 실시간 배송정보 (단발 조회)

화면 재진입·통신 실패 복구처럼 드물게 1회 가져갈 때. 지속 갱신은 #4-B SSE 권장 (양자택일).

{
  "result": "SUCCESS",
  "data": {
    "robotId": "uuid",
    "position": { "x": 0, "y": 0, "th": 0 },
    "phase": "to_shop|at_shop|to_household|at_household|returning",
    "etaMinutes": 4
  }
}

GET /v1/automata/dispatch/{orderId}/tracking/stream — #4-B 위치기반 실시간 배송정보 (SSE 스트리밍)

지도 위 로봇 마커 등 지속 갱신용. 비스캣이 위치·상태 변경 시점에 push.

event: position
id: 1716893405000
data: {"robotId":"uuid","position":{...},"phase":"to_shop","etaMinutes":4}

event: heartbeat
data: {}

event: position
id: 1716893490000
data: {"robotId":"uuid","position":{...},"phase":"at_household","etaMinutes":0}

event: complete
data: {"finalStatus":"completed"}

GET /v1/automata/dispatch/{orderId}/eta — #5 고객 도착 예상시간

{ "result": "SUCCESS", "data": { "robotId": "uuid", "etaMinutes": 4 } }

POST /v1/automata/dispatch/{orderId}/unlock — #10 박스 개폐 (하차)

대면 배송(autoDropoff: false)에서 주문자가 오토메타 앱(WEB)에서 박스를 여는 원격 개폐입니다. 앱이 orderId로 unlock을 요청하면 비스캣이 해당 주문에 배차된 로봇의 박스를 엽니다. 로봇이 고객 위치에 도착(arrived)한 뒤에만 허용됩니다.

{ "shopId": "string" }                  // orderId는 URL 경로

{ "result": "SUCCESS", "data": { "missionId": "uuid", "boxSlots": [1, 3], "status": "OPENED" } }

4. 아웃바운드 콜백 (비스캣 → 오토메타)

#6~#9는 비스캣이 오토메타 콜백 URL로 발신합니다. 공통 형식·서명·재시도를 따르며, X-Zeroworks-Event로 종류를 구분합니다.

콜백 요청 형식

POST {콜백URL}
Headers:
  X-Zeroworks-Event: robot.shop_arrived | delivery.departed | delivery.status_changed | notify.event
  X-Zeroworks-Signature: HMAC-SHA256(secret, body)   // secret = 콘솔(서비스 설정)에서 발급받은 콜백 서명 키, 대상 = 요청 body 원문
  X-Zeroworks-Timestamp: Unix timestamp (초 단위, 예: 1783644212)
  X-Zeroworks-Delivery: uuid (재시도 시 동일 → 중복 수신 무시용 유니크 키)

서명 검증: secret은 콘솔(서비스 설정)에서 발급받은 콜백 서명 키입니다. 수신 시 HMAC-SHA256(secret, 수신 body 원문)을 계산해 X-Zeroworks-Signature와 일치하는지 확인하세요 (대상은 body 원문 그대로 — timestamp 등은 서명에 포함하지 않음. timestamp·delivery는 별도 헤더).

{
  "shopId": "string",
  "orderId": "string", "robotId": "uuid",
  "boxSlots": [1, 3],            // 적재할 박스 번호 배열 (1~4)
  "pin": "4821"                  // 점주가 박스 개방에 입력할 핀번호
}

{
  "shopId": "string",
  "orderId": "string", "robotId": "uuid"
}                                // 박스 닫힘이 출발 트리거

{
  "phase": "scheduled|arrived|unloaded",
  "shopId": "string",
  "orderId": "string", "robotId": "uuid",
  "etaMinutes": 4
}

{
  "code": "NOTI_ETA_5MIN",     // 상태 식별자 코드만 전달
  "orderId": "string", "robotId": "uuid",
  "occurredAt": "2026-06-04T14:30:00+09:00"
}                              // 표출 문구는 오토메타가 관리

알림 코드 카탈로그

비스캣은 코드(상태 식별자)만 콜백으로 전달하고, 사용자 표출 문구·최종 표출 채널은 오토메타가 관리합니다. 아래는 콜백 발행 대상 코드입니다. 표출 채널·임계값(N·M분)·최종 코드명은 제안값이며 협의로 확정합니다.

5. 에러 코드 (주문·배차 관련 발췌)

5.1 NO_ROBOT_AVAILABLE 사유

HTTP 상태(503)와 result(NO_ROBOT_AVAILABLE)는 사유와 무관하게 동일하다. 구분이 필요하면 message 를 본다 — 아래 문구로 시작한다. 문구는 안내용이며 분기 조건으로 삼지 말 것 (신규 사유가 추가될 수 있다). 목록에 없는 사유는 입찰 가능한 로봇 없음 으로 떨어진다.