시스템 연동

한 제조사에 종속되지 않는 연결 계층.

제조사·FMS의 직접 전송 API 또는 HTTPS GET·MQTT v5 수집을 연결합니다. 데이터 형식과 연결 환경을 준비하고, 현장 담당자와 연동 담당자가 함께 수집·매핑을 확인합니다.

합성 데이터 · 연동 흐름 예시

AMR-031 / 수신 추적

시연 기준 시각 · 2026-10-04 01:44 UTC

  1. 01

    수집 경로와 출처 등록

    연동 담당자가 출처를 등록하고 Site Agent의 연결을 설정합니다.

  2. 02

    원본 필드 매핑

    AMR-031 · 배터리 잔량 48% · 관측 01:44:00 UTC

  3. 03

    접수와 처리 상태 확인

    접수 → 처리 중 → 처리 완료

    접수 01:44:02 UTC · 상태 조회 01:44:03 UTC · 1건
  4. 04

    정규화 상태

    AMR-031 · 연결됨 · 운행 중 · 배터리 잔량 48% · 유효 데이터

연동 흐름 · 합성 데이터 예시. 실제 제조사 연결 상태를 나타내지 않습니다.
연결 준비

무엇을 연결하고, 누가 준비하나요?

기존 로봇·장비와 FMS에서 상태·이벤트·미션·센서 데이터를 받습니다. 제조사 추가 인터페이스는 어댑터 확장과 연결 시험으로 적용합니다.

연결 방식 정하기

제조사 시스템의 직접 API 전송, 또는 Site Agent의 HTTPS GET·MQTT v5 수집 중 현장에 맞는 방식을 정합니다.

자료와 접근 권한 준비

제조사·FMS 문서, 비식별 샘플, 장비 식별 규칙, 시각·단위와 네트워크 조건을 준비합니다. 인증 정보는 승인된 등록 환경에서 별도로 설정합니다.

매핑과 상태 함께 확인

현장·제조사 담당자는 원본 의미와 연결을 확인하고, 연동 담당자는 필드 매핑과 시험을 진행합니다. 운영 담당자가 수집 상태를 확인한 뒤 적용 범위를 정합니다.

API·스키마·샘플의 개발 가이드 보기 →

현장 수집 경로

Site Agent는 고객 내부망에서 아웃바운드로 연결합니다.

장애와 버퍼 포화는 운영자에게 드러내고, 관측 공백을 정상 데이터처럼 채우지 않습니다.

1로봇·FMS2현장 네트워크3Site Agent4외부 연결 · TLS5RONIQ
지원 기술

개발자용 연동 기술 요약

제조사별 추가 인터페이스는 어댑터 확장으로 적용할 수 있습니다. 데이터 형식·인증·현장 네트워크에 맞춘 연결 시험 후 적용합니다.

지원 프로토콜·인증·수집 방식 보기

REST

HTTPS GET 주기 수집 · JSON 객체/NDJSON · 선택 Bearer 토큰 파일. 제조사 확장 필드와 원본을 보존합니다.

HTTPS GET · JSON/NDJSON

MQTT

MQTT v5 · 고정 topic QoS 1 구독 · TLS · 사용자/비밀번호 파일. 상태·이벤트·미션·텔레메트리 매핑을 지원합니다.

v5 · QoS 1 · TLS

Site Agent

REST/MQTT 수집 · 암호화 로컬 버퍼 · 재전송. 콘솔에서 heartbeat·수집 상태·버퍼 사용량을 조회합니다.

수집·버퍼·재전송

시뮬레이터

합성 데이터를 생성해 필드 매핑과 정규화 규칙을 시험합니다. 실제 제조사 SDK 연결 완료를 의미하지 않습니다.

합성 시험

등록부터 정규화 결과 확인까지

현재 구현된 전송 계약을 파일과 합성 예제로 확인하세요. 상태·센서·오류·미션 수신, Receipt 추적, 현재 상태 조회를 연결합니다.

합성 자료 · 실제 계정 없음AMR-031 · SOC 48%

01. 버전이 고정된 계약과 합성 자료

공개 계약은 수신·접수 상태·현재 상태 조회의 6개 operation을 포함합니다. 관리·자격 발급·예측 API는 제공하지 않습니다. 계약 버전 확인: docs/api/openapi.yaml, SHA-256 ab41dd6bd8e19bb94613f19aaa9319fb639ba546368f37a6784a1a9eea67ebc6.

JSON·Agent 설정·Docker 예제 다운로드

