{
  "openapi": "3.1.0",
  "info": {
    "title": "RONIQ 제조사 수신 API · 공개 발췌",
    "version": "1.1.6",
    "contact": {
      "name": "RONIQ",
      "email": "ayden@bnbcompany.io"
    },
    "description": "현재 승인된 수신 API 4종, 수신증 조회와 로봇 현재 상태 조회만 발췌한 공개 문서입니다. 실제 계정·고객 데이터·시험 서버가 없는 합성 예제를 사용합니다. 관리·자격 발급·예측 확장 API는 포함하지 않습니다."
  },
  "servers": [
    {
      "url": "https://api.roniq.invalid",
      "description": "실행 불가능한 문서용 placeholder. 등록된 로컬 시험 API 주소로 교체합니다."
    }
  ],
  "paths": {
    "/api/v1/robots/{id}/state": {
      "get": {
        "operationId": "getRobotState",
        "summary": "조회 — RobotState",
        "description": "현재 상태. OEM와 파생 점수·관측 없음·오래된 값을 구분. 권한과 현재 자원 범위를 서버가 검증한다. 변경 시 업무·이력·감사·outbox를 원자 확정하고 외부 전송은 commit 후 실행한다.",
        "tags": [
          "robots"
        ],
        "security": [
          {
            "UserBearer": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "해당 경로 자원의 불투명 식별자.",
            "schema": {
              "type": "string",
              "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
              "minLength": 1,
              "maxLength": 128,
              "example": "sample_id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "현재 상태. OEM와 파생 점수·관측 없음·오래된 값을 구분.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "로봇 최신 상태 결과를 data에 담은 공통 성공 응답. success, code, message와 요청 추적 정보 meta를 함께 반환한다.",
                  "$ref": "#/components/schemas/SiApiResponse",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RobotState"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "code": "SUCCESS",
                  "message": "처리되었습니다.",
                  "data": {
                    "robotId": "sample_id",
                    "connectivity": "ONLINE",
                    "operation": "IDLE",
                    "healthOem": null,
                    "batterySoc": null,
                    "observedAt": null,
                    "receivedAt": null,
                    "stale": true,
                    "synthetic": true,
                    "sourceId": "sample_id",
                    "mappingVersion": "mapping-1",
                    "freshnessSeconds": 0,
                    "extensions": {
                      "ext.sim.source": "SIMULATOR"
                    }
                  },
                  "meta": {
                    "requestId": "request_sample",
                    "timestamp": "2026-09-26T08:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/ingest/v1/events": {
      "post": {
        "operationId": "ingestEvents",
        "summary": "등록/처리 — Receipt",
        "description": "영속 수집 접수. 정규화 완료와 별개. 권한과 현재 자원 범위를 서버가 검증한다. 변경 시 업무·이력·감사·outbox를 원자 확정하고 외부 전송은 commit 후 실행한다.",
        "tags": [
          "ingestion"
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "영속 수집 접수. 정규화 완료와 별개.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "원문이 영속 접수되었음을 나타내는 공통 성공 응답. data의 수신증으로 후속 처리 상태를 조회하며, 202 자체는 정규화 완료를 뜻하지 않는다.",
                  "$ref": "#/components/schemas/SiApiResponse",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Receipt"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "code": "SUCCESS",
                  "message": "처리되었습니다.",
                  "data": {
                    "receiptId": "sample_id",
                    "acceptedCount": 1,
                    "status": "RECEIVED",
                    "receivedAt": "2026-09-26T08:00:00Z",
                    "synthetic": true,
                    "payloadRefs": [
                      "sample_id"
                    ],
                    "checksums": [
                      "0000000000000000000000000000000000000000000000000000000000000000"
                    ]
                  },
                  "meta": {
                    "requestId": "request_sample",
                    "timestamp": "2026-09-26T08:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        },
        "requestBody": {
          "required": true,
          "description": "최대500항목/1MiB. 원자 검증·내구성 저장 후 접수. 부분 성공 없음.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventBatch"
              },
              "example": {
                "connectorId": "sample_id",
                "sourceGeneration": 1,
                "synthetic": true,
                "items": [
                  {
                    "eventId": "sample_id",
                    "robotExternalId": "sample_id",
                    "observedAt": "2026-09-26T08:00:00Z",
                    "sequence": 1,
                    "vendorCode": "SIM_OFFLINE",
                    "category": "CONNECTIVITY",
                    "severity": "INFO",
                    "source": {
                      "sourceId": "sample_id",
                      "mappingVersion": "mapping-1",
                      "sourceQuality": "VALID",
                      "freshnessSeconds": 0
                    },
                    "rawPayload": {
                      "mediaType": "application/json",
                      "body": "eyJiYXR0ZXJ5Ijo3NX0=",
                      "sha256": "9aeb4c95009ce0a818a5fe6689aae08319fc3da935c76959fae860dd680e4f26"
                    },
                    "extensions": {
                      "ext.sim.source": "SIMULATOR"
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/ingest/v1/telemetry": {
      "post": {
        "operationId": "ingestTelemetry",
        "summary": "등록/처리 — Receipt",
        "description": "영속 수집 접수. 정규화 완료와 별개. 권한과 현재 자원 범위를 서버가 검증한다. 변경 시 업무·이력·감사·outbox를 원자 확정하고 외부 전송은 commit 후 실행한다.",
        "tags": [
          "ingestion"
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "영속 수집 접수. 정규화 완료와 별개.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "원문이 영속 접수되었음을 나타내는 공통 성공 응답. data의 수신증으로 후속 처리 상태를 조회하며, 202 자체는 정규화 완료를 뜻하지 않는다.",
                  "$ref": "#/components/schemas/SiApiResponse",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Receipt"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "code": "SUCCESS",
                  "message": "처리되었습니다.",
                  "data": {
                    "receiptId": "sample_id",
                    "acceptedCount": 1,
                    "status": "RECEIVED",
                    "receivedAt": "2026-09-26T08:00:00Z",
                    "synthetic": true,
                    "payloadRefs": [
                      "sample_id"
                    ],
                    "checksums": [
                      "0000000000000000000000000000000000000000000000000000000000000000"
                    ]
                  },
                  "meta": {
                    "requestId": "request_sample",
                    "timestamp": "2026-09-26T08:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        },
        "requestBody": {
          "required": true,
          "description": "최대500항목/1MiB. 원자 검증·내구성 저장 후 접수. 부분 성공 없음.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TelemetryBatch"
              },
              "example": {
                "connectorId": "sample_id",
                "sourceGeneration": 1,
                "synthetic": true,
                "items": [
                  {
                    "eventId": "sample_id",
                    "robotExternalId": "sample_id",
                    "observedAt": "2026-09-26T08:00:00Z",
                    "sequence": 1,
                    "metric": "battery.soc",
                    "numericValue": 75,
                    "stringValue": null,
                    "unit": "%",
                    "source": {
                      "sourceId": "sample_id",
                      "mappingVersion": "mapping-1",
                      "sourceQuality": "VALID",
                      "freshnessSeconds": 0
                    },
                    "rawPayload": {
                      "mediaType": "application/json",
                      "body": "eyJiYXR0ZXJ5Ijo3NX0=",
                      "sha256": "9aeb4c95009ce0a818a5fe6689aae08319fc3da935c76959fae860dd680e4f26"
                    },
                    "extensions": {
                      "ext.sim.source": "SIMULATOR"
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/ingest/v1/states": {
      "post": {
        "operationId": "ingestStates",
        "summary": "등록/처리 — Receipt",
        "description": "영속 수집 접수. 정규화 완료와 별개. 권한과 현재 자원 범위를 서버가 검증한다. 변경 시 업무·이력·감사·outbox를 원자 확정하고 외부 전송은 commit 후 실행한다.",
        "tags": [
          "ingestion"
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "영속 수집 접수. 정규화 완료와 별개.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "원문이 영속 접수되었음을 나타내는 공통 성공 응답. data의 수신증으로 후속 처리 상태를 조회하며, 202 자체는 정규화 완료를 뜻하지 않는다.",
                  "$ref": "#/components/schemas/SiApiResponse",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Receipt"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "code": "SUCCESS",
                  "message": "처리되었습니다.",
                  "data": {
                    "receiptId": "sample_id",
                    "acceptedCount": 1,
                    "status": "RECEIVED",
                    "receivedAt": "2026-09-26T08:00:00Z",
                    "synthetic": true,
                    "payloadRefs": [
                      "sample_id"
                    ],
                    "checksums": [
                      "0000000000000000000000000000000000000000000000000000000000000000"
                    ]
                  },
                  "meta": {
                    "requestId": "request_sample",
                    "timestamp": "2026-09-26T08:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        },
        "requestBody": {
          "required": true,
          "description": "최대500항목/1MiB. 원자 검증·내구성 저장 후 접수. 부분 성공 없음.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StateBatch"
              },
              "example": {
                "connectorId": "sample_id",
                "sourceGeneration": 1,
                "synthetic": true,
                "items": [
                  {
                    "eventId": "sample_id",
                    "robotExternalId": "sample_id",
                    "observedAt": "2026-09-26T08:00:00Z",
                    "sequence": 1,
                    "connectivity": "ONLINE",
                    "operation": "IDLE",
                    "batterySoc": null,
                    "source": {
                      "sourceId": "sample_id",
                      "mappingVersion": "mapping-1",
                      "sourceQuality": "VALID",
                      "freshnessSeconds": 0
                    },
                    "rawPayload": {
                      "mediaType": "application/json",
                      "body": "eyJiYXR0ZXJ5Ijo3NX0=",
                      "sha256": "9aeb4c95009ce0a818a5fe6689aae08319fc3da935c76959fae860dd680e4f26"
                    },
                    "extensions": {
                      "ext.sim.source": "SIMULATOR"
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/ingest/v1/receipts/{id}": {
      "get": {
        "operationId": "getIngestReceipt",
        "summary": "조회 — Receipt",
        "description": "영속 수집 접수. 정규화 완료와 별개. 권한과 현재 자원 범위를 서버가 검증한다. 변경 시 업무·이력·감사·outbox를 원자 확정하고 외부 전송은 commit 후 실행한다.",
        "tags": [
          "ingestion"
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "해당 경로 자원의 불투명 식별자.",
            "schema": {
              "type": "string",
              "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
              "minLength": 1,
              "maxLength": 128,
              "example": "sample_id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "영속 수집 접수. 정규화 완료와 별개.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "수집 수신증 결과를 data에 담은 공통 성공 응답. success, code, message와 요청 추적 정보 meta를 함께 반환한다.",
                  "$ref": "#/components/schemas/SiApiResponse",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Receipt"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "code": "SUCCESS",
                  "message": "처리되었습니다.",
                  "data": {
                    "receiptId": "sample_id",
                    "acceptedCount": 1,
                    "status": "RECEIVED",
                    "receivedAt": "2026-09-26T08:00:00Z",
                    "synthetic": true,
                    "payloadRefs": [
                      "sample_id"
                    ],
                    "checksums": [
                      "0000000000000000000000000000000000000000000000000000000000000000"
                    ]
                  },
                  "meta": {
                    "requestId": "request_sample",
                    "timestamp": "2026-09-26T08:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/ingest/v1/missions": {
      "post": {
        "operationId": "ingestMissions",
        "summary": "ingestMissions — 영속 수집 접수. 정규화 완료와 별개.",
        "description": "영속 수집 접수. 정규화 완료와 별개.",
        "tags": [
          "robots"
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "영속 수집 접수. 정규화 완료와 별개.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "원문이 영속 접수되었음을 나타내는 공통 성공 응답. data의 수신증으로 후속 처리 상태를 조회하며, 202 자체는 정규화 완료를 뜻하지 않는다.",
                  "$ref": "#/components/schemas/SiApiResponse",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Receipt"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "code": "SUCCESS",
                  "message": "처리되었습니다.",
                  "data": {
                    "receiptId": "sample_id",
                    "acceptedCount": 1,
                    "status": "RECEIVED",
                    "receivedAt": "2026-09-26T08:00:00Z",
                    "synthetic": true,
                    "payloadRefs": [
                      "sample_id"
                    ],
                    "checksums": [
                      "0000000000000000000000000000000000000000000000000000000000000000"
                    ]
                  },
                  "meta": {
                    "requestId": "request_sample",
                    "timestamp": "2026-09-26T08:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        },
        "requestBody": {
          "required": true,
          "description": "미션관측 최대500항목/1MiB 원자수집. 내부planner 없음.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MissionBatch"
              },
              "example": {
                "connectorId": "sample_id",
                "sourceGeneration": 1,
                "synthetic": true,
                "items": [
                  {
                    "eventId": "sample_id",
                    "robotExternalId": "sample_id",
                    "externalId": "sample_id",
                    "observedAt": "2026-09-26T08:00:00Z",
                    "sequence": 1,
                    "type": "DELIVERY",
                    "status": "QUEUED",
                    "startedAt": null,
                    "endedAt": null,
                    "durationSeconds": null,
                    "distanceMeters": null,
                    "source": {
                      "sourceId": "sample_id",
                      "mappingVersion": "mapping-1",
                      "sourceQuality": "VALID",
                      "freshnessSeconds": 0
                    },
                    "rawPayload": {
                      "mediaType": "application/json",
                      "body": "eyJiYXR0ZXJ5Ijo3NX0=",
                      "sha256": "9aeb4c95009ce0a818a5fe6689aae08319fc3da935c76959fae860dd680e4f26"
                    },
                    "extensions": {
                      "ext.sim.source": "SIMULATOR"
                    }
                  }
                ]
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SiApiResponse": {
        "type": "object",
        "description": "공통 Envelope. 각 operation의 properties.data가 구체 DTO를 제약한다.",
        "properties": {
          "success": {
            "description": "요청이 성공적으로 처리되었음을 나타내는 고정값 true. 비동기 접수 응답에서는 후속 작업 완료와 구분한다.",
            "type": "boolean",
            "const": true
          },
          "code": {
            "description": "정상 처리 결과를 나타내는 고정 코드 SUCCESS. 비동기 접수의 실제 처리 상태는 해당 data에서 확인한다.",
            "type": "string",
            "const": "SUCCESS"
          },
          "message": {
            "type": "string",
            "description": "한국어 결과.",
            "minLength": 1,
            "maxLength": 200,
            "example": "처리되었습니다."
          },
          "data": {
            "description": "각 operation의 구체 DTO."
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "success",
          "code",
          "message",
          "data",
          "meta"
        ],
        "additionalProperties": false
      },
      "Meta": {
        "type": "object",
        "description": "추적 메타데이터.",
        "properties": {
          "requestId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z$",
            "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
            "example": "2026-09-26T08:00:00Z"
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        },
        "required": [
          "requestId",
          "timestamp"
        ],
        "additionalProperties": false
      },
      "Pagination": {
        "type": "object",
        "description": "페이지 메타데이터.",
        "properties": {
          "page": {
            "type": "integer",
            "description": "1부터 시작.",
            "example": 1,
            "minimum": 1
          },
          "size": {
            "type": "integer",
            "description": "페이지 크기.",
            "example": 20,
            "minimum": 1
          },
          "totalElements": {
            "type": "integer",
            "description": "필터·권한 일치 건수.",
            "example": 1,
            "minimum": 0
          },
          "totalPages": {
            "type": "integer",
            "description": "전체 페이지 수.",
            "example": 1,
            "minimum": 0
          },
          "hasNext": {
            "type": "boolean",
            "description": "다음 페이지 존재.",
            "example": false
          }
        },
        "required": [
          "page",
          "size",
          "totalElements",
          "totalPages",
          "hasNext"
        ],
        "additionalProperties": false
      },
      "RobotState": {
        "type": "object",
        "description": "현재 상태. OEM와 파생 점수·관측 없음·오래된 값을 구분.",
        "properties": {
          "robotId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "connectivity": {
            "type": "string",
            "description": "연결 상태.",
            "minLength": 1,
            "maxLength": 200,
            "example": "ONLINE",
            "enum": [
              "ONLINE",
              "OFFLINE",
              "UNKNOWN"
            ]
          },
          "operation": {
            "type": "string",
            "description": "운용 상태.",
            "minLength": 1,
            "maxLength": 200,
            "example": "IDLE",
            "enum": [
              "IDLE",
              "RUNNING",
              "CHARGING",
              "ERROR",
              "UNKNOWN"
            ]
          },
          "healthOem": {
            "anyOf": [
              {
                "type": "string",
                "description": "OEM 상태.",
                "minLength": 1,
                "maxLength": 200,
                "example": "NORMAL"
              },
              {
                "type": "null"
              }
            ],
            "description": "OEM 상태."
          },
          "batterySoc": {
            "anyOf": [
              {
                "type": "number",
                "description": "SOC(%).",
                "example": 75,
                "minimum": 0,
                "maximum": 100
              },
              {
                "type": "null"
              }
            ],
            "description": "현재 상태 관측의 배터리 잔량 SOC(%). 관측값이 없으면 null이며 실제 잔량 0%와 구분한다."
          },
          "observedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "Z$",
                "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
                "example": "2026-09-26T08:00:00Z"
              },
              {
                "type": "null"
              }
            ],
            "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용."
          },
          "receivedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "Z$",
                "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
                "example": "2026-09-26T08:00:00Z"
              },
              {
                "type": "null"
              }
            ],
            "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용."
          },
          "stale": {
            "type": "boolean",
            "description": "최신성 초과.",
            "example": true
          },
          "synthetic": {
            "type": "boolean",
            "description": "합성 입력.",
            "example": true
          },
          "sourceId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "mappingVersion": {
            "type": "string",
            "description": "정규화 매핑 버전.",
            "minLength": 1,
            "maxLength": 200,
            "example": "mapping-1"
          },
          "freshnessSeconds": {
            "type": "integer",
            "description": "관측 최신성초.",
            "minimum": 0,
            "example": 0
          },
          "extensions": {
            "type": "object",
            "description": "Vendor 확장 scalar map. 복잡한 원문은 rawPayload에 보존. ext.vendor.field 명명,최대100개.",
            "maxProperties": 100,
            "propertyNames": {
              "pattern": "^ext\\.[a-z0-9_]+\\.[A-Za-z0-9_.-]+$"
            },
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            },
            "example": {
              "ext.sim.source": "SIMULATOR"
            }
          }
        },
        "required": [
          "robotId",
          "connectivity",
          "operation",
          "healthOem",
          "batterySoc",
          "observedAt",
          "receivedAt",
          "stale",
          "synthetic",
          "sourceId",
          "mappingVersion",
          "freshnessSeconds",
          "extensions"
        ],
        "additionalProperties": false
      },
      "SiApiErrorResponse": {
        "type": "object",
        "description": "안전한 공통 오류. 토큰·원문 개인정보·stack trace 비노출.",
        "properties": {
          "success": {
            "description": "요청 처리가 실패했음을 나타내는 고정값 false. 구체적인 실패 원인은 code와 message로 확인한다.",
            "type": "boolean",
            "const": false
          },
          "code": {
            "type": "string",
            "description": "오류 코드.",
            "minLength": 1,
            "maxLength": 200,
            "example": "INVALID_REQUEST",
            "enum": [
              "INVALID_REQUEST",
              "UNAUTHENTICATED",
              "FORBIDDEN",
              "NOT_FOUND",
              "CONFLICT",
              "BUSINESS_RULE_VIOLATION",
              "RATE_LIMITED",
              "INTERNAL_ERROR"
            ]
          },
          "message": {
            "type": "string",
            "description": "오류 안내.",
            "minLength": 1,
            "maxLength": 200,
            "example": "처리할 수 없습니다."
          },
          "data": {
            "description": "오류 응답의 업무 데이터. 항상 null이며 성공 결과나 내부 오류 원문을 담지 않는다.",
            "type": "null"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "errors": {
            "type": "array",
            "description": "필드별 오류.",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "maxItems": 30
          }
        },
        "required": [
          "success",
          "code",
          "message",
          "data",
          "meta"
        ],
        "additionalProperties": false
      },
      "FieldError": {
        "type": "object",
        "description": "입력 필드 오류.",
        "properties": {
          "field": {
            "type": "string",
            "description": "camelCase 필드 경로.",
            "minLength": 1,
            "maxLength": 200,
            "example": "name"
          },
          "code": {
            "type": "string",
            "description": "오류 코드.",
            "minLength": 1,
            "maxLength": 200,
            "example": "REQUIRED"
          },
          "message": {
            "type": "string",
            "description": "안전한 한국어 안내.",
            "minLength": 1,
            "maxLength": 200,
            "example": "필수 항목입니다."
          }
        },
        "required": [
          "field",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "Receipt": {
        "type": "object",
        "description": "영속 수집 접수. 정규화 완료와 별개.",
        "properties": {
          "receiptId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "acceptedCount": {
            "type": "integer",
            "description": "접수 개수.",
            "example": 1,
            "minimum": 1
          },
          "status": {
            "type": "string",
            "description": "처리 상태.",
            "minLength": 1,
            "maxLength": 200,
            "example": "RECEIVED",
            "enum": [
              "RECEIVED",
              "PROCESSING",
              "COMPLETED",
              "FAILED"
            ]
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z$",
            "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
            "example": "2026-09-26T08:00:00Z"
          },
          "synthetic": {
            "type": "boolean",
            "description": "합성 여부.",
            "example": true
          },
          "payloadRefs": {
            "type": "array",
            "description": "서버발급 불투명 raw 참조. URL/비밀 노출아님.",
            "maxItems": 500,
            "items": {
              "type": "string",
              "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
              "minLength": 1,
              "maxLength": 128,
              "example": "sample_id"
            }
          },
          "checksums": {
            "type": "array",
            "description": "확정 저장 raw checksum.",
            "maxItems": 500,
            "items": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            },
            "example": [
              "0000000000000000000000000000000000000000000000000000000000000000"
            ]
          }
        },
        "required": [
          "receiptId",
          "acceptedCount",
          "status",
          "receivedAt",
          "synthetic",
          "payloadRefs",
          "checksums"
        ],
        "additionalProperties": false
      },
      "EventBatch": {
        "type": "object",
        "description": "최대500항목/1MiB. 원자 검증·내구성 저장 후 접수. 부분 성공 없음.",
        "properties": {
          "connectorId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "sourceGeneration": {
            "type": "integer",
            "description": "등록된 출처 세대. 철회 세대 거절.",
            "example": 1,
            "minimum": 1
          },
          "synthetic": {
            "type": "boolean",
            "description": "등록 연결과 일치하는 합성 여부.",
            "example": true
          },
          "items": {
            "type": "array",
            "description": "항목.",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/IngestEvent"
            }
          }
        },
        "required": [
          "connectorId",
          "sourceGeneration",
          "synthetic",
          "items"
        ],
        "additionalProperties": false
      },
      "IngestEvent": {
        "type": "object",
        "description": "observedAt 90일 이상 과거/미래5분 초과 거절. 삭제·철회된 source generation 차단.",
        "properties": {
          "eventId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "robotExternalId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z$",
            "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
            "example": "2026-09-26T08:00:00Z"
          },
          "sequence": {
            "type": "integer",
            "description": "원본 sequence.",
            "example": 1,
            "minimum": 0
          },
          "vendorCode": {
            "type": "string",
            "description": "Vendor 코드.",
            "minLength": 1,
            "maxLength": 200,
            "example": "SIM_OFFLINE"
          },
          "category": {
            "type": "string",
            "description": "범주.",
            "minLength": 1,
            "maxLength": 200,
            "example": "CONNECTIVITY"
          },
          "severity": {
            "type": "string",
            "description": "심각도.",
            "minLength": 1,
            "maxLength": 200,
            "example": "INFO",
            "enum": [
              "INFO",
              "WARNING",
              "CRITICAL"
            ]
          },
          "source": {
            "$ref": "#/components/schemas/SourceMetadata"
          },
          "rawPayload": {
            "$ref": "#/components/schemas/RawPayload"
          },
          "extensions": {
            "type": "object",
            "description": "Vendor 확장 scalar map. 복잡한 원문은 rawPayload에 보존. ext.vendor.field 명명,최대100개.",
            "maxProperties": 100,
            "propertyNames": {
              "pattern": "^ext\\.[a-z0-9_]+\\.[A-Za-z0-9_.-]+$"
            },
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            },
            "example": {
              "ext.sim.source": "SIMULATOR"
            }
          }
        },
        "required": [
          "eventId",
          "robotExternalId",
          "observedAt",
          "sequence",
          "vendorCode",
          "category",
          "severity",
          "source",
          "rawPayload",
          "extensions"
        ],
        "additionalProperties": false
      },
      "SourceMetadata": {
        "type": "object",
        "description": "인증 Connector와 일치하는 출처. 임의 고객 확대 금지.",
        "additionalProperties": false,
        "properties": {
          "sourceId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "mappingVersion": {
            "type": "string",
            "description": "적용매핑 불변 버전.",
            "minLength": 1,
            "maxLength": 200,
            "example": "mapping-1"
          },
          "sourceQuality": {
            "type": "string",
            "description": "원본 품질.",
            "minLength": 1,
            "maxLength": 200,
            "example": "VALID",
            "enum": [
              "VALID",
              "INVALID",
              "UNKNOWN"
            ]
          },
          "freshnessSeconds": {
            "type": "integer",
            "description": "관측 후 전송까지 경과초. 서버수신시각으로 대사.",
            "minimum": 0,
            "example": 0
          }
        },
        "required": [
          "sourceId",
          "mappingVersion",
          "sourceQuality",
          "freshnessSeconds"
        ]
      },
      "RawPayload": {
        "type": "object",
        "description": "Agent가 받은 원본bytes의base64. batch전체1MiB 제한. checksum은전송중무결성확인이지 Vendor진위서명증명이아님. raw전용암호화저장,업무응답/로그비노출.",
        "additionalProperties": false,
        "properties": {
          "mediaType": {
            "type": "string",
            "description": "원본 형식.",
            "minLength": 1,
            "maxLength": 200,
            "example": "application/json",
            "enum": [
              "application/json",
              "text/plain",
              "application/octet-stream"
            ]
          },
          "body": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "원본bytes base64. decoded최대512KiB, batch전체1MiB서버검증.",
            "maxLength": 699052,
            "minLength": 1,
            "example": "eyJiYXR0ZXJ5Ijo3NX0="
          },
          "sha256": {
            "type": "string",
            "description": "원문 UTF-8 bytes SHA-256 소문자hex.",
            "pattern": "^[0-9a-f]{64}$",
            "example": "9aeb4c95009ce0a818a5fe6689aae08319fc3da935c76959fae860dd680e4f26"
          }
        },
        "required": [
          "mediaType",
          "body",
          "sha256"
        ]
      },
      "TelemetryBatch": {
        "type": "object",
        "description": "최대500항목/1MiB. 원자 검증·내구성 저장 후 접수. 부분 성공 없음.",
        "properties": {
          "connectorId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "sourceGeneration": {
            "type": "integer",
            "description": "등록된 출처 세대. 철회 세대 거절.",
            "example": 1,
            "minimum": 1
          },
          "synthetic": {
            "type": "boolean",
            "description": "등록 연결과 일치하는 합성 여부.",
            "example": true
          },
          "items": {
            "type": "array",
            "description": "항목.",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/IngestTelemetry"
            }
          }
        },
        "required": [
          "connectorId",
          "sourceGeneration",
          "synthetic",
          "items"
        ],
        "additionalProperties": false
      },
      "IngestTelemetry": {
        "type": "object",
        "description": "numericValue/stringValue 정확히 하나 non-null.",
        "properties": {
          "eventId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "robotExternalId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z$",
            "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
            "example": "2026-09-26T08:00:00Z"
          },
          "sequence": {
            "type": "integer",
            "description": "원본 sequence.",
            "example": 1,
            "minimum": 0
          },
          "metric": {
            "type": "string",
            "description": "계측명.",
            "minLength": 1,
            "maxLength": 200,
            "example": "battery.soc"
          },
          "numericValue": {
            "description": "숫자 형태의 계측값. 숫자 계측이면 이 값만 non-null로 보내고 stringValue는 null이어야 한다.",
            "anyOf": [
              {
                "type": "number",
                "description": "숫자값.",
                "example": 75
              },
              {
                "type": "null"
              }
            ]
          },
          "stringValue": {
            "description": "문자열 형태의 계측값. 문자열 계측이면 이 값만 non-null로 보내고 numericValue는 null이어야 한다.",
            "anyOf": [
              {
                "type": "string",
                "description": "문자값.",
                "minLength": 1,
                "maxLength": 200,
                "example": "IDLE"
              },
              {
                "type": "null"
              }
            ]
          },
          "unit": {
            "type": "string",
            "description": "단위.",
            "minLength": 1,
            "maxLength": 32,
            "example": "%"
          },
          "source": {
            "$ref": "#/components/schemas/SourceMetadata"
          },
          "rawPayload": {
            "$ref": "#/components/schemas/RawPayload"
          },
          "extensions": {
            "type": "object",
            "description": "Vendor 확장 scalar map. 복잡한 원문은 rawPayload에 보존. ext.vendor.field 명명,최대100개.",
            "maxProperties": 100,
            "propertyNames": {
              "pattern": "^ext\\.[a-z0-9_]+\\.[A-Za-z0-9_.-]+$"
            },
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            },
            "example": {
              "ext.sim.source": "SIMULATOR"
            }
          }
        },
        "required": [
          "eventId",
          "robotExternalId",
          "observedAt",
          "sequence",
          "metric",
          "numericValue",
          "stringValue",
          "unit",
          "source",
          "rawPayload",
          "extensions"
        ],
        "additionalProperties": false,
        "oneOf": [
          {
            "properties": {
              "numericValue": {
                "description": "숫자 계측 분기에서 사용하는 숫자 값.",
                "type": "number"
              },
              "stringValue": {
                "description": "숫자 계측 분기에서는 문자열 값을 사용하지 않으므로 null이다.",
                "type": "null"
              }
            }
          },
          {
            "properties": {
              "numericValue": {
                "description": "문자열 계측 분기에서는 숫자 값을 사용하지 않으므로 null이다.",
                "type": "null"
              },
              "stringValue": {
                "description": "문자열 계측 분기에서 사용하는 문자열 값.",
                "type": "string"
              }
            }
          }
        ]
      },
      "StateBatch": {
        "type": "object",
        "description": "최대500항목/1MiB. 원자 검증·내구성 저장 후 접수. 부분 성공 없음.",
        "properties": {
          "connectorId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "sourceGeneration": {
            "type": "integer",
            "description": "등록된 출처 세대. 철회 세대 거절.",
            "example": 1,
            "minimum": 1
          },
          "synthetic": {
            "type": "boolean",
            "description": "등록 연결과 일치하는 합성 여부.",
            "example": true
          },
          "items": {
            "type": "array",
            "description": "항목.",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/IngestState"
            }
          }
        },
        "required": [
          "connectorId",
          "sourceGeneration",
          "synthetic",
          "items"
        ],
        "additionalProperties": false
      },
      "IngestState": {
        "type": "object",
        "description": "동일 시각 sequence로 current state 갱신 판단.",
        "properties": {
          "eventId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "robotExternalId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z$",
            "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
            "example": "2026-09-26T08:00:00Z"
          },
          "sequence": {
            "type": "integer",
            "description": "원본 sequence.",
            "example": 1,
            "minimum": 0
          },
          "connectivity": {
            "type": "string",
            "description": "연결 상태.",
            "minLength": 1,
            "maxLength": 200,
            "example": "ONLINE",
            "enum": [
              "ONLINE",
              "OFFLINE",
              "UNKNOWN"
            ]
          },
          "operation": {
            "type": "string",
            "description": "운용 상태.",
            "minLength": 1,
            "maxLength": 200,
            "example": "IDLE",
            "enum": [
              "IDLE",
              "RUNNING",
              "CHARGING",
              "ERROR",
              "UNKNOWN"
            ]
          },
          "batterySoc": {
            "description": "원본 출처가 보고한 배터리 잔량 SOC(%). 0~100 범위의 값이며 관측값이 없으면 null이다.",
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "description": "SOC(%).",
                "example": 75
              },
              {
                "type": "null"
              }
            ]
          },
          "source": {
            "$ref": "#/components/schemas/SourceMetadata"
          },
          "rawPayload": {
            "$ref": "#/components/schemas/RawPayload"
          },
          "extensions": {
            "type": "object",
            "description": "Vendor 확장 scalar map. 복잡한 원문은 rawPayload에 보존. ext.vendor.field 명명,최대100개.",
            "maxProperties": 100,
            "propertyNames": {
              "pattern": "^ext\\.[a-z0-9_]+\\.[A-Za-z0-9_.-]+$"
            },
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            },
            "example": {
              "ext.sim.source": "SIMULATOR"
            }
          },
          "mission": {
            "description": "상태 관측과 함께 전달하는 외부 미션 자료. 선택 필드로, 미션 자료가 없으면 생략하거나 null을 사용할 수 있다.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/IngestMission"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "eventId",
          "robotExternalId",
          "observedAt",
          "sequence",
          "connectivity",
          "operation",
          "batterySoc",
          "source",
          "rawPayload",
          "extensions"
        ],
        "additionalProperties": false
      },
      "IngestMission": {
        "type": "object",
        "description": "외부 미션 조회자료 수집. planner/원격실행 아님.",
        "additionalProperties": false,
        "properties": {
          "eventId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "robotExternalId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "externalId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z$",
            "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
            "example": "2026-09-26T08:00:00Z"
          },
          "sequence": {
            "type": "integer",
            "description": "출처 순서.",
            "minimum": 0,
            "example": 1
          },
          "type": {
            "type": "string",
            "description": "미션 종류.",
            "minLength": 1,
            "maxLength": 200,
            "example": "DELIVERY"
          },
          "status": {
            "type": "string",
            "description": "상태.",
            "minLength": 1,
            "maxLength": 200,
            "example": "QUEUED",
            "enum": [
              "QUEUED",
              "RUNNING",
              "COMPLETED",
              "FAILED",
              "CANCELLED",
              "UNKNOWN"
            ]
          },
          "startedAt": {
            "description": "원본 출처의 미션 시작 시각(UTC RFC3339). 시작 시각이 제공되지 않으면 null이다.",
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "Z$",
                "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
                "example": "2026-09-26T08:00:00Z"
              },
              {
                "type": "null"
              }
            ]
          },
          "endedAt": {
            "description": "원본 출처의 미션 종료 시각(UTC RFC3339). 종료 시각이 제공되지 않으면 null이다.",
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "Z$",
                "description": "UTC RFC3339 시각. 사이트 시간대는 화면 표시에서 적용.",
                "example": "2026-09-26T08:00:00Z"
              },
              {
                "type": "null"
              }
            ]
          },
          "durationSeconds": {
            "description": "원본 출처가 제공한 미션 경과 시간(초). 값이 없으면 null을 보내며 0초와 구분한다.",
            "anyOf": [
              {
                "type": "integer",
                "description": "미션 경과초.",
                "minimum": 0,
                "example": 10
              },
              {
                "type": "null"
              }
            ]
          },
          "distanceMeters": {
            "description": "원본 출처가 제공한 미션 이동 거리(m). 값이 없으면 null을 보내며 0m와 구분한다.",
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "example": 12.5,
                "description": "거리m."
              },
              {
                "type": "null"
              }
            ]
          },
          "source": {
            "$ref": "#/components/schemas/SourceMetadata"
          },
          "rawPayload": {
            "$ref": "#/components/schemas/RawPayload"
          },
          "extensions": {
            "type": "object",
            "description": "Vendor 확장 scalar map. 복잡한 원문은 rawPayload에 보존. ext.vendor.field 명명,최대100개.",
            "maxProperties": 100,
            "propertyNames": {
              "pattern": "^ext\\.[a-z0-9_]+\\.[A-Za-z0-9_.-]+$"
            },
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            },
            "example": {
              "ext.sim.source": "SIMULATOR"
            }
          }
        },
        "required": [
          "eventId",
          "robotExternalId",
          "externalId",
          "observedAt",
          "sequence",
          "type",
          "status",
          "startedAt",
          "endedAt",
          "durationSeconds",
          "distanceMeters",
          "source",
          "rawPayload",
          "extensions"
        ]
      },
      "MissionBatch": {
        "type": "object",
        "description": "미션관측 최대500항목/1MiB 원자수집. 내부planner 없음.",
        "properties": {
          "connectorId": {
            "type": "string",
            "description": "서버 불투명 식별자. 인증 범위 밖 자원 존재 여부를 노출하지 않는다.",
            "minLength": 1,
            "maxLength": 128,
            "example": "sample_id"
          },
          "sourceGeneration": {
            "type": "integer",
            "description": "등록된 출처 세대. 철회 세대 거절.",
            "example": 1,
            "minimum": 1
          },
          "synthetic": {
            "type": "boolean",
            "description": "등록 연결과 일치하는 합성 여부.",
            "example": true
          },
          "items": {
            "type": "array",
            "description": "항목.",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/IngestMission"
            }
          }
        },
        "required": [
          "connectorId",
          "sourceGeneration",
          "synthetic",
          "items"
        ],
        "additionalProperties": false
      }
    },
    "responses": {
      "Error400": {
        "description": "형식 오류.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SiApiErrorResponse"
            },
            "example": {
              "success": false,
              "code": "INVALID_REQUEST",
              "message": "요청을 처리할 수 없습니다.",
              "data": null,
              "meta": {
                "requestId": "request_sample",
                "timestamp": "2026-09-26T08:00:00Z"
              }
            }
          }
        }
      },
      "Error401": {
        "description": "인증 만료/누락.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SiApiErrorResponse"
            },
            "example": {
              "success": false,
              "code": "UNAUTHENTICATED",
              "message": "요청을 처리할 수 없습니다.",
              "data": null,
              "meta": {
                "requestId": "request_sample",
                "timestamp": "2026-09-26T08:00:00Z"
              }
            }
          }
        }
      },
      "Error403": {
        "description": "권한 부족.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SiApiErrorResponse"
            },
            "example": {
              "success": false,
              "code": "FORBIDDEN",
              "message": "요청을 처리할 수 없습니다.",
              "data": null,
              "meta": {
                "requestId": "request_sample",
                "timestamp": "2026-09-26T08:00:00Z"
              }
            }
          }
        }
      },
      "Error404": {
        "description": "허용 범위에 자원 없음.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SiApiErrorResponse"
            },
            "example": {
              "success": false,
              "code": "NOT_FOUND",
              "message": "요청을 처리할 수 없습니다.",
              "data": null,
              "meta": {
                "requestId": "request_sample",
                "timestamp": "2026-09-26T08:00:00Z"
              }
            }
          }
        }
      },
      "Error422": {
        "description": "업무 규칙/상태/시간 범위 위반.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SiApiErrorResponse"
            },
            "example": {
              "success": false,
              "code": "BUSINESS_RULE_VIOLATION",
              "message": "요청을 처리할 수 없습니다.",
              "data": null,
              "meta": {
                "requestId": "request_sample",
                "timestamp": "2026-09-26T08:00:00Z"
              }
            }
          }
        }
      },
      "Error429": {
        "description": "요청률 초과. Retry-After 이후 재시도.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SiApiErrorResponse"
            },
            "example": {
              "success": false,
              "code": "RATE_LIMITED",
              "message": "요청을 처리할 수 없습니다.",
              "data": null,
              "meta": {
                "requestId": "request_sample",
                "timestamp": "2026-09-26T08:00:00Z"
              }
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "대기 초.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      },
      "Error500": {
        "description": "안전한 서버 오류. 추적 ID 사용.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SiApiErrorResponse"
            },
            "example": {
              "success": false,
              "code": "INTERNAL_ERROR",
              "message": "요청을 처리할 수 없습니다.",
              "data": null,
              "meta": {
                "requestId": "request_sample",
                "timestamp": "2026-09-26T08:00:00Z"
              }
            }
          }
        }
      },
      "Error409": {
        "description": "version·멱등키 충돌 또는 처리중. 재조회 후 변경 재확인.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SiApiErrorResponse"
            },
            "example": {
              "success": false,
              "code": "CONFLICT",
              "message": "요청을 처리할 수 없습니다.",
              "data": null,
              "meta": {
                "requestId": "request_sample",
                "timestamp": "2026-09-26T08:00:00Z"
              }
            }
          }
        }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "16~128자 키. tenant/principal+method+path+키, 24시간. 동일 완료 payload 원응답, 다른 payload/진행중 409.",
        "schema": {
          "type": "string",
          "minLength": 16,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "example": "sample-request-20260926-001"
      }
    },
    "securitySchemes": {
      "UserBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "현재 자원 범위에 할당된 사용자의 OIDC JWT. 수집 서비스 자격과 구분."
      },
      "ServiceBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "OAuth client_credentials 수집 서비스 JWT. 등록 Connector·고객·사이트·세대 범위 검사."
      }
    }
  }
}
