제로웍스 연동 API 문서

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

본 문서의 JSON 본문은 예시 값이며, 값 자체에 의미를 두지 않습니다.

1. 공통 규약

• 채널 구분: REST는 등록·인증(§2)과 맵 등록(§7)에 사용하고, 이후 로봇↔관제 전 메시지(미션 입찰·상태·알람·PIN·박스)는 MQTT로 주고받습니다(§3~§6).
• REST Base URL: https://fms-api.zeroworks.co.kr (인증 endpoint — 환경별 분리가 필요한 경우 호스트 별도 안내)
• 전송: REST는 TLS 1.2+ / application/json; charset=utf-8. MQTT는 TLS + X.509 상호 인증 위 JSON 페이로드.
• REST 공통 응답 형식: 성공·실패 모두 동일 형식 — { "result": <ResultCode>, "data"?: object|string, "message"?: string }. result는 결과 코드 enum으로, SUCCESS·FAIL(일반 실패) 외 도메인별 구체 코드(ROBOT_NOT_REGISTERED·ROBOT_SIGNATURE_INVALID 등)가 사용됨. data·message는 있을 때만 노드 발현.
• MQTT 메시지 envelope: 모든 메시지는 최상위에 occurredAt(ISO8601, +09:00 KST)·payload를 두고, 행위를 트리거하는 이벤트·명령(입찰·알람·PIN·박스 등)에는 멱등 처리를 위한 requestId(UUID v7)를 함께 둡니다(§3).
• 식별자·시간: 식별자는 UUID v7. 시각은 ISO 8601, 타임존 +09:00(KST) — 모든 시각을 동일 표기 (예: 2026-06-04T14:30:00+09:00).
• 상태 어휘(status) 통일: state.status·goal.status·mission.status는 계층과 무관하게 같은 어휘를 씁니다 — standby(대기) · doing(수행 중) · done(완료), 취소는 canceled. 계층마다 다른 낱말(ready·going·arrived)은 쓰지 않습니다(아래 callout).
• REST 인증 헤더: X-Robot-ID, X-Robot-Ts, X-Robot-Signature (인증 endpoint 한정)

2. 인증 (REST)

등록·인증은 REST로 진행합니다. 키쌍은 로봇이 직접 생성하며, 개인키는 디바이스 밖으로 내보내지 않습니다(TPM·보안 칩 권장).

키 발급 절차

1. 키쌍 생성 — 로봇이 공개키/개인키 쌍을 디바이스 내부에서 생성.
2. 공개키 제출 — 사전 등록된 robotCode(예: R-001)와 함께 로봇의 공개키를 POST /v1/robot/key로 제출. 관제가 robotCode 로 로봇을 조회해 내부 식별자 robotId(UUID)를 회신하며, 로봇은 이후 인증에 robotId 를 사용한다.
3. 비밀키 수령 — 서버가 HMAC 비밀키를 로봇 공개키로 암호화해 응답 → 로봇이 개인키로 복호화해 보관.
4. 인증서 발급 — POST /v1/robot/cert로 X.509 인증서 번들(다운로드 URL 목록) 수령 → 설치 후 MQTT 연결.
5. 요청 서명 — 이후 모든 REST 인증 요청에 HMAC-SHA256 서명 헤더 부착.

암호화·서명 규격 비스캣 제안 — 협의 확정 대상

로봇(Ubuntu·C++/OpenSSL)과 관제가 상호운용하도록 아래 규격을 제안합니다. 모든 문자열은 UTF-8, base64는 표준(RFC 4648, 개행 없음)입니다.

위 값은 비스캣 제안 규격이며 제로웍스 확인 후 확정합니다. 인증서 발급은 현재 서버 생성(원클릭) + 다운로드 URL 번들 방식이며, 필요 시 CSR 서명 방식(로봇이 mTLS 키 생성·CSR 제출, 개인키 미전송)으로 협의 가능합니다. 협의 확정 대상

POST /v1/robot/key — 비밀키 발급

{ "robotCode": "R-001", "publicKey": "base64(SPKI DER)" }   // robotCode = 관리자 등록 식별자, publicKey = RSA-2048 공개키(DER SubjectPublicKeyInfo → base64)

{
  "result": "SUCCESS",
  "data": {
    "robotId": "uuid",                // 관제가 robotCode 로 조회해 반환하는 내부 식별자 — 이후 인증·MQTT 에 사용
    "secretKeyEncrypted": "base64",   // 로봇 공개키로 암호화된 HMAC 비밀키
    "issuedAt": "2026-05-21T10:00:00+09:00"
  }
}

POST /v1/robot/cert — X.509 인증서 발급 (다운로드 URL 목록)

관제가 AWS IoT Core에 로봇 Thing(thingName = robotId)과 X.509 인증서를 발급하고, 인증서 번들을 저장한 뒤 파일별 다운로드 URL 목록을 회신합니다. 로봇은 각 URL로 파일을 내려받아 설치하고 mTLS로 MQTT에 연결합니다.

{
  "result": "SUCCESS",
  "data": {
    "files": [                          // 번들 파일별 다운로드 URL
      { "name": "certificate.pem.crt", "url": "https://.../certificate.pem.crt?..." },
      { "name": "private.pem.key",     "url": "https://..." },
      { "name": "public.pem.key",      "url": "https://..." },
      { "name": "AmazonRootCA1.pem",   "url": "https://..." }
    ],
    "expiresIn": 600                    // 다운로드 URL 유효기간(초)
  }
}

발급 인증서에는 로봇 정책(zws-iot-policy-fms, Thing 변수 기반)이 부착되어 로봇은 자기 토픽만 pub/sub 합니다. 번들은 암호화 저장되며, 다운로드 URL은 expiresIn 경과 시 만료됩니다.

재발급 정책 — 로봇은 등록·인증으로 비밀키·인증서를 발급받으며, 이미 발급(활성화)된 로봇이 /key·/cert를 다시 호출하면 409 ROBOT_ALREADY_ACTIVATED로 거절됩니다. 재발급(인증서 회전)이 필요하면 관제 관리자 초기화 후 다시 발급받으며, 이때 이전 Thing·인증서·번들은 폐기됩니다.

POST
/v1/robot/cert
2026-07-08T14:30:00+09:00
44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a

C++/OpenSSL 레퍼런스 구현 비스캣 제안