표시 코드와 파일은 같은 데이터이며 manifest에는 파일별 해시가 있습니다. 고정 시각·ID는 문서용입니다. 실제 전송 전 등록값과 실제 측정 시각으로 맞춥니다.

02. 등록 범위와 인증을 먼저 맞춥니다

  1. 운영자가 고객·사업장과 제조사 정보를 등록합니다.
  2. PlatformAdmin의 할당 범위에서 Connector와 수집 서비스 자격을 준비합니다. 등록된 Connector ID·sourceGeneration·mappingVersion을 확인합니다.
  3. 운영자가 Connector·수집 종류·세대에 맞는 서버 출처를 등록하고 robotExternalId를 같은 Connector에 연결합니다. Agent의 sources[]는 수집 설정이며 서버 출처 등록을 대신하지 않습니다. 현재 공개 Source 등록 API는 없습니다.
  4. 부품은 자산 변경 권한이 있는 사용자 자격으로 등록합니다. 기존 부품의 교체를 기록한 뒤 새 부품은 새 ID로 등록합니다. 수집 서비스 토큰으로 자산을 생성하지 않습니다.

수신·Receipt 조회는 OAuth client_credentials의 ServiceBearer, 로봇 상태·부품 조회는 현재 범위에 할당된 UserBearer를 사용합니다. 고객·사업장 접근 범위를 요청 본문으로 넓힐 수 없습니다.

현재 부품 이력 API와 변경 규칙
자산 계약 · UserBearerHTTP
GET /api/v1/robots/{id}/components
POST /api/v1/robots/{id}/components
PATCH /api/v1/robot-components/{id}

BATTERY·MOTOR·LIDAR·OTHER의 모델·일련번호·설치 및 교체 시각을 관리합니다. 변경은 자산 권한과 expectedVersion 검사 대상입니다. 서버 출처 등록은 이 부품 API와도 별개입니다.

시험 base URL과 OIDC token endpoint는 운영자가 지정한 로컬 HTTPS gateway를 사용합니다. 아래 RONIQ_TEST_BASE_URL, RONIQ_SERVICE_TOKEN, RONIQ_USER_TOKEN은 발급된 시험값을 담는 환경변수이며 공개 샌드박스 주소나 실제 토큰이 아닙니다.

03. 데이터 전송 → Receipt → 현재 상태

상태 예제는 AMR-031의 OEM 보고 SOC 48%입니다. 예상 운용시간이나 위험 점수를 제조사 보고 DTO에 넣지 않습니다. 배치는 1~500항목·전체 1MiB, 원문 항목 decoded 512KiB 이내입니다.

응답의 message는 현재 서버 언어인 한국어를 유지합니다. 오류 코드와 schema는 언어에 따라 바꾸지 않습니다.

수신 operation 목록
현재 수신 계약 · ServiceBearerHTTP
POST /ingest/v1/states         ingestStates
POST /ingest/v1/telemetry      ingestTelemetry
POST /ingest/v1/events         ingestEvents
POST /ingest/v1/missions       ingestMissions
GET /ingest/v1/receipts/{id}    getIngestReceipt

요청 · POST /ingest/v1/statesJSON파일 다운로드
{
  "connectorId": "connector-demo-031",
  "sourceGeneration": 1,
  "synthetic": true,
  "items": [
    {
      "eventId": "state-demo-031-001",
      "robotExternalId": "AMR-031",
      "observedAt": "2026-10-04T01:44:00Z",
      "sequence": 31,
      "connectivity": "ONLINE",
      "operation": "RUNNING",
      "batterySoc": 48,
      "source": {
        "sourceId": "source-demo-states",
        "mappingVersion": "mapping-demo-1",
        "sourceQuality": "VALID",
        "freshnessSeconds": 0
      },
      "rawPayload": {
        "mediaType": "application/json",
        "body": "eyJyb2JvdElkIjoiQU1SLTAzMSIsImJhdHRlcnlTb2MiOjQ4fQ==",
        "sha256": "c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
      },
      "extensions": {
        "ext.sim.source": "SIMULATOR"
      }
    }
  ]
}

원문은 {"robotId":"AMR-031","batterySoc":48}의 UTF-8 bytes입니다. rawPayload.body는 그 bytes의 base64, sha256은 같은 bytes의 해시입니다. 예제 품질은 명시적 VALID이며 실제 출처의 품질이 없거나 미정이면 UNKNOWN으로 보존합니다.

전송 명령 · 등록된 로컬 시험 환경Shell
curl --request POST "$RONIQ_TEST_BASE_URL/ingest/v1/states" \
  --header "Authorization: Bearer $RONIQ_SERVICE_TOKEN" \
  --header "Idempotency-Key: demo-state-031-001" \
  --header "Content-Type: application/json" \
  --data-binary @apps/web/public/integration/1.1.6/states.request.json

