오토메타 연동 API 문서

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

1. 공통 규약

Base URL: https://api.{env}.biscat.example.com/v1 (env=prod·staging·dev)
전송: TLS 1.2+, Content-Type: application/json; charset=utf-8
응답 봉투: 성공·에러 모두 {success, data?, error?, meta?} 구조
시간: ISO 8601 UTC · 식별자: UUID v7
인바운드 인증: X-Api-Key, X-Api-Key-Id (또는 mTLS)
멱등성: 배차 요청은 Idempotency-Key 필수, 그 외 POST는 권장 (24h 캐시)
아웃바운드 콜백 인증: X-Biscat-Signature(HMAC-SHA256), X-Biscat-Timestamp, X-Biscat-Delivery

2. 10종 API 목록

#	API	방향	Method / Path	인증
1	배송 가능 여부 (결제 전)	오토메타 → 비스캣	POST `/v1/automa/delivery/availability`	API Key
2	로봇 배차 요청	오토메타 → 비스캣	POST `/v1/automa/dispatch`	API Key + Idempotency
3	로봇 배차 취소	오토메타 → 비스캣	POST `/v1/automa/dispatch/{robotId}/cancel`	API Key
4	~~로봇 상차 완료~~	삭제 (5/22 협의) — 박스 닫힘 = 출발 알림(#8)으로 통일
5	위치기반 실시간 배송정보	오토메타 → 비스캣	GET `/v1/automa/dispatch/{robotId}/tracking`	API Key
6	고객 도착 예상시간 조회	오토메타 → 비스캣	GET `/v1/automa/dispatch/{robotId}/eta`	API Key
7	매장(점포) 도착	비스캣 → 오토메타	POST `{콜백URL}` (`robot.shop_arrived`)	HMAC 서명
8	배달 출발 알림	비스캣 → 오토메타	POST `{콜백URL}` (`delivery.departed`)	HMAC 서명
9	배달 예정/도착/하차 완료	비스캣 → 오토메타	POST `{콜백URL}` (`delivery.status_changed`)	HMAC 서명
10	알림 노티 (신규)	비스캣 → 오토메타	POST `{콜백URL}` (`notify.event`)	HMAC 서명

{robotId}는 배차 응답(#2)으로 내려준 배차로봇ID입니다.

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

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

요청

{
  "deliveryType": "delivery|trash_pickup",   // 구분 (매장/쓰레기)
  "siteCode": "string",                       // 단지 사이트코드
  "shopId": "string",
  "shopName": "string"
}

200 응답

{ "success": true, "data": { "available": true, "shopEtaMinutes": 7 } }

에러 422 AUTOMA_INVALID_PAYLOAD

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

요청

{
  "shopId": "string",
  "shopName": "string",
  "orderId": "string",            // 요청주문ID (외부 식별자)
  "deliveryType": "delivery|trash_pickup",
  "siteCode": "string",
  "dong": "101",
  "ho": "1502",
  "ownerPin": "4821"              // 점주용 PIN — 고정 4자리, 오토메타가 동봉
}

202 응답

{
  "success": true,
  "data": {
    "missionId": "uuid",
    "robotId": "uuid",            // 배차로봇ID — 이후 #3·#5·#6에서 사용
    "shopEtaMinutes": 7,
    "userPin": "7390",            // 사용자 PIN — 비스캣 생성 랜덤 4자리
    "status": "CREATED",
    "expiresAt": "..."
  }
}

에러 409 ORDER_DUPLICATE, 422 AUTOMA_INVALID_PAYLOAD, 503 NO_ROBOT_AVAILABLE, 422 DISPATCH_LOAD_EXCEEDED (주문 수량이 박스 4칸 초과)

POST `/v1/automa/dispatch/{robotId}/cancel` — #3 배차 취소

요청	`{ "shopId": "string", "orderId": "string" }`
200 응답	`{ "success": true, "data": { "missionId": "uuid", "status": "ABORTED" } }`
에러	`404 DISPATCH_NOT_FOUND`, `409 DISPATCH_NOT_CANCELABLE` (출발 후 취소 불가)

GET `/v1/automa/dispatch/{robotId}/tracking` — #5 위치기반 실시간 배송정보

200 응답

{
  "success": true,
  "data": {
    "robotId": "uuid",
    "position": { "x": 0, "y": 0, "heading": 0 },
    "phase": "to_shop|at_shop|to_household|at_household|returning",
    "etaMinutes": 4
  }
}

GET `/v1/automa/dispatch/{robotId}/eta` — #6 고객 도착 예상시간

쿼리	`?shopId=...&shopName=...`
200 응답	`{ "success": true, "data": { "robotId": "uuid", "customerEtaMinutes": 4 } }`

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

#7~#10은 비스캣이 오토메타 콜백 URL로 발신합니다. 공통 봉투·서명·재시도를 따르며, X-Biscat-Event로 종류를 구분합니다.

콜백 요청 봉투

POST {콜백URL}
Headers:
  X-Biscat-Event: robot.shop_arrived | delivery.departed | delivery.status_changed | notify.event
  X-Biscat-Signature: HMAC-SHA256(secret, body)
  X-Biscat-Timestamp: ISO8601
  X-Biscat-Delivery: uuid (재시도 시 동일 → 멱등 키)

#7 매장 도착 `robot.shop_arrived`	`{ "shopId": "string", "shopName": "string", "orderId": "string", "robotId": "uuid", "pin": "4821" // 점주가 박스 개방에 입력할 핀번호 }`
#8 배달 출발 `delivery.departed`	`{ "shopId": "string", "shopName": "string", "orderId": "string", "robotId": "uuid" } // 박스 닫힘 트리거 (구 #4 상차완료 통합)`
#9 예정/도착/하차 `delivery.status_changed`	`{ "phase": "scheduled\|arrived\|unloaded", "shopId": "string", "orderId": "string", "robotId": "uuid", "etaMinutes": 4 }`
#10 알림 노티 `notify.event`	`{ "code": "NOTI_ETA_5MIN", // 상태 식별자 코드만 전달 "orderId": "string", "robotId": "uuid", "occurredAt": "..." } // 표출 문구는 오토메타가 관리`

재시도 정책

2xx 응답을 받지 못하면 지수 백오프로 최대 24회/24시간 재시도.
각 시도는 동일 X-Biscat-Delivery ID — 오토메타는 이 ID로 멱등 처리.
최종 실패는 비스캣 운영자 알림 + DLQ로 적재.

#10 알림 코드 ↔ 발생 시점 매핑(예: NOTI_ETA_5MIN 도착 5분 전, NOTI_ARRIVED 세대 도착)은 별도 코드 카탈로그로 관리하며, 양사 동기화의 단일 진실입니다.

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

코드	HTTP	의미
`AUTOMA_INVALID_PAYLOAD`	422	배송/배차 페이로드 검증 실패
`ORDER_DUPLICATE`	409	동일 `Idempotency-Key`로 다른 페이로드
`DISPATCH_LOAD_EXCEEDED`	422	주문 수량이 박스 4칸 초과 — 배차 거부
`NO_ROBOT_AVAILABLE`	503	디스패치 가능 로봇 없음 (정책상 거절)
`DISPATCH_NOT_FOUND`	404	취소 대상 배차 없음
`DISPATCH_NOT_CANCELABLE`	409	출발 후 취소 불가
`RATE_LIMIT_EXCEEDED`	429	레이트 리밋 초과 — `Retry-After` 준수

전체 에러 카탈로그·멱등성·버전 정책은 비스캣 API 공통 규약을 따릅니다. 규약 상세는 비스캣 담당자를 통해 제공됩니다.