로봇(Ubuntu · C++)에서 위 규격을 구현하는 최소 예제입니다. OpenSSL 3.x 기준(빌드: g++ auth.cpp -lssl -lcrypto)이며, 지면상 에러 처리는 생략했습니다. HTTP 호출·JSON 파싱은 libcurl·nlohmann/json 등 임의 라이브러리를 사용합니다.

① 공통 헬퍼 (base64 · hex · SHA-256 · HMAC)

#include <openssl/evp.h>
#include <openssl/hmac.h>
#include <string>
#include <vector>
#include <stdexcept>

static std::string toHex(const unsigned char* d, size_t n) {
    static const char* h = "0123456789abcdef";
    std::string s; s.reserve(n * 2);
    for (size_t i = 0; i < n; ++i) { s += h[d[i] >> 4]; s += h[d[i] & 0xf]; }
    return s;
}

// 표준 base64(RFC 4648, 개행 없음)
static std::string b64encode(const unsigned char* d, int n) {
    std::string out(4 * ((n + 2) / 3), '\0');
    int len = EVP_EncodeBlock((unsigned char*)out.data(), d, n);
    out.resize(len);
    return out;
}
static std::vector<unsigned char> b64decode(const std::string& in) {
    std::vector<unsigned char> out(3 * (in.size() / 4) + 3);
    int len = EVP_DecodeBlock(out.data(), (const unsigned char*)in.data(), (int)in.size());
    if (len < 0) throw std::runtime_error("base64 decode 실패");
    if (!in.empty() && in.back() == '=') len--;            // 패딩 보정
    if (in.size() >= 2 && in[in.size() - 2] == '=') len--;
    out.resize(len);
    return out;
}

static std::string sha256Hex(const std::string& data) {
    unsigned char md[EVP_MAX_MD_SIZE]; unsigned int n = 0;
    EVP_Digest(data.data(), data.size(), md, &n, EVP_sha256(), nullptr);
    return toHex(md, n);
}
static std::string hmacSha256Hex(const std::string& key, const std::string& msg) {
    unsigned char mac[EVP_MAX_MD_SIZE]; unsigned int n = 0;
    HMAC(EVP_sha256(), key.data(), (int)key.size(),
         (const unsigned char*)msg.data(), msg.size(), mac, &n);
    return toHex(mac, n);
}

② 키쌍 생성 · 공개키 인코딩

#include <openssl/rsa.h>
#include <openssl/x509.h>   // i2d_PUBKEY

// RSA-2048 키쌍 생성. 개인키는 디바이스에 안전 저장(예: PEM_write_PrivateKey_ex), 외부 반출 금지.
EVP_PKEY* generateRobotKeyPair() { return EVP_RSA_gen(2048); }   // OpenSSL 3.0+

// 공개키 → base64(SPKI DER). POST /v1/robot/key 의 publicKey 필드에 그대로 사용.
std::string publicKeyB64(EVP_PKEY* pkey) {
    unsigned char* der = nullptr;
    int len = i2d_PUBKEY(pkey, &der);        // SubjectPublicKeyInfo(DER)
    if (len <= 0) throw std::runtime_error("i2d_PUBKEY 실패");
    std::string b64 = b64encode(der, len);
    OPENSSL_free(der);
    return b64;
}

③ 비밀키 복호화 (RSA-OAEP · SHA-256/MGF1 SHA-256)

// secretKeyEncrypted(base64) → HMAC secret 문자열. OAEP 해시 SHA-256 / MGF1 SHA-256.
std::string decryptSecret(EVP_PKEY* priv, const std::string& secretKeyEncryptedB64) {
    std::vector<unsigned char> ct = b64decode(secretKeyEncryptedB64);
    EVP_PKEY_CTX* ctx = EVP_PKEY_CTX_new(priv, nullptr);
    EVP_PKEY_decrypt_init(ctx);
    EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING);
    EVP_PKEY_CTX_set_rsa_oaep_md(ctx, EVP_sha256());
    EVP_PKEY_CTX_set_rsa_mgf1_md(ctx, EVP_sha256());   // ← SHA-256 로 명시(서버와 일치)
    size_t outLen = 0;
    EVP_PKEY_decrypt(ctx, nullptr, &outLen, ct.data(), ct.size());
    std::string secret(outLen, '\0');
    EVP_PKEY_decrypt(ctx, (unsigned char*)secret.data(), &outLen, ct.data(), ct.size());
    secret.resize(outLen);
    EVP_PKEY_CTX_free(ctx);
    return secret;   // 그대로 HMAC 키로 사용 — base64 디코드 금지
}

④ 타임스탬프 · HMAC 서명 헤더

#include <ctime>

// ISO-8601 KST (예: 2026-07-08T14:30:00+09:00). NTP 로 시각 동기 필요(±60초).
std::string nowKstIso8601() {
    std::time_t t = std::time(nullptr) + 9 * 3600;   // UTC+9
    std::tm tm{}; gmtime_r(&t, &tm);
    char buf[40];
    std::strftime(buf, sizeof(buf), "%Y-%m-%dT%H:%M:%S+09:00", &tm);
    return buf;
}

// POST /v1/robot/cert 서명 헤더 구성.
void buildCertHeaders(const std::string& robotId, const std::string& secret,
                      std::string& xId, std::string& xTs, std::string& xSig, std::string& body) {
    body = "{}";
    xId  = robotId;
    xTs  = nowKstIso8601();
    // 정규화: {METHOD}\n{path}\n{X-Robot-Ts}\n{sha256hex(body)}
    std::string canonical = "POST\n/v1/robot/cert\n" + xTs + "\n" + sha256Hex(body);
    xSig = hmacSha256Hex(secret, canonical);
}

⑤ 호출 순서

int main() {
    EVP_PKEY* priv = generateRobotKeyPair();
    std::string pub = publicKeyB64(priv);

    // 1) POST /v1/robot/key   body: {"robotCode":"R-001","publicKey":pub}
    //    응답(data): robotId, secretKeyEncrypted        (HTTP·JSON 은 libcurl·nlohmann/json 등)
    std::string robotId   = /* 응답 파싱 */ "";
    std::string secretEnc = /* 응답 파싱 */ "";

    std::string secret = decryptSecret(priv, secretEnc);   // HMAC 키 확보

    // 2) POST /v1/robot/cert  (서명 헤더 + body {})
    std::string xId, xTs, xSig, body;
    buildCertHeaders(robotId, secret, xId, xTs, xSig, body);
    //   헤더:  X-Robot-ID: xId  ·  X-Robot-Ts: xTs  ·  X-Robot-Signature: xSig
    //   응답(data.files[]) 의 다운로드 URL 을 일반 HTTPS GET 으로 각각 다운로드 →
    //   certificate.pem.crt · private.pem.key · AmazonRootCA1.pem 으로 mTLS MQTT 접속(clientId=robotId).
    return 0;
}