응답 · HTTP 202 영속 접수JSON파일 다운로드
{
  "success": true,
  "code": "SUCCESS",
  "message": "처리되었습니다.",
  "data": {
    "receiptId": "receipt-demo-031-001",
    "acceptedCount": 1,
    "status": "RECEIVED",
    "receivedAt": "2026-10-04T01:44:02Z",
    "synthetic": true,
    "payloadRefs": [
      "raw-demo-031-001"
    ],
    "checksums": [
      "c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
    ]
  },
  "meta": {
    "requestId": "request-demo-031",
    "timestamp": "2026-10-04T01:44:02Z"
  }
}

202는 내구 저장 접수이며 정규화 완료가 아닙니다. data.receiptId로 같은 서비스 범위의 수신증을 조회합니다.

조회 요청 · Receipt와 상태Shell
curl "$RONIQ_TEST_BASE_URL/ingest/v1/receipts/<RECEIPT_ID>" \
  --header "Authorization: Bearer $RONIQ_SERVICE_TOKEN"

curl "$RONIQ_TEST_BASE_URL/api/v1/robots/<REGISTERED_ROBOT_ID>/state" \
  --header "Authorization: Bearer $RONIQ_USER_TOKEN"

대기·완료·실패 상태와 오류 응답

RECEIVED → PROCESSING → COMPLETED 또는 FAILED로 진행합니다. 아래는 가능한 상태별 예제이며 완료 후 실패로 바뀌었다는 이력이 아닙니다. FAILED 조회도 HTTP 200·success:true이며 data.status로 처리 실패를 구분합니다. 오류 객체는 요청 자체의 거절입니다.

HTTP 200 · PROCESSINGJSON파일 다운로드
{
  "success": true,
  "code": "SUCCESS",
  "message": "처리되었습니다.",
  "data": {
    "receiptId": "receipt-demo-031-001",
    "acceptedCount": 1,
    "status": "PROCESSING",
    "receivedAt": "2026-10-04T01:44:02Z",
    "synthetic": true,
    "payloadRefs": [
      "raw-demo-031-001"
    ],
    "checksums": [
      "c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
    ]
  },
  "meta": {
    "requestId": "request-demo-031",
    "timestamp": "2026-10-04T01:44:02Z"
  }
}

HTTP 200 · COMPLETEDJSON파일 다운로드
{
  "success": true,
  "code": "SUCCESS",
  "message": "처리되었습니다.",
  "data": {
    "receiptId": "receipt-demo-031-001",
    "acceptedCount": 1,
    "status": "COMPLETED",
    "receivedAt": "2026-10-04T01:44:02Z",
    "synthetic": true,
    "payloadRefs": [
      "raw-demo-031-001"
    ],
    "checksums": [
      "c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
    ]
  },
  "meta": {
    "requestId": "request-demo-031",
    "timestamp": "2026-10-04T01:44:02Z"
  }
}

HTTP 200 · FAILEDJSON파일 다운로드
{
  "success": true,
  "code": "SUCCESS",
  "message": "처리되었습니다.",
  "data": {
    "receiptId": "receipt-demo-031-001",
    "acceptedCount": 1,
    "status": "FAILED",
    "receivedAt": "2026-10-04T01:44:02Z",
    "synthetic": true,
    "payloadRefs": [
      "raw-demo-031-001"
    ],
    "checksums": [
      "c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
    ]
  },
  "meta": {
    "requestId": "request-demo-031",
    "timestamp": "2026-10-04T01:44:02Z"
  }
}

거절 응답 · HTTP 422 미등록 출처JSON파일 다운로드
{
  "success": false,
  "code": "BUSINESS_RULE_VIOLATION",
  "message": "등록되지 않은 원본 출처입니다.",
  "data": null,
  "meta": {
    "requestId": "request-demo-031",
    "timestamp": "2026-10-04T01:44:02Z"
  }
}

현재 상태 응답 · HTTP 200JSON파일 다운로드
{
  "success": true,
  "code": "SUCCESS",
  "message": "처리되었습니다.",
  "data": {
    "robotId": "robot-demo-031",
    "connectivity": "ONLINE",
    "operation": "RUNNING",
    "healthOem": null,
    "batterySoc": 48,
    "observedAt": "2026-10-04T01:44:00Z",
    "receivedAt": "2026-10-04T01:44:02Z",
    "stale": false,
    "synthetic": true,
    "sourceId": "source-demo-states",
    "mappingVersion": "mapping-demo-1",
    "freshnessSeconds": 0,
    "extensions": {
      "ext.sim.source": "SIMULATOR"
    }
  },
  "meta": {
    "requestId": "request-demo-031",
    "timestamp": "2026-10-04T01:44:03Z"
  }
}

