개요

빠른 시작

curl "https://external-api.oasis-arca.com/api/v1/ext/stations" \
  -H "x-api-key: <발급받은 API 키>"

응답의 null 값 필드는 생략될 수 있습니다. 파서는 필드 부재를 허용하도록 구현하십시오.

목록 API(stations · chargers · transactions)는 공통으로 page(0-base, 기본 0) / size(기본 50, 최대 200) 페이지네이션을 지원하며, 응답에 items와 함께 page/size/totalElements/totalPages 메타가 포함됩니다.

인증 (API 키)

모든 요청에 발급받은 API 키를 x-api-key 헤더로 전달합니다. 키는 CPO(사업자) 단위로 CSMS 운영팀이 발급합니다.

x-api-key: <발급받은 API 키>

• 키 누락·무효 → 403 (게이트웨이 단)
• 운영팀에서 차단된 키 → 403 (백엔드 단)
• 다른 CPO 소유 자원은 목록에서 제외되고, 상세 조회 시 404로 응답합니다.

사용량 제한

플랜 상향이 필요하면 운영팀에 문의하십시오.

오류 응답

오류는 발생 지점에 따라 두 가지 형태로 반환됩니다.

게이트웨이 단 (키 검증·사용량 제한)

{ "message": "Forbidden" }

백엔드 단 (파라미터·대상 검증)

{ "error": "조회 기간은 최대 92일까지 가능합니다." }

변경 정책

• URL은 /api/v1/ext/로 고정됩니다.
• 하위 호환을 깨지 않는 변경(응답 필드 추가, enum 값 추가 등)은 예고 없이 이루어질 수 있습니다. 파서는 알 수 없는 필드·enum 값을 무시하도록 구현하십시오.
• 호환이 깨지는 변경이 필요한 경우 별도 공지 후 진행합니다.

충전소 목록

키에 매핑된 CPO가 소유한 충전소 목록을 이름 오름차순으로 반환합니다 (페이지네이션).

쿼리 파라미터

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/stations?page=0&size=50" -H "x-api-key: <API 키>"

응답 200

{
  "items": [
    {
      "id": 103,
      "sid": "100001",
      "name": "OO빌딩 충전소",
      "address": "경기 과천시 과천대로7나길 60",
      "detailAddress": "C동 505호",
      "postalCode": "13840",
      "latitude": 37.432265,
      "longitude": 126.994741,
      "createdAt": "2026-06-15T05:16:07.760511"
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1,
  "totalPages": 1
}

충전소 상세 (소속 충전기 포함)

충전소 단건을 조회합니다. 목록 항목의 필드에 더해 해당 충전소 소속 충전기 목록(chargers, ID 오름차순)이 포함되며, 각 충전기의 스키마는 충전기 목록·상태의 항목과 동일합니다(커넥터 상태 포함). 존재하지 않거나 다른 CPO 소유인 경우 404.

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/stations/103" -H "x-api-key: <API 키>"

응답 200

{
  "id": 103,
  "sid": "100001",
  "name": "OO빌딩 충전소",
  "address": "경기 과천시 과천대로7나길 60",
  "detailAddress": "C동 505호",
  "postalCode": "13840",
  "latitude": 37.432265,
  "longitude": 126.994741,
  "createdAt": "2026-06-15T05:16:07.760511",
  "chargers": [
    {
      "id": 3004,
      "stationId": 103,
      "identity": "CP-0001",
      "online": true,
      "status": "Available",
      "operative": true,
      "ocppVersion": "1.6",
      "currentFirmwareVersion": "A00.00.01",
      "lastHeartbeat": "2026-07-10T06:00:53.706155Z",
      "connectors": [
        { "connectorId": 1, "status": "Charging", "operative": true, "lastStatusTime": "2026-07-10T06:02:55.678207Z" }
      ]
    }
  ]
}

충전기 목록·상태

CPO 소유 충전기 목록을 ID 오름차순으로 반환합니다 (페이지네이션). 각 충전기에 커넥터별 실시간 상태가 포함됩니다.

쿼리 파라미터

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/chargers?page=0&size=50" -H "x-api-key: <API 키>"

응답 200

{
  "items": [
    {
      "id": 3004,
      "stationId": 103,
      "identity": "CP-0001",
      "online": true,
      "status": "Available",
      "operative": true,
      "ocppVersion": "1.6",
      "currentFirmwareVersion": "A00.00.01",
      "lastHeartbeat": "2026-07-10T06:00:53.706155Z",
      "connectors": [
        { "connectorId": 1, "status": "Charging", "operative": true, "lastStatusTime": "2026-07-10T06:02:55.678207Z" }
      ]
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1,
  "totalPages": 1
}

충전기 상세

충전기 단건(커넥터 상태 포함)을 조회합니다. 응답 스키마는 목록의 항목과 동일합니다. 존재하지 않거나 다른 CPO 소유인 경우 404.

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/chargers/3004" -H "x-api-key: <API 키>"

충전 트랜잭션 내역

충전 트랜잭션 내역을 시작 시각 내림차순으로 반환합니다. 기간은 [from, to) 반개구간으로 필터됩니다.

쿼리 파라미터

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/transactions?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z&page=0&size=50" \
  -H "x-api-key: <API 키>"

응답 200

{
  "items": [
    {
      "id": 98765,
      "chargerId": 3004,
      "chargerIdentity": "CP-0001",
      "connectorId": 1,
      "startTime": "2026-07-11T02:10:00Z",
      "stopTime": "2026-07-11T03:05:12Z",
      "consumedWh": 21500,
      "totalFee": 6450.00,
      "reason": "Remote"
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1,
  "totalPages": 1
}

OpenAPI 스펙

기계가독형 계약 문서(OpenAPI 3.0)를 제공합니다. 클라이언트 코드 생성(openapi-generator 등)에 사용할 수 있습니다.

• external-api.openapi.yaml — OpenAPI 3.0.3 (YAML)

# 예: TypeScript 클라이언트 생성
npx @openapitools/openapi-generator-cli generate \
  -i https://admin.oasis-arca.com/docs/external-api.openapi.yaml \
  -g typescript-fetch -o ./csms-external-client

문의

API 키 발급·차단, 사용량 플랜, 응답 필드 추가 요청 등은 CSMS 운영팀에 문의하십시오.

문의: axd@bionever.com