3. MQTT 채널·토픽 네임스페이스 협의 대상

인증서 설치 후 로봇은 MQTT 브로커에 연결합니다. 토픽은 방향 프리픽스를 앞에 둔 {방향}/{robot_id}/{항목}/{명령} 형태입니다 — s2r(server→robot, 로봇 subscribe), r2s(robot→server, 로봇 publish). 브로커 정책으로 로봇은 r2s/{자기id}/#만 publish, s2r/{자기id}/#만 subscribe할 수 있어 디바이스 토픽이 격리됩니다.

3.1 운영자 개입 명령 — s2r/{robot_id}/action/set 비스캣 제안

운영자가 관제 화면에서 내리는 개입 지시를 로봇에 전달합니다. 미션 경로(§5)와 분리된 채널입니다 — 미션 원장의 상태를 바꾸는 것이 아니라 로봇의 현재 거동에 직접 개입하는 명령이기 때문입니다. 미션 자체를 끊는 것은 이 토픽이 아니라 goals/set이 담당합니다(아래 callout).

{
  "requestId": "uuid-v7",
  "occurredAt": "2026-09-26T14:00:00+09:00",
  "payload": {
    "action": "speed",                   // 개입 종류
    "params": { "limitKmh": 1.5 }        // action 별 인자. estop·resume 은 생략
  }
}

location 본문 규격은 §5.1 goals[].location과 같습니다(맵 로컬 좌표 x·y·th + map_id).

3.2 지시 수신 확인 — r2s/{robot_id}/ack 비스캣 제안

requestId를 실어 보내는 모든 s2r 지시에 대해 로봇이 받았는지·수행했는지·거절했는지를 회신합니다. 관제는 이 회신으로 지시의 종결을 판정하며, 회신이 없으면 「전송됨」에서 더 나아가지 않습니다.

{
  "requestId": "uuid-v7",              // 대상 s2r 지시의 requestId — 변형 없이 echo
  "occurredAt": "2026-09-26T14:00:00.480+09:00",
  "payload": {
    "topic": "action/set",             // 대상 토픽 (방향 프리픽스 제외)
    "result": "accepted",              // accepted | rejected | done
    "reason": null                     // rejected 일 때 사유 코드 (§10)
  }
}

3.3 소프트웨어 배포 — software/deploy · software/progress 비스캣 제안

관제가 컴포넌트별 버전을 지정해 배포를 지시하고, 로봇이 진행률을 보고합니다. 설치 결과는 기존 r2s/{robot_id}/software(인벤토리, retain)의 재발행으로 확정됩니다 — 배포 원장과 설치 현황이 두 곳으로 갈리지 않게 합니다.

① 배포 지시 — s2r/{robot_id}/software/deploy

{
  "requestId": "uuid-v7",
  "occurredAt": "2026-09-26T14:00:00+09:00",
  "payload": {
    "jobId": "ZWS-FWJ-...",              // 관제 발급 — progress 에 echo
    "components": [
      { "name": "navigation", "version": "1.4.2",
        "url": "https://.../navigation-1.4.2.tar.gz",
        "sha256": "9f2c..." }
    ],
    "scheduledAt": null                  // null = 즉시. 값이 있으면 그 시각 이후 설치
  }
}

주행 중에는 설치하지 않습니다 — 로봇은 미션이 없고 정지 상태일 때 설치하며, 지시 수신 시점이 주행 중이면 ack로 accepted를 보낸 뒤 대기합니다.

② 진행률·결과 — r2s/{robot_id}/software/progress

{
  "requestId": "uuid-v7",
  "occurredAt": "2026-09-26T14:03:12+09:00",
  "payload": {
    "jobId": "ZWS-FWJ-...",
    "component": "navigation",
    "progress": 64,                      // 0~100
    "status": "doing",                   // standby | doing | done | failed
    "reason": null                       // failed 일 때 사유 코드 (§10)
  }
}

컴포넌트 단위로 발행합니다. status=done 뒤에는 r2s/{robot_id}/software 인벤토리를 갱신 발행해 설치 버전을 확정합니다. failed는 해당 컴포넌트의 이전 버전이 유지됨을 뜻합니다(부분 적용 없음).

4. robot info — 상태·알람

4.1 상태 질의 — s2r/{robot_id}/state/get 예약 — 관제 미발행

{
  "requestId": "uuid",
  "occurredAt": "2026-06-04T10:00:00+09:00",
  "payload": { "fields": ["mode"] }     // 조회할 상태 필드 목록
}

상태 설정 — s2r/{robot_id}/state/set

관제가 일부 상태 필드를 설정합니다. 본문은 상태 발행과 동일 구조의 부분 집합을 사용합니다.

상태 발행 — r2s/{robot_id}/state

robot 상태가 변하는 필드값을 이벤트 단위로 로봇이 발행합니다. retain=true 권장. 자발·고빈도 텔레메트리이므로 requestId는 생략 가능하며 occurredAt으로 순서를 판단합니다.

{
  "occurredAt": "2026-06-04T10:00:00+09:00",
  "payload": {
    "online": true,
    "mode": "bringup",
    "status": "standby",
    "ems": ["button", "door", "LiDAR", "bumper"],
    "location_score": 0,
    "location": { "x": 0.0, "y": 0.0, "th": 0.0, "map_id": "" },
    "battery": {
      "voltage": 0, "current": 0, "soc": 0,
      "est_charge_complete": 0, "est_discharge_complete": 0,
      "soh": 0, "temperature": 0
    }
  }
}

도어 상태는 미션 컨텍스트(어느 오더의 어느 칸인지)에서 의미가 있으므로 state가 아니라 goals[].mission[].door[]로 발행합니다(§5). ems의 트리거 소스 door(도어로 인한 EMS)와는 별개입니다.

상태 확장 필드(주행 속도·내부 온도·센서 헬스·통신 품질·보유 맵 버전·누적 주행거리·가동 시간·충전 도킹)는 별도 문서 로봇 발행 항목 §2·§5에 정의되어 있으며, 같은 r2s/{robot_id}/state 페이로드에 함께 싣습니다.

부분(delta) 전송 — 상태는 변동 필드만 실어 보내므로 한 페이로드에 모든 키가 오지 않습니다(실측: 위치만, {"online":false}만, mode+status만, 접속 시 전체 스냅샷). 관제는 occurredAt 기준 last-write-wins 로 최신값을 유지·병합합니다.