robotId는 서버 ID이고 AMR-031은 robotExternalId입니다. observedAt은 OEM 관측시각, receivedAt은 서버 수신시각입니다. 정규화 완료 뒤 같은 출처·SOC·매핑 버전인지 대사합니다.

04. 기존 API·MQTT를 Site Agent로 수집

REST adapter는 등록된 HTTPS URL을 GET으로 주기 조회하며 JSON 객체·NDJSON을 읽습니다. 선택 Bearer token은 파일에서 읽고 redirect·환경 proxy를 자동 추종하지 않습니다. JSON 배열은 항목 경계를 정의한 별도 adapter가 필요합니다.

MQTT v5는 현장 broker의 단일 고정 topic을 QoS 1로 구독하며 외부 연결은 TLS와 사용자·비밀번호 파일을 사용합니다. +/# wildcard는 거절합니다. 다음 message와 Source 설정은 같은 합성 출처입니다.

MQTT 메시지·매핑과 Agent 설정 보기
MQTT · factory/a/amr-031/state · QoS 1JSON파일 다운로드
{
  "eventId": "state-demo-031-001",
  "robotId": "AMR-031",
  "observedAt": "2026-10-04T01:44:00Z",
  "sequence": 31,
  "connectivity": "ONLINE",
  "operation": "RUNNING",
  "soc": 48,
  "quality": "VALID"
}

Source 설정 · MQTT 필드 매핑JSON파일 다운로드
{
  "sourceId": "source-demo-states",
  "transport": "mqtt",
  "kind": "states",
  "mappingVersion": "mapping-demo-1",
  "mqttTopic": "factory/a/amr-031/state",
  "fields": {
    "eventId": "eventId",
    "robotExternalId": "robotId",
    "observedAt": "observedAt",
    "sequence": "sequence",
    "connectivity": "connectivity",
    "operation": "operation",
    "batterySoc": "soc",
    "sourceQuality": "quality"
  }
}

Agent 설정 · 비접속 HTTPS placeholderJSON파일 다운로드
{
  "agentId": "agent-demo-031",
  "tenantId": "tenant-demo",
  "customerId": "customer-demo",
  "siteId": "site-demo",
  "connectorId": "connector-demo-031",
  "sourceGeneration": 1,
  "synthetic": true,
  "bufferCapacityBytes": 1073741824,
  "bufferReserveBytes": 67108864,
  "heartbeatSeconds": 60,
  "sources": [
    {
      "sourceId": "source-demo-states",
      "transport": "rest",
      "kind": "states",
      "mappingVersion": "mapping-demo-1",
      "fields": {
        "eventId": "eventId",
        "robotExternalId": "robotId",
        "observedAt": "observedAt",
        "sequence": "sequence",
        "connectivity": "connectivity",
        "operation": "operation",
        "batterySoc": "batterySoc",
        "sourceQuality": "quality"
      },
      "restUrl": "https://oem.example.invalid/state",
      "pollSeconds": 10
    }
  ]
}

Agent는 원문을 암호화 spool에 commit한 뒤 MQTT ACK를 보냅니다. QoS 1 중복은 가능하며 broker persistent session의 보존 범위를 넘어선 무손실을 보장하지 않습니다. Agent → Core 전송은 같은 HTTPS 수신 API·Receipt 규칙을 따릅니다.

로컬 합성 Docker 구성

Compose는 합성 OEM REST 서비스의 구성 예제입니다. 실행하려면 별도로 제공받은 RONIQ 저장소의 tools/simulator 소스와 Docker가 필요합니다. 공개 다운로드 파일만으로 실행되는 패키지는 아닙니다. 접근 권한은 담당 운영자와 확인하고, 저장소 루트에서 사용하며 18081 포트가 비어 있어야 합니다.

Docker 예제 · 합성 OEM과 Agent 이미지Shell
docker compose --project-directory . \
  -f apps/web/public/integration/1.1.6/compose.synthetic.yaml config --quiet

docker compose --project-directory . \
  -f apps/web/public/integration/1.1.6/compose.synthetic.yaml up --build simulator

curl http://127.0.0.1:18081/vendor/atlas/states

docker build -t roniq-site-agent:local apps/site-agent

