REST · JSON APIBearer 토큰 인증실시간 로봇 상태VDA5050 지원

M2 로봇 연동 API

Polaris3D AMR을 고객사의 관제 시스템(FMS)이나 MES에 연동하고, 로봇의 실시간 상태·위치·미션 이력을 간단한 REST API로 조회하세요.

2개 리소스 · 4개 엔드포인트

두 가지 조회 리소스로 로봇 모니터링과 미션 추적을 할 수 있습니다. 모든 엔드포인트는 인증이 필요한 GET 요청이며, JSON으로 응답합니다.

API 레퍼런스

기본 URL, 인증 방법, 엔드포인트별 명세입니다. 응답 필드와 예시는 항목을 눌러 펼쳐 볼 수 있습니다.

  1. 토큰 발급발급받은 계정으로 /api/v1/auth/token을 호출합니다.
  2. 헤더에 토큰 첨부Authorization: Bearer <토큰>
  3. API 호출아래 엔드포인트로 GET 요청을 보냅니다.
기본 URLhttps://{host}/api/v1 ({host}는 발급받은 IP 또는 도메인)
전송 방식HTTPS · JSON (UTF-8)
Content-Typeapplication/json

인증 · 토큰 발급

모든 API는 Bearer 액세스 토큰이 있어야 호출할 수 있습니다.

POST/api/v1/auth/token

요청 본문 (Request Body)

Key타입필수설명
client_idString발급받은 클라이언트 ID
client_secretString발급받은 시크릿 키
응답 필드4
Key타입설명
access_tokenStringAPI 호출용 액세스 토큰
token_typeString항상 Bearer
expires_inInteger토큰 유효 시간(초)
refresh_tokenString토큰 만료 시 재발급에 사용하는 토큰
요청 · 응답 예시
POST /api/v1/auth/token
Content-Type: application/json

{ "client_id": "발급받은_client_id", "client_secret": "발급받은_client_secret" }

--- 200 OK ---
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def502..."
}

계정 발급 안내: 클라이언트 ID와 시크릿 키는 연동 문의 시 발급해 드립니다. 토큰 만료 및 갱신 정책도 이때 함께 안내해 드립니다.

공통 에러

모든 엔드포인트에 동일하게 적용됩니다.

HTTP Status설명
401 Unauthorized인증되지 않은 사용자
403 Forbidden권한이 없어 요청이 거부됨
500 Internal Server Error서버 에러
501 Not Implemented기타 에러
에러 응답 본문2
Key타입설명
error_codeInteger에러 식별자
messageString에러 원인 설명

미션 리스트

미션 목록을 페이지 단위로 조회합니다.

GET/api/v1/missions

쿼리 파라미터

파라미터타입설명
mission_idString미션 ID로 필터
site_idString사이트로 필터
object_idString오브젝트(로봇)로 필터
map_idString맵으로 필터
mission_state_idInteger미션 상태로 필터
pageInteger페이지 번호 (기본값 0)
응답 필드 · mission15
Key타입필수설명
mission_idString미션 ID
mission_stateObject상태: 0 WAITING · 1 CANCELED · 2 PROCESS · 3 COMPLETE · 4 ASSIGNED · 5 ERROR · 6 ASSIGN_FAILED · 7 ASSIGN_PREPARING
mission_creatorObject생성 주체: 100 자동 · 101 수동 · 102 재생성 · 103 라인콜
siteObject사이트
mapObject맵
objectObject오브젝트(로봇)
priorityObject우선순위: 1 상 · 2 중 · 3 하
mission_resultObject결과: 0 START · 1 FINISHED · 2 CANCEL · 3~8 각종 실패 · 100~115 서버/EV/웹소켓 등 에러 · 501 FINISHED_EARLY_FOR_NEXT_MISSION
mission_reject_reasonString미션 거절 사유
mission_start_timeString시작 시각
mission_end_timeString종료 시각
mission_timeString소요 시간
mission_typeObject타입: 50 MCS · 100 물류 · 102 복귀
updated_atString변경 일시
created_atString등록 일시
응답 필드 · page (페이징)5
Key타입설명
contentList미션 목록 (없으면 빈 리스트)
total_page_countInteger전체 페이지 수
now_page_numberInteger현재 페이지 번호 (0부터 시작)
total_element_countInteger전체 요소 수
now_element_countInteger현재 페이지의 요소 수
응답 예시 (200 OK)
{
  "content": [
    {
      "mission_id": "mi-u2jg-bgae",
      "mission_state": { "id": 1, "label": "취소" },
      "mission_creator": { "id": 100, "label": "자동" },
      "site": { "id": "s001", "label": "s001" },
      "map": { "id": "m001", "label": "m001" },
      "object": { "id": "o001", "label": "o001" },
      "priority": { "id": 1, "label": "상" },
      "mission_start_time": "2025-08-11 15:43:00.0",
      "mission_end_time": "2025-08-11 15:43:00.0",
      "mission_time": "0분0초",
      "mission_type": { "id": 100, "label": "물류" },
      "created_at": "2025-08-11 14:08:00.0",
      "updated_at": "2025-08-11 15:43:00.0",
      "mission_result": { "id": 2, "label": "사용자 취소" }
    }
  ],
  "total_page_count": 4,
  "now_page_number": 3,
  "total_element_count": 43,
  "now_element_count": 1
}