상태는 이 토픽 하나로 보냅니다 — 변동 주기가 서로 달라도(자주 바뀌는 위치 vs 드물게 바뀌는 battery soh/temperature vs 희소한 mode/status 전이) 토픽을 더 나누지 않습니다. 주기 차이는 위 부분(delta) 전송이 이미 흡수합니다 — 변하지 않은 값은 실리지 않으므로, 자주 바뀌는 값과 드물게 바뀌는 값이 한 토픽에 있어도 서로의 발행량을 끌어올리지 않습니다. 한 토픽으로 두면 동일 시점 상태도 occurredAt 기준으로 그대로 재구성됩니다.

채널을 가르는 기준은 빈도가 아니라 성질입니다 — 최신값만 의미 있어 덮어써도 되는 값(상태)은 이 토픽에 싣고, 발생 자체가 기록이라 놓치면 복구할 수 없는 것(이벤트)은 각자의 토픽(alarm·safety·software·geofence·goals)에 싣습니다.

4.2 알람 발행 — r2s/{robot_id}/alarm

{
  "requestId": "uuid",
  "occurredAt": "2026-06-04T10:00:00+09:00",
  "payload": {
    "alarm": [
      { "code": "0000", "level": "warn", "msg": "" },
      { "code": "1000", "level": "warn", "msg": "" }
    ]
  }
}

알람 리셋 — s2r/{robot_id}/alarm

{
  "requestId": "uuid",
  "occurredAt": "2026-06-04T10:00:00+09:00",
  "payload": { "alarm": "reset" }      // 알람 리셋 명령
}

5. goals info — 미션·입찰

로봇 서비스는 mode → goal → mission 3계층으로 정의합니다. mode는 로봇이 현재 무슨 서비스를 수행 중인지(robot 레벨), goal은 어디로 가는지(목적지 단위), mission은 그 지점에서 무엇을 하는지(동작)를 나타냅니다. 각 계층의 어휘는 서로 겹치지 않게 분리합니다 — 장소 성격은 goal.type, 동작은 mission.type에만 둡니다.

하나의 mission은 하나의 고객 오더 단위이며, 동일 mission.id가 여러 goal에 걸쳐 존재할 수 있습니다 — 예: 픽업 goal과 하차 goal이 같은 오더로 묶입니다. 미션을 로봇에 부여하는 경로는 입찰(goals/offer → bid → result)이며, 낙찰 통보가 곧 수행 개시 신호입니다. 부여 후 로봇은 r2s/{robot_id}/goals로 수행 상태를 발행하고, 관제가 중간에 상태를 바꿔 지시할 때만 goals/set(부분 갱신)을 씁니다. 멀티스톱 배송은 goal 배열로 표현합니다.

5.1 goal 본문 — s2r/{robot_id}/goals/offer · goals/set

goal은 mission[] 배열을 품습니다. 이 본문이 goal의 정본 구조이며, 관제가 goal 전체 정의를 실어 보내는 곳은 입찰 요청(goals/offer, §5.3 ①)입니다. 낙찰(goals/result) 통보를 받은 로봇은 offer 로 받아 둔 이 goal 을 그대로 수행합니다.

goals/set은 이미 부여된 goal·mission의 상태를 관제가 바꿔 지시할 때 쓰는 부분 갱신 채널입니다(아래 callout). 아래 예시는 한 오더의 픽업(매장 goal)·하차(고객 goal)가 같은 mission.id로 두 goal에 걸친 모습입니다.

{
  "requestId": "uuid",
  "occurredAt": "2026-06-04T10:00:00+09:00",
  "payload": {
    "goals": [
      {
        "id": "g-01a0324f-eb55-7ba6-a670-91ace2d98ca5-store",
        "type": "store",
        "status": "standby",
        "arrivalOrder": 1,
        "location": { "x": 0.0, "y": 0.0, "th": 0.0, "map_id": "" },
        "mission": [
          {
            "id": "m-01a0324f-eb55-7ba6-a670-91ace2d98ca5",
            "type": "pickup",
            "status": "standby",
            "atomic": true,
            "PIN": "5678",
            "door": [ { "name": "door2", "status": "closed" } ],
            "orderId": "ZWS-ORD-20260903...",
            "address": "",
            "addressDetail": "101동 1503호",
            "phoneNumber": "",
            "message": ""
          }
        ]
      },
      {
        "id": "g-01a0324f-eb55-7ba6-a670-91ace2d98ca5-customer",
        "type": "customer",
        "status": "standby",
        "arrivalOrder": 2,
        "location": { "x": 0.0, "y": 0.0, "th": 0.0, "map_id": "" },
        "mission": [
          {
            "id": "m-01a0324f-eb55-7ba6-a670-91ace2d98ca5",
            "type": "dropoff",
            "status": "standby",
            "atomic": true,
            "PIN": "1234",
            "door": [ { "name": "door2", "status": "closed" } ],
            "orderId": "",
            "address": "",
            "addressDetail": "",
            "phoneNumber": "",
            "message": ""
          }
        ]
      }
    ]
  }
}

// s2r/{robot_id}/goals/set — 매장 인증 단계 완료 지시(관제 문열림 처리 시)
{
  "requestId": "uuid",
  "occurredAt": "2026-09-03T14:00:00+09:00",
  "payload": {
    "goals": [
      { "id": "g-01a0324f-…-store", "mission": [ { "id": "…auth 단계 id…", "status": "done" } ] }
    ]
  }
}

5.2 goal 수행 발행 — r2s/{robot_id}/goals

수행 중 goal 상태(진행률·도착예상·상태)를 로봇이 발행합니다. retain=true. 일감이 없으면 goals: []로 보고합니다.

이 배열은 로봇이 들고 있는 미션 전체의 스냅샷입니다 — 동시에 여러 미션을 낙찰받으면 배열 하나에 모두 실어 보냅니다(실측 최대 4미션·goal 8개). 관제는 goal.id 접두로 미션을 가르므로 미션별로 토픽·메시지를 나눌 필요가 없습니다. 동시에 doing인 goal 은 하나이고 나머지는 standby로 줄 세워 둡니다.