Agent 이미지에는 저장소의 apps/site-agent 소스가 필요합니다. 실행 전 운영자에게 등록 범위와 시험용 API/OIDC 환경을 할당받고, 별도 spool 암호키·서비스 secret 파일·UID 10001 볼륨 권한을 준비하세요. 복사·다운로드는 파일을 제공하며 API 실행이나 인증 발급을 대신하지 않습니다. simulator.agent_config의 12개 합성 출처에는 별도 MQTT broker도 필요합니다.

설정 생성 명령 · 등록 ID placeholderShell
# Set PYTHONPATH=tools/simulator in an isolated Python environment.
python -m simulator.agent_config --help
python -m simulator.agent_config --output <LOCAL_AGENT_JSON> \
  --agent-id <REGISTERED_AGENT_ID> --tenant-id <REGISTERED_TENANT_ID> \
  --customer-id <REGISTERED_CUSTOMER_ID> --site-id <REGISTERED_SITE_ID> \
  --connector-id <REGISTERED_CONNECTOR_ID>

05. 시각·단위·재전송을 보존합니다

  • observedAt은 UTC RFC3339 Z이며 수신시각으로 바꾸지 않습니다. 서버는 수신 시각 기준 과거 90일·미래 5분 범위의 관측을 받습니다. 동시각 상태는 sequence로 순서를 판단하고 늦은 상태는 현재 상태를 덮지 않습니다.
  • telemetry의 numericValue/stringValue는 정확히 하나만 non-null입니다. 단위·원본 품질·mappingVersion을 함께 보내고 누락은 0·정상으로 채우지 않습니다. 전류 부호와 누적 카운터 초기화 의미는 제조사 매핑에서 정의합니다.
  • 재전송은 같은 eventId·sequence·Idempotency-Key·본문을 유지합니다. 401은 자격 갱신, 409는 세대·매핑·중복 충돌 확인, 429는 Retry-After, 네트워크·5xx는 backoff 재전송으로 처리합니다. 다른 영구 4xx는 원문을 보존하고 수정 후 처리합니다.
  • 현재 수신 제한은 Connector당 분당 60회·burst 10입니다. CSV는 자산 일괄등록이며 센서 수집 채널이 아닙니다.

06. 지원 데이터와 검증 범위

아래 방식으로 데이터를 연결할 수 있습니다. 실제 제조사 연결에는 해당 환경의 매핑과 시험이 필요합니다. 작은 화면에서는 표 안에서 좌우로 이동할 수 있습니다.

인터페이스데이터 범위연결 전 확인
HTTPS REST직접 POST: states·telemetry·events·missions. Agent GET: JSON 객체·NDJSON 매핑.시험 URL·접근 권한·필드 매핑·단위·관측 시각을 준비하고 접수 상태와 정규화 결과를 대사합니다.
MQTT v5 / QoS 1상태·센서·오류·미션의 JSON 객체. 출처별 고정 topic과 명시적 필드 매핑.고정 topic·TLS·자격 파일을 준비하고 단절·재연결·중복 수신을 현장 broker에서 확인합니다.
Site AgentREST/MQTT → 암호 spool → HTTPS 수신 → Receipt. 출처·단위·시각·품질 보존.소스·등록 범위·비밀 파일·볼륨 권한을 준비하고 매핑·재전송·품질·상태를 시험 환경에서 확인합니다.
UserBearer 자산 API로봇 상태 조회, BATTERY·MOTOR·LIDAR·OTHER의 모델·일련번호·설치/교체 기록.현재 할당 범위·자산 권한·expectedVersion 검사. 수집 서비스 자격과 분리.

현재 Health·Battery·Anomaly API는 품질·coverage·근거·분석 버전이 있는 시험 관측입니다. 새 예상 운용시간·부품별 고장 위험·누적 카운터·예측 feed는 추가 개발 범위이며 이 공개 계약에 포함하지 않습니다. 기존 Incident 서명 Webhook은 예측 알림과 구분합니다. OEM/FMS의 주행·안전 제어는 유지합니다.

검증은 단위·시각·출처 대사, 중복·순서 변경, 단절·재전송, 잘못된 센서값, 부품 교체와 범위 밖 접근을 확인합니다. 합성 시험·실제 제조사 연결·예측 성능 평가는 각각 기록합니다. 파일·schema의 정적 일치는 실제 연결 성공을 뜻하지 않습니다.

시작하기

현재 로봇에서 시작하는,
새로운 운영 방식.

로봇·FMS와 필요한 운영 범위를 알려주세요. 연결 가능한 환경부터 함께 확인합니다.

도입 상담 시작하기