미션 상세

단일 미션의 상세 정보와 서브미션 목록을 조회합니다.

GET/api/v1/missions/{mission_id}

경로 변수 (Path Variable)

파라미터타입설명
mission_idString조회할 미션 ID
응답 필드 · 추가 필드2

미션 리스트의 mission 필드를 모두 포함하며, 아래 필드가 추가됩니다.

Key타입필수설명
origin_mission_idString원본 미션 ID
submissionsList서브미션 리스트. 요소: submission_id, submission_type(1 목적지 이동 후 대기 · 2 대기장소 복귀 · 3 충전스테이션 복귀 · 4 수거 · 5 공급), submission_destination, submission_start_time, submission_end_time, submission_time, is_in_progress, amr_operation_modes(List), error_messages(List), created_at, updated_at
응답 예시 (200 OK)
{
  "mission_id": "m001",
  "mission_state": { "id": 0, "label": "대기중" },
  "mission_creator": { "id": 100, "label": "자동" },
  "site": { "id": "SITE001", "label": "호텔" },
  "map": { "id": "MAP001", "label": "호텔1층" },
  "object": { "id": "AMR001", "label": "로봇1" },
  "priority": { "id": 1, "label": "상" },
  "mission_result": { "id": 1, "label": "성공" },
  "mission_type": { "id": 100, "label": "물류" },
  "origin_mission_id": null,
  "created_at": "2024-12-12 12:32:00.0",
  "updated_at": "2024-12-12 12:32:00.0",
  "submissions": [
    {
      "submission_id": "si001",
      "submission_type": { "id": 4, "label": "수거" },
      "submission_destination": "Rack001",
      "submission_time": "2분0초",
      "is_in_progress": 0,
      "amr_operation_modes": ["2단 공급", "1단 수거"],
      "error_messages": []
    },
    {
      "submission_id": "si002",
      "submission_type": { "id": 5, "label": "공급" },
      "submission_destination": "Rack002",
      "is_in_progress": 0,
      "amr_operation_modes": ["2단 공급", "1단 수거"],
      "error_messages": ["[22] 측위 LiDAR 상태 이상", "[24] 휠 인코더 상태 이상"]
    }
  ]
}

이동형 오브젝트 리스트

사이트 내 로봇(이동형 오브젝트) 목록과 실시간 상태를 조회합니다. 별도의 요청 파라미터는 없습니다.

GET/api/v1/amr/objects
응답 필드 (배열 요소)10
Key타입필수설명
object_idString오브젝트 ID
object_typeObject종류: 1 배송 · 2 서빙 · 3 물류 · 5 M3
siteObject사이트
object_nameString오브젝트명
stateObject상태: -2 오프라인 · -1 초기화중 · 0 에러 · 1 대기중 · 2 진행중 · 3 정지 · 6 충전중 · 7 대기장소 복귀중 · 8 충전스테이션 복귀중 · 9 도킹중 · 10 AMR 수동조작
mapObject현재 위치(맵)
coordinateObject현재 좌표: coordinate_x, coordinate_y, direction
batteryString배터리 잔량
prevent_mission_executionInteger미션 수행 방지: 0 OFF(기본) · 1 ON
last_communication_timeString마지막 통신 시각
응답 예시 (200 OK)
[
  {
    "object_id": "amr-ywfx",
    "object_type": { "id": 3, "label": "물류 로봇" },
    "site": { "id": "st-pls3", "label": "폴라리스3D" },
    "object_name": "물류로봇1번",
    "state": { "id": -1, "label": "초기화중" },
    "last_communication_time": "2025-03-21 13:22:42",
    "map": { "id": "4f_fih", "label": "퍼스트힐 4층" },
    "coordinate": {
      "coordinate_x": "250.7113581270456",
      "coordinate_y": "220.8253131469545",
      "direction": "-140.0"
    },
    "battery": "100",
    "prevent_mission_execution": 1
  }
]