{
  "requestId": "uuid",
  "occurredAt": "2026-06-04T10:00:00+09:00",
  "payload": {
    "goals": [
      {
        "id": "g-01a0324f-…-store",
        "type": "store",
        "status": "doing",
        "arrivalOrder": 1,
        "estArrival": "2026-06-04T10:07:00+09:00",
        "progress": 0,
        "location": { "x": 0.0, "y": 0.0, "th": 0.0, "map_id": "" },
        "mission": [
          { "id": "…move 단계 id…", "type": "move",   "status": "done",  "atomic": true, "orderId": "ZWS-ORD-…" },
          { "id": "…auth 단계 id…", "type": "auth",   "status": "doing", "atomic": true, "orderId": "ZWS-ORD-…" },
          { "id": "m-01a0324f-…",   "type": "pickup", "status": "standby", "atomic": true, "orderId": "ZWS-ORD-…" }
        ]
      }
    ]
  }
}

5.3 입찰 (offer → bid → result)

입찰은 3단계입니다. 관제가 후보 로봇에 offer로 제시 → 각 로봇이 bid로 goal별 도착 예상 시각 응답 → 관제가 전체 ETA(마지막 goal 도착 예상 시각 기준 남은 시간) 최소 로봇으로 배차를 결정(추후 적재공간 기준 포함)해 result로 낙찰 여부를 통보합니다. 어느 로봇이 수행할지의 최종 배차 결정은 관제가 단독으로 가집니다(배차 확정·충돌 방지).

① 입찰 요청 — s2r/{robot_id}/goals/offer

goal 전체 정의(§5.1 본문)를 그대로 실어 보냅니다 — id·type·status·arrivalOrder·location과 mission[](PIN·door·orderId·addressDetail·autoDropOff 포함). 낙찰 로봇은 이 본문을 그대로 수행하며, 별도의 goal 재전송은 없습니다.

따라서 goals/offer는 "입찰 요청"인 동시에 조건부 goal 부여입니다. 미낙찰 로봇은 result{claimed:false}를 받고 해당 goal 을 폐기합니다.

② 입찰 응답 — r2s/{robot_id}/goals/bid

quote/bid(§5.4 ②)와 동일한 스키마입니다 — 두 응답은 필드 구성이 같고, 쓰이는 맥락만 다릅니다.

{
  "requestId": "uuid",
  "occurredAt": "2026-06-04T10:00:00+09:00",
  "payload": {
    "goals": [
      { "id": "g-01a0324f-…-store",    "arrivalOrder": 1, "available": true, "estArrival": "2026-06-04T10:05:00+09:00", "reason": null },
      { "id": "g-01a0324f-…-customer", "arrivalOrder": 2, "available": true, "estArrival": "2026-06-04T10:12:00+09:00", "reason": null }
    ]
  }
}

offer 로 받은 goal 전부에 대해 응답합니다. 수행할 수 없으면 available=false·estArrival=null·reason(사유)으로 답합니다. 입찰하지 않겠다면 응답하지 않아도 됩니다(타임아웃으로 무응답 처리).

③ 입찰 결과 — s2r/{robot_id}/goals/result

offer 로 제시한 goal 전부에 낙찰 여부를 실어 보냅니다. 순서는 offer 와 동일합니다. 낙찰(claimed:true) 통보가 곧 주행 개시 신호이며, 관제는 이후 별도의 출발 지시(state/set 등)를 보내지 않습니다.

{
  "requestId": "uuid",
  "occurredAt": "2026-06-04T10:00:00+09:00",
  "payload": {
    "goals": [
      { "id": "g-01a0324f-…-store",    "claimed": true, "reason": null },
      { "id": "g-01a0324f-…-customer", "claimed": true, "reason": null }
    ]
  }
}

result는 bid 를 보낸 로봇에게만 발송됩니다. 무응답 로봇은 통보를 받지 않으므로, offer 를 받고 응답하지 않았다면 해당 goal 은 스스로 폐기해야 합니다.

5.4 배송 가능여부 견적 (quote) 운영 적용됨

