제로웍스 연동 API 문서

제로웍스 로봇이 비스캣 코어와 주고받는 채널·엔드포인트·페이로드·인증 규약입니다. 동작 흐름은 개발 시나리오를 함께 참조하세요.

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-Robot-ID, X-Robot-Ts, X-Robot-Signature
멱등성: POST는 Idempotency-Key 헤더 권장 (24h 캐시)
레이트 리밋: 폴링 10 req/s per 로봇. 429 수신 시 Retry-After에 따라 지수 백오프.

2. 인증 (REST)

POST `/v1/robot/key` — 비밀키 발급 (1회)

인증	없음 (사전 등록된 robotId + 공개키)
요청	`{ "robotId": "uuid", "publicKey": "base64-encoded PEM" }`
200 응답	`{ "success": true, "data": { "secretKeyEncrypted": "base64", // 로봇 공개키로 암호화된 HMAC 비밀키 "issuedAt": "2026-05-21T10:00:00Z" } }`
에러	`404 ROBOT_NOT_REGISTERED`, `409 ROBOT_ALREADY_ACTIVATED`

POST `/v1/robot/cert` — X.509 인증서 발급 (1회용 URL)

인증	HMAC (로봇)
200 응답	`{ "success": true, "data": { "downloadUrl": "https://...", "expiresIn": 600 } }`

HMAC 서명 방식

발급받은 비밀키로 요청을 서명합니다. X-Robot-Ts는 ±60초 윈도우를 벗어나면 ROBOT_TIMESTAMP_OUT_OF_WINDOW로 거절(replay 방지)됩니다. 서명 대상 문자열 구성(메서드·경로·timestamp·body 해시)은 결합 시 키 관리 가이드와 함께 확정합니다.

3. FMS 폴링·점유 (REST)

POST `/v1/fms/command` — 폴링·응답 단일 엔드포인트

인증	HMAC (로봇)
레이트 리밋	10 req/s per 로봇
요청 (요청 모드)	`{ "mode": "request", "robotMode": "none\|serving\|calling\|charging\|error", "battery": 85, "position": { "x": 0, "y": 0, "heading": 0 } }`
200 응답 (요청 모드)	`{ "success": true, "data": { "commands": [ { "commandId": "uuid", "missionId": "uuid", "type": "anyone", "targetRobots": ["modelNoA", "modelNoB"], "missionType": "delivery\|trash_pickup", "payload": { /* 미션별 — boxSlot 등 */ } } ] } }`
요청 (응답 모드)	`{ "mode": "response", "executions": [ { "commandId": "uuid", "executionTime": 0 } // 0 = 즉시 수행 → 점유 ] }`
200 응답 (응답 모드)	`{ "success": true, "data": { "claimed": [ { "commandId": "uuid", "missionId": "uuid" } ], "rejected": [ { "commandId": "uuid", "reason": "already_claimed\|expired\|mode_mismatch" } ] } }`

4. 로봇 → 코어 인바운드 (SQS) 페이로드 협의 대기

주행 중 발생하는 이벤트는 AWS SQS로 코어에 전달됩니다. 공통 봉투(requestId·occurredAt·source="robot"·complexId·payload)에 담아 보냅니다.

kind	의미	payload 주요 필드
`arrived`	매장·세대 도착	위치, 도착 지점 구분
`state`	상태·배터리·위치 보고	`robotMode`, `battery`, `position`
`error`	장애 보고	오류 코드·상세 → 운영자 알림 생성
`pin_verify_request`	점주/사용자 PIN 검증 요청	`boxSlot`, `pin`(4자리), `pinType: "owner"\|"user"`
`box_closed`	비대면 상차 감지 (박스 닫힘)	닫힘 센서 결과 — 배달 출발 트리거

// PIN 검증 요청 페이로드 (pin_verify_request)
{
  "robotId": "uuid",
  "boxSlot": 1,                // 1~4
  "pin": "7390",              // 입력된 4자리
  "pinType": "owner" | "user" // 점주(고정) / 사용자(랜덤)
}

pin_verify_request·box_closed의 구체 센서 페이로드 형식과 PIN 입력 채널(점주 KDS / 사용자 박스 키패드)은 제로웍스 펌웨어와 협의 후 확정합니다.

5. 코어 → 로봇 아웃바운드 (MQTT) 페이로드 협의 대기

코어의 응답·지시는 AWS IoT Core(MQTT)로 로봇에 전달됩니다. stream으로 종류를 구분합니다.

stream	의미	payload 주요 필드
`pin_verify_result`	PIN 검증 결과	`ok`, `boxSlot`, `reason?`
`box_assign`	적재함 칸 할당·개폐 지시	`boxSlot`(1~4), `action: "open"\|"lock"`
`arrive` / `state` / `error`	응답 채널 ack·상태 동기화	이벤트별
`replan`	경로 수정 지시 (1차 자리만, 로그 적재)	수정 경로 정보

// 칸 할당 지시 (box_assign)
{
  "robotId": "uuid",
  "missionId": "uuid",
  "boxSlot": 1,               // 코어가 주문 수량 기반으로 결정
  "action": "open" | "lock"
}

6. 에러 코드 (로봇 관련 발췌)

코드	HTTP	의미
`ROBOT_SIGNATURE_INVALID`	401	HMAC 서명 검증 실패
`ROBOT_TIMESTAMP_OUT_OF_WINDOW`	401	timestamp ±60s 윈도우 초과 (replay 의심)
`ROBOT_CERT_REVOKED`	401	인증서 폐기됨
`ROBOT_NOT_REGISTERED`	404	사전 등록되지 않은 robotId
`ROBOT_ALREADY_ACTIVATED`	409	비밀키 1회 발급 정책 위반
`MISSION_ALREADY_CLAIMED`	409	이미 다른 로봇이 점유
`MISSION_EXPIRED`	409	만료 미션 점유 시도
`RATE_LIMIT_EXCEEDED`	429	레이트 리밋 초과 — `Retry-After` 준수

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