이동형 오브젝트 상세

단일 로봇의 상세 상태를 조회합니다. 하드웨어 모듈(포크, 그리퍼, 컨베이어, 리프트) 상태, 미션 진행 상황, 적재 정보를 확인할 수 있습니다.

GET/api/v1/amr/objects/{object_id}

경로 변수 (Path Variable)

파라미터타입설명
object_idString조회할 오브젝트 ID
응답 필드 · 추가 필드17

오브젝트 리스트의 필드를 모두 포함하며, 아래 필드가 추가됩니다. 모듈 필드(fork, gripper, conveyor, top_lift, bottom_lift)는 로봇 종류에 따라 포함 여부가 다릅니다.

Key타입설명
serial_numberString시리얼 번호
activate_dateString활동 시작일
deactivate_dateString활동 종료일
error_codesList현재 발생 중인 에러 (예: {"id":22,"label":"측위 LiDAR 상태 이상"})
mission_completedInteger미션 완료 횟수
mission_idString현재 진행 중인 미션 ID
current_positionString현재 위치(경로)
destinationString목적지 (node_id 기준)
loadingObject적재 정보 (현재 미사용, 기본값 null)
loadingsList<Object>적재 정보. 요소: stage, loading
forkObject포크: state, error_codes, depth
gripperObject그리퍼: state, error_codes, depth, width, xoffset
conveyorList<Object>컨베이어. 요소: stage, state, error_codes
top_liftObject탑 리프트: state, error_codes, height
bottom_liftObject바텀 리프트: state, error_codes, height
pick_drop_direction_idsList<Integer>수거·공급 방향 (VDA5050 사용 시): 1 FRONT · 2 REAR · 3 LEFT · 4 RIGHT
docking_direction_idsList<Integer>도킹 방향 (VDA5050 사용 시): 1 FRONT · 2 REAR · 3 LEFT · 4 RIGHT
응답 예시 (200 OK · M3)
{
  "object_id": "amr-5ofn",
  "object_type": { "id": 5, "label": "M3" },
  "site": { "id": "st-pls3", "label": "폴라리스3D" },
  "object_name": "M3",
  "state": { "id": 0, "label": "에러" },
  "last_communication_time": "2026-03-05 16:36:39",
  "map": { "id": "4f_fih", "label": "퍼스트힐 4층" },
  "coordinate": { "coordinate_x": "123.45", "coordinate_y": "67.89", "direction": "180.0" },
  "battery": "87",
  "prevent_mission_execution": 0,
  "error_codes": [ { "id": 22, "label": "측위 LiDAR 상태 이상" } ],
  "mission_completed": 0,
  "mission_id": "",
  "destination": "",
  "loadings": [
    { "stage": "1", "loading": "적재중" },
    { "stage": "2", "loading": "비어 있음" }
  ],
  "fork": { "state": "에러", "error_codes": [ { "id": 501, "label": "측위 실행 불가" } ], "depth": "1200" },
  "gripper": { "state": "대기중", "error_codes": [], "depth": "500", "width": "300", "xoffset": "15" },
  "conveyor": [
    { "stage": "1", "state": "회전중", "error_codes": [ { "id": 201, "label": "배터리 부족 및 방전 중 에러" } ] },
    { "stage": "2", "state": "전진", "error_codes": [] }
  ],
  "top_lift": { "state": "상승중", "error_codes": [ { "id": 200, "label": "배터리 부족 에러" } ], "height": "1500" },
  "bottom_lift": { "state": "하강중", "error_codes": [], "height": "300" },
  "pick_drop_direction_ids": [1, 2, 3, 4],
  "docking_direction_ids": [1]
}

M2 정품 부품도 함께 확인하세요

구동계·전장·센서·배터리 등 M2 정품 교체 부품을 카테고리별로 보고, 필요한 부품의 견적을 바로 요청할 수 있습니다.

TOP