주문이 확정되기 전, 관제가 후보 로봇에게 "지금 이 배송을 수행할 수 있는지"를 미리 물어 가용성·예상 도착시간을 받아 두는 사전 견적입니다. 미션(goal)을 생성하지 않는 비구속 질의이므로, 배차 입찰(§5.3 goals/*)과 토픽을 분리해 quote/* 네임스페이스로 운영합니다. 낙찰(result) 단계가 없어 입찰의 3단계를 2단계(질의 → 견적)로 축약하며, 응답(bid) 스키마는 배차 입찰과 완전히 동일합니다. 관제는 모든 goal 이 available인 로봇 중 전체 ETA(마지막 goal 도착 예상 시각 기준 남은 시간) 최소를 가용 ETA로 집계합니다(배차 낙찰과 동일 방식).

① 견적 질의 — s2r/{robot_id}/quote/offer

견적 단계에는 아직 goal 이 없으므로 goal 전체 정의가 아니라 축약 본문을 씁니다. 로봇은 목적지 좌표와 필요한 적재 칸 수만으로 "지금 이 배송을 맡을 수 있는지"를 판정합니다.

{
  "requestId": "uuid",
  "occurredAt": "2026-07-05T10:00:00+09:00",
  "payload": {
    "quoteId": "01a03250-e223-7f8e-8d2c-9eb06b4fdfa4",
    "deliveryType": "delivery",                 // delivery | trash_pickup
    "goals": [
      { "type": "store",    "location": { "x": 12.3, "y": 45.6, "th": 0.0, "map_id": "ground" } },
      { "type": "customer", "location": { "x": 78.9, "y": 10.1, "th": 0.0, "map_id": "ground" }, "boxCount": 2 }
    ]
  }
}

배차 입찰과 달리 goal id·PIN·주문번호가 없습니다 — 아직 주문이 확정되지 않은 단계이기 때문입니다.

② 견적 응답 — r2s/{robot_id}/quote/bid

배차 입찰 응답(goals/bid, §5.3 ②)과 동일한 스키마입니다. 불가 시 available=false·estArrival=null·reason(사유)로 응답합니다. 관제는 모든 goal 이 available일 때만 가용으로 보고 마지막 goal 도착 예상 시각 기준 남은 시간으로 예상 도착시간을 산출합니다.

{
  "requestId": "uuid",
  "occurredAt": "2026-07-05T10:00:03+09:00",
  "payload": {
    "goals": [
      { "id": "", "arrivalOrder": 1, "available": true, "estArrival": "2026-07-05T10:07:00+09:00", "reason": null },
      { "id": "", "arrivalOrder": 2, "available": true, "estArrival": "2026-07-05T10:14:00+09:00", "reason": null }
    ]
  }
}

적재함 만재는 관제가 판정합니다 — 로봇이 칸 점유를 알 수 없으므로, boxCount만큼 칸을 배정할 수 없는 로봇은 관제가 채택 단계에서 제외합니다. 로봇은 주행 가능 여부만 판단해 답하면 됩니다.

5.5 인프라 자원 요청 — 엘베·로비폰 운영 적용됨

로봇이 미션 수행 중 엘리베이터·로비폰(공동현관)이 필요한 시점에 관제로 요청합니다. 주소 정보는 관제가 orderId 로 보유합니다. 단, 엘리베이터는 로봇이 도착한 엘베 코드(elevatorCode)와 탑승층·목적층(sourceFloor·destinationFloor)을 함께 전달합니다 — 관제가 elevatorCode로 해당 엘베 라인(홀)의 호출 식별자를 조회해 MIRI 콜에 사용합니다. 실제 탑승 호기는 로봇이 고르지 않고 엘베 그룹제어가 배정하며, 관제는 배정된 호기(elId)를 resource/status 로 로봇에 전달해 로봇이 그 호기 문 앞으로 이동하도록 안내합니다. 로비폰은 로봇이 개방 대상 lobbyId(예: GOCHEOK-101)를 함께 전달하면, 관제가 lobbyId로 DB(lobbyphone 레지스트리)를 조회해 해당 로비의 siteId·IP·개방시간을 얻어 자동 개방(inBase 호출)합니다 — 로봇은 inBase·IP·토큰을 몰라도 됩니다. 처리 완료 시 관제가 진행 신호를 보내고, 로봇은 다음 단계로 이동합니다.

// 로봇 → 관제 : r2s/{robot_id}/resource  (엘베)
{ "orderId": "ZWS-ORD-...", "resource": "elevator",
  "elevatorCode": "EL-S002506-103", "sourceFloor": "3", "destinationFloor": "15",
  "building": "101" }                       // 선택 — 동 표기(있으면 감사 기록에 사용)

// 로봇 → 관제 : r2s/{robot_id}/resource  (로비폰)
{ "orderId": "ZWS-TRA-...", "resource": "lobbyphone", "lobbyId": "GOCHEOK-101" }

// 관제 → 로봇 : s2r/{robot_id}/resource/ready
//   result(로비폰): opened | failed   /  result(엘베): ok | canceled(취소 성공, 종결 신호) | failed(취소 거부)
{ "orderId": "ORD-...", "resource": "lobbyphone", "result": "opened" }
{ "orderId": "ORD-...", "resource": "elevator",   "result": "ok" }

요청 순서는 로비폰(건물 진입) → 엘베(상층 이동)입니다. 엘베는 로봇이 전달한 elevatorCode 로 관제가 호출 식별자를 조회하고, 로봇이 준 sourceFloor·destinationFloor 로 호출·탑승·하차를 조율하며, 하차 완료 후 진행 신호를 보냅니다. 로비폰은 자동 개방(입주민 호출 없음)이며, 로봇이 보낸 lobbyId 는 관제 DB(lobbyphone.lobby_id, status=active)의 값과 글자까지 정확히 일치해야 합니다 — 불일치·미등록이면 관제가 failed 를 회신합니다(신규 동/단지는 관제 DB에 로비 레코드를 먼저 등록하고 lobbyId 를 공유). 관제가 실제 개방 상태(opened/failed)를 result 로 회신하며, 로봇은 opened 일 때만 진입하고 그 외엔 대기·재시도합니다. 문 열림 시간은 관제 설정값(레코드별 durationSec)이며 로봇이 지정하지 않습니다.

엘베 중간 상태(탑승·하차)

엘베는 호출 후 탑승·하차 단계가 진행됩니다. 관제는 MIRI serviceStatus(호출확정→탑승→하차완료, 24종)를 받아 로봇에 중계(resource/status)하고, 로봇은 실제 탑승·하차 시점에 보고하면 관제가 이를 MIRI thing/status 로 중계합니다. 배정 호기는 콜 배정 확정(sourceFloorCallConfirmed) 시점부터 elId 로 함께 실려 오므로, 로봇은 그 호기 앞에서 탑승을 준비합니다.

// 관제 → 로봇 : s2r/{robot_id}/resource/status  (중간 상태 중계)
{ "resource": "elevator",
  "serviceStatus": "sourceFloorCallConfirmed" | "sourceFloorGetOn" | "sourceFloorGetOnCheck"
                 | "destinationFloorGetOff" | "destinationFloorGetOffCheck" | …,
  "elId": "EL-..." }

// 로봇 → 관제 : r2s/{robot_id}/resource  (탑승/하차 보고 → 관제가 MIRI thing/status 중계)
//   status 어휘는 MIRI serviceStatus 를 그대로 쓰는 것이 정본입니다(실 로봇 발행값).
{ "orderId": "ZWS-ORD-...", "resource": "elevator",
  "status": "sourceFloorWaiting" | "sourceFloorGettingOn" | "sourceFloorGotOn"
          | "destinationFloorGettingOff" | "destinationFloorGotOff" }
//   status 취소값(탑승 진행 어휘와 별개, §5.5): "cancelByRobot" — 탑승 실패로 로봇이 콜을 포기할 때

탑승 완료 = sourceFloorGotOn, 하차 완료 = destinationFloorGotOff 입니다. 이 두 전이는 MIRI 가 push 하지 않아 로봇 보고가 유일한 소식통입니다 — 누락되면 콜이 취소될 뿐 아니라 완료 이력도 남지 않습니다.

관제는 콜 배정 확정(sourceFloorCallConfirmed) 시점에 배정 호기(elId)를 실어 보내며, 로봇은 그 호기 앞에서 대기합니다. 이어 로봇은 sourceFloorGetOn(탑승 안내) 시 탑승 후 status:"sourceFloorGotOn", destinationFloorGetOff(하차 안내) 시 하차 후 status:"destinationFloorGotOff" 를 보고합니다. serviceStatus 어휘와 배정 호기 식별자(elId)는 MIRI 표준값을 그대로 사용하며, 호기 식별자→실제 문 위치 매핑은 제로웍스와 협의해 확정합니다.

엘베 콜 취소 — 로봇이 탑승하지 못해 콜을 포기할 때 같은 resource 토픽에 status: "cancelByRobot" 을 실어 보냅니다. 관제가 MIRI 사물 콜 취소를 대신 수행하고 resource/ready 로 result: "canceled"(성공) 또는 "failed"(MIRI 거부)를 돌려줍니다. canceled 는 진행 신호가 아니라 종결 신호입니다 — ok 와 혼동하지 마십시오. 취소 후 같은 엘베를 다시 부르려면 5초 이상 띄워야 합니다(현장 안정화 단계).

// 로봇 → 관제 : r2s/{robot_id}/resource
{ "orderId": "...", "resource": "elevator", "status": "cancelByRobot" }

// 관제 → 로봇 : s2r/{robot_id}/resource/ready
{ "orderId": "...", "resource": "elevator", "result": "canceled" }

6. PIN·박스 개방

고객 수령(하차) 방식은 로봇 H/W의 비대면 지원 여부(robot.auto_drop_off)로 결정되며, 배차/입찰 시점에 goal.mission으로 전달됩니다. 비스캣은 대면 배송에서 항상 userPin(4자리)을 발행하고 오토메타 배차 응답에 동봉합니다.

• 대면 — 로봇 PIN 입력(로컬 검증 + 감사 보고): 서버 왕복 지연·실패를 줄이기 위해 userPin을 mission.PIN으로 선전달하고 로봇이 로컬 검증합니다. 검증 후 사용·결과(성공/실패·박스 개폐 인가)를 r2s 감사 이벤트로 보고합니다(보고 토픽·페이로드 형식 확정 대상).
• 대면 — 오토메타 웹 개방(문열림 지시): 오토메타 앱/웹에서 고객이 개방 버튼을 누르면 오토메타→관제→로봇 문열림 지시(s2r) 신호로 해당 도어를 개방합니다(PIN 입력 불필요. 토픽·페이로드 확정 대상).
• userPin 발행 주체: 비스캣 관제가 대면(attended) 배송마다 랜덤 4자리를 생성·오토메타 배차 응답(userPin 필드)에 동봉합니다.
• autoDropOff 결정 주체: 배차 시 관제가 담당 로봇의 robot.auto_drop_off를 보고 결정합니다.
• 문 닫기(수령 완료): 로봇에서 확인 처리합니다.

오토메타 웹 개방용 문열림 지시(s2r)의 토픽·페이로드는 아래 6.1에 있습니다. 상차·하차 완료 보고는 별도 토픽 없이 r2s/{robot_id}/goals의 pickup:done·dropoff:done으로 일원화되었습니다(§6.1). 로봇 키패드 PIN 입력 경로의 PIN 감사 이벤트(r2s) 토픽·페이로드는 여전히 별도 확정 대상입니다. 토픽·페이로드 협의

6.1 박스 개방 지시 — s2r/{robot_id}/box/open

개방 지시는 관제가 박스 번호(boxSlots)를 지정해 내려보냅니다. 로봇은 주문번호를 해석하지 않습니다 — 관제가 주문번호↔박스 번호 매핑을 관장하고, 로봇은 지정된 물리 칸만 엽니다. 이 메시지는 행위를 트리거하는 명령이므로 §1 규약대로 requestId(멱등)를 유지하고 QoS 1로 전송합니다. 개방 지시는 로봇이 해당 지점에 도착한 뒤(점포=상차, 세대=하차)에만 유효합니다.

① 개방 지시 본문

관제가 열 박스 번호(boxSlots)를 지정해 지시합니다. 관제가 주문번호에 매핑한 번호를 내려주며, 로봇은 지정된 물리 박스 칸만 개방하고 주문번호는 해석하지 않습니다. 상차(점포)·하차(세대) 공용입니다.

{
  "requestId": "uuid",
  "occurredAt": "2026-07-19T14:00:00+09:00",
  "payload": {
    "boxSlots": [1, 3],                  // 관제가 지정한 개방 박스 번호
    "orderId": "ZWS-ORD-..."             // 선택 — 상관용. 로봇은 해석하지 않습니다
  }
}

② 개방·닫힘 결과 보고

별도 토픽 없이 r2s/{robot_id}/goals(§5.2)로 보고합니다.

• 열림 — 해당 goal 의 pickup/dropoff mission 이 status: "doing". 관제는 이 보고를 개방 완료(오토메타 unlock 응답)로 처리합니다.
• 닫힘 — 같은 mission 이 status: "done". 매장이면 배송 출발, 세대면 수령 완료·미션 종료로 처리합니다.

개방에 실패한 경우(기구 오류 등)는 goal·mission 을 canceled + reason: "door-not-opened"로 보고합니다(로봇 발행 항목 §6).

7. 맵 등록 (REST)

로봇이 보유한 지도와 의미 거점 노드(관제가 goal을 내릴 때 참조하는 명명된 지점)를 siteId 기준으로 관제에 등록합니다. 로봇 UI의 업로드 버튼을 누르면 로봇이 보유 맵을 자동 업로드합니다. 흐름은 등록 개시 → 파일 업로드 → 등록 확정 3단계로, 등록 개시 시 siteId·제시 mapId와 업로드할 파일 목록을 선언하면 관제가 파일별 업로드 URL을 발급하고, 로봇은 지도 이미지·메타(yml)·노드(json) 파일을 각각 해당 URL로 전송합니다(압축하지 않음).

① 등록 개시 — POST /v1/robot/maps

인증: HMAC(로봇). siteId·제시 mapId와 함께 업로드할 파일 목록(files)을 선언하면, 관제가 mapVersion과 선언한 파일별 업로드 URL을 발급합니다. 지도 메타·노드는 본문에 싣지 않고 ②에서 각 파일로 업로드합니다.

{
  "siteId": "APT-1023",
  "mapId": "zw-map-001",        // 로봇(제로웍스)이 제시하는 맵 식별자
  "files": [                    // 업로드할 파일 목록 선언
    { "name": "map.pgm",    "type": "image" },
    { "name": "map.yml",    "type": "meta"  },
    { "name": "nodes.json", "type": "nodes" }
  ]
}

{
  "result": "SUCCESS",
  "data": {
    "mapId": "zw-map-001",
    "mapVersion": 3,
    "uploadExpiresIn": 600,
    "uploads": [                 // 선언한 파일별 업로드 URL
      { "name": "map.pgm",    "uploadUrl": "https://...(map.pgm 업로드 URL)..." },
      { "name": "map.yml",    "uploadUrl": "https://...(map.yml 업로드 URL)..." },
      { "name": "nodes.json", "uploadUrl": "https://...(nodes.json 업로드 URL)..." }
    ]
  }
}

② 파일 업로드 — {uploadUrl}

로봇이 ① 응답의 uploads[]에 따라 각 파일을 해당 업로드 URL에 그대로 PUT합니다(압축하지 않음). uploadExpiresIn 내에 완료해야 합니다.

{
  "header": { "version": 5, "hash": "…" },
  "nodes": [
    {
      "idx": 12,                                  // ★ 파일 내 노드 식별자 — 관제의 place_id 가 됩니다
      "x": 12.34, "y": 56.78, "th": 0.0,
      "floor": 15,                                // 노드가 속한 건물 층(숫자). 없는 포맷도 허용
      "edge_to": [11, 13],
      "Place": {                                  // 이 객체가 있는 노드만 목적지로 등록됩니다
        "name": "1503호",
        "type": "home",
        "sort_order": 12,
        "size": 1
      }
    }
  ]
}

선언 목록(files)에 없는 파일은 DB에 반영되지 않고 삭제됩니다. type 별로 파일은 1개씩이어야 하며, 확장자로 type 을 추론합니다(pgm·png → image, yml → meta, json → nodes). meta(yml)는 resolution·origin 키가 있어야 통과합니다.

③ 등록 확정 — POST /v1/robot/maps/{mapId}/commit

업로드 완료를 통보합니다. 관제가 ① 선언 목록의 모든 파일이 업로드됐는지 확인하고, 각 파일을 검증(파싱·필수 항목 확인)해 통과하면 활성화(이전 버전 비활성)합니다. 선언 파일이 하나라도 누락됐거나 검증에 실패하면 거절하며, 선언에 없는 파일은 반영하지 않고 삭제합니다.

{
  "result": "SUCCESS",
  "data": {
    "mapId": "zw-map-001",
    "mapVersion": 3,
    "isActive": true,
    "activatedAt": "2026-06-12T10:00:00+09:00"
  }
}

8. 지오펜스 (REST · MQTT)

관제 콘솔에서 정의한 다각형 영역을 로봇이 내려받아 보유하고, 경로 계획·주행 중 스스로 판정합니다. 버전 알림은 MQTT, 본문 조회는 REST입니다. 동작 흐름은 시나리오 §9, 로봇이 발행하는 항목은 로봇 발행 항목 §9를 따릅니다.

① 버전 알림 — s2r/{robot_id}/geofence/version

단지 지오펜스 버전이 바뀌면 그 단지의 모든 로봇 토픽에 발행합니다. retain이므로 재접속한 로봇은 마지막 버전을 자동으로 수신합니다.

{
  "occurredAt": "2026-09-22T10:00:00+09:00",
  "payload": {
    "siteId": "APT-GOCHEOK-001",
    "version": 42
  }
}

② 영역 조회 — GET /v1/robot/geofences

인증: HMAC(로봇) — 맵 등록(§7)과 동일 방식입니다. 로봇이 소속된 단지의 활성 영역 전체를 반환합니다.

{
  "result": "SUCCESS",
  "data": {
    "siteId": "APT-GOCHEOK-001",
    "version": 42,
    "geofences": [
      {
        "id": "GF-01a0c3ef",
        "kind": "no-go",           // no-go · avoid · hazard
        "env": "indoor",           // indoor · outdoor
        "mapId": "ground",         // indoor 에만 포함 — location.map_id 와 동일 값
        "vertices": [              // 나열 순서가 변의 순서. 3개 이상
          { "x": 46.3, "y": 193.9 },
          { "x": 52.3, "y": 193.9 },
          { "x": 52.3, "y": 199.9 },
          { "x": 46.3, "y": 199.9 }
        ],
        "effectiveFrom": null,     // null = 제한 없음
        "effectiveTo": null        // null = 무기한
      },
      {
        "id": "GF-01a0c318",
        "kind": "hazard",
        "env": "outdoor",
        "vertices": [              // outdoor 는 WGS84 위경도
          { "lat": 37.4983392, "lng": 126.8599869 },
          { "lat": 37.4978070, "lng": 126.8595129 },
          { "lat": 37.4971505, "lng": 126.8605206 }
        ],
        "effectiveFrom": "2026-09-22T09:00:00+09:00",
        "effectiveTo": "2026-09-30T18:00:00+09:00"
      }
    ]
  }
}

• 전량 교체입니다. 응답에 없는 영역은 삭제된 것으로 간주하고 보유 목록에서 제거합니다 — 증분이 아닙니다.
• 비활성 영역은 응답에 포함되지 않습니다.
• 응답의 version이 ①에서 수신한 값과 다르면 그 사이 다시 바뀐 것입니다. 응답 값을 적용 버전으로 삼고 다음 알림을 기다립니다.
• effectiveFrom·effectiveTo는 로봇이 자체 시계로 매 판정 시점에 대조합니다. 기간의 시작·종료로는 버전이 바뀌지 않습니다.

③ 적용 회신 · 우회·차단 발행

적용 버전 회신(state.geofence)과 우회·차단 이벤트(r2s/{robot_id}/geofence)의 필드 규격은 로봇 발행 항목 §9에 있습니다.

9. 추후 범위 (setting · remote) 추후 추가 예정

아래 항목은 1.5차 PoC 범위 밖이며 토픽 자리만 예약합니다. (지도 파일 등록은 §7 REST로 정의되며, 아래 map MQTT 토픽은 추후 실시간 조회·갱신용으로 별도 검토합니다.)

운영자 개입 명령(s2r/{robot_id}/action/set)은 이 예약에서 §3.1 로 옮겨 정의했습니다. 관제 화면의 정지·재가동·속도·이동 조작이 그 토픽을 씁니다.

10. 에러·거절 코드 (로봇 관련 발췌)

REST 인증 에러 (HTTP status)

REST 맵 등록 에러 (§7)

MQTT 지시 거절 사유 (ack의 reason) 비스캣 제안

로봇이 s2r 지시를 수행할 수 없을 때 §3.2 ack에 result: "rejected"와 함께 싣습니다.

거절은 실패가 아니라 답입니다 — 관제는 이 코드로 운영자에게 「왜 안 됐는지」를 그대로 보여주고, 사유별 재시도 여부를 가릅니다.

MQTT 입찰 미낙찰 사유 (goals/result의 reason)

입찰 단계의 미낙찰은 HTTP가 아니라 goals/result 메시지 goals[].reason 값으로 전달됩니다(claimed=false). 구체 사유 코드 집합은 bid 타임아웃 값과 함께 확정합니다. 사유 코드 협의

전체 에러 카탈로그·유니크 키(재시도 안전)·버전 정책은 비스캣 API 공통 규약을 따릅니다. 규약 상세는 비스캣 담당자를 통해 제공됩니다.