개요

빠른 시작

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",
      "chargerCount": 4,
      "chargerCountsByPower": [
        { "maxPowerKw": 7, "count": 3 },
        { "maxPowerKw": 100, "count": 1 }
      ]
    }
  ],
  "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",
  "chargerCount": 1,
  "chargerCountsByPower": [{ "maxPowerKw": 7, "count": 1 }],
  "chargers": [
    {
      "id": 3004,
      "stationId": 103,
      "identity": "CP-0001",
      "maxPowerKw": 7,
      "manufacturer": "바이온에버",
      "modelName": "BSS007K-V11-J",
      "online": true,
      "status": "Available",
      "operative": true,
      "ocppVersion": "1.6",
      "currentFirmwareVersion": "A00.00.01",
      "lastHeartbeat": "2026-07-10T06:00:53.706155Z",
      "kepcoContract": {
        "voltageType": "LOW",
        "planOption": "OPTION_1",
        "demandChargeEnabled": false,
        "contractDemandKw": 150.00
      },
      "connectors": [
        { "connectorId": 1, "status": "Charging", "operative": true, "connectorType": "CCS1", "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",
      "maxPowerKw": 7,
      "manufacturer": "바이온에버",
      "modelName": "BSS007K-V11-J",
      "online": true,
      "status": "Available",
      "operative": true,
      "ocppVersion": "1.6",
      "currentFirmwareVersion": "A00.00.01",
      "lastHeartbeat": "2026-07-10T06:00:53.706155Z",
      "kepcoContract": {
        "voltageType": "LOW",
        "planOption": "OPTION_1",
        "demandChargeEnabled": false,
        "contractDemandKw": 150.00
      },
      "connectors": [
        { "connectorId": 1, "status": "Charging", "operative": true, "connectorType": "CCS1", "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 키>"

충전기 판매 단가 설정 (v1.9.0)

충전기에 CSMS 에 설정된 판매 단가를 반환합니다. 충전기에 질의하지 않는 설정값이라 충전기가 오프라인이어도 응답합니다. 기준일(date, KST, 기본 오늘)에 유효한 단가 세트가 할당돼 있으면 시간대별 회원/비회원 단가를, 없으면 CPO 기본 단가를 적용 대상으로 표시합니다. 존재하지 않거나 다른 CPO 소유인 충전기는 404.

쿼리 파라미터

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/chargers/3004/pricing?date=2026-09-18" -H "x-api-key: <API 키>"

응답 200

{
  "chargerId": 3004,
  "chargerIdentity": "CP-0001",
  "asOf": "2026-09-18",
  "currency": "KRW",
  "priceUnit": "KRW/kWh",
  "source": "ASSIGNED_PRICE_SET",
  "priceSet": {
    "id": 3,
    "name": "주간 세트",
    "validFrom": "2026-09-01",
    "validTo": "2026-12-31",
    "timeRanges": [
      { "start": "00:00:00", "end": "12:00:00", "memberPrice": 150.00, "nonMemberPrice": 180.00 },
      { "start": "12:00:00", "end": "00:00:00", "memberPrice": 220.00, "nonMemberPrice": 260.00 }
    ]
  },
  "defaultUnitPrice": { "member": 200.00, "nonMember": 240.00 },
  "rounding": { "mode": "HALF_UP", "unit": 1 }
}

충전기 충전 프로필 — CSMS 설정값 (v1.10.0)

CSMS 가 이 충전기에 SetChargingProfile 로 보낸 충전 프로필(전력 제한값·시간대별 스케줄)의 현재 유효한 목록입니다. 충전기에 질의하지 않는 CSMS 전송 기록이며, 충전기가 실제로 수락했는지는 항목별 commandStatus로 판단하십시오(기준선으로 쓸 때는 ACCEPTED만). 존재하지 않거나 다른 CPO 소유인 충전기는 404.

요청 예시

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

응답 200

{
  "chargerId": 3004,
  "chargerIdentity": "CP-0001",
  "ocppVersion": "1.6",
  "asOf": "2026-09-18T03:00:00Z",
  "profiles": [
    {
      "profileId": 1587249301,
      "connectorId": 0,
      "purpose": "ChargePointMaxProfile",
      "purposeOcpp": "ChargePointMaxProfile",
      "kind": "Recurring",
      "recurrency": "Daily",
      "stackLevel": 0,
      "validFrom": "2026-09-18T00:00:00Z",
      "validTo": "2026-12-31T15:00:00Z",
      "schedule": {
        "duration": 86400,
        "startSchedule": "2026-09-18T00:00:00Z",
        "chargingRateUnit": "W",
        "periods": [
          { "startPeriod": 0,     "limit": 7000, "numberPhases": 1 },
          { "startPeriod": 32400, "limit": 3500, "numberPhases": 1 },
          { "startPeriod": 64800, "limit": 7000, "numberPhases": 1 }
        ]
      },
      "source": "PRESET",
      "sentAt": "2026-09-18T00:00:05Z",
      "commandStatus": "ACCEPTED",
      "commandRespondedAt": "2026-09-18T00:00:06Z"
    }
  ]
}

충전 트랜잭션 내역

충전 트랜잭션 내역을 시작 시각 내림차순으로 반환합니다. 기간은 [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,
      "assessedFee": 6450.00,
      "authType": "MEMBER_CARD",
      "feeBreakdown": {
        "pricingSource": "ASSIGNED_PRICE_SET",
        "memberType": "MEMBER",
        "exempted": false,
        "energyWh": 21500,
        "currency": "KRW",
        "priceSet": { "id": 3, "name": "주간 세트" },
        "segments": [
          { "from": "2026-07-11T02:10:00Z", "to": "2026-07-11T03:00:00Z", "energyKwh": 19.5455, "unitPrice": 300.00, "fee": 5863.6364 },
          { "from": "2026-07-11T03:00:00Z", "to": "2026-07-11T03:05:12Z", "energyKwh": 1.9545, "unitPrice": 300.00, "fee": 586.3636 }
        ],
        "rounding": { "mode": "HALF_UP", "unit": 1, "rawFee": 6450.0000, "finalFee": 6450.00 }
      },
      "reason": "Remote",
      "metricsExcluded": false
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1,
  "totalPages": 1
}

feeBreakdown — 요금 산정 스냅샷 (v1.8.0)

거래 종료 시점에 어떤 단가가 어느 시간대 구간에 적용됐는지를 고정한 기록입니다. 단가 세트는 운영자가 수정할 수 있으므로 이 스냅샷이 그 거래에 적용된 단가의 유일한 근거입니다. 도매(정산) 단가와 결제 수단 정보는 담지 않습니다.

거래별 미터값 시계열

한 트랜잭션에 적재된 미터값(누적 전력량·순시 전력)을 시각 오름차순으로 반환합니다. 충전기 MeterValues 보고 주기(통상 약 60초)로 적재되며, 진행 중인 세션도 조회할 수 있습니다. 보관 중인 과거 거래는 기간 제한 없이 트랜잭션 ID로 소급 조회할 수 있습니다.

쿼리 파라미터

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/transactions/98765/meter-values?page=0&size=200" \
  -H "x-api-key: <API 키>"

응답 200

{
  "items": [
    { "timestamp": "2026-08-27T09:23:28Z", "context": "Transaction.Begin", "energyWh": 273, "powerW": null },
    { "timestamp": "2026-08-27T09:24:28Z", "context": "Sample.Periodic",   "energyWh": 294, "powerW": 1260 }
  ],
  "page": 0,
  "size": 200,
  "totalElements": 2,
  "totalPages": 1
}

출력 등급 분류 기준

충전기 출력 등급(완속/중속/급속)의 분류 기준을 반환합니다. 충전기 응답의 maxPowerKw(kW)를 grades 배열 순서대로 상한과 비교해 첫 매칭이 그 충전기의 등급입니다(마지막 등급은 상한 없음). CPO와 무관한 공통 기준이며, CSMS 관리콘솔 대시보드 「출력 분포」와 동일합니다. maxPowerKw가 없는(모델 미지정) 충전기는 미분류로 취급하십시오.

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/meta/speed-grades" \
  -H "x-api-key: <API 키>"

응답 200

{
  "basis": "chargers[].maxPowerKw (kW)",
  "grades": [
    { "grade": "SLOW", "label": "완속", "upperBoundKw": 11, "upperInclusive": true },
    { "grade": "MID",  "label": "중속", "upperBoundKw": 50, "upperInclusive": false },
    { "grade": "FAST", "label": "급속", "upperBoundKw": null, "upperInclusive": null }
  ]
}

한전 요금표 (v1.11.0)

한전 EV 충전 요금표(도매원가 단가)를 반환합니다. CPO와 무관한 전역 데이터이며, CSMS 기동 시 표준 요금표가 자동 입력되고 이후 CSMS 운영자가 관리합니다. 충전기 응답의 kepcoContract(voltageType·planOption)로 그 충전기에 적용되는 요금표 행을 고른 뒤, seasons(월 기준 계절)와 timeBands(계절 그룹별 KST 시간대)로 시각별 단가를 적용합니다 — CSMS 내부 원가 계산과 동일한 해석입니다.

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/meta/kepco-tariffs" \
  -H "x-api-key: <API 키>"

응답 200

{
  "currency": "KRW",
  "rateUnit": "KRW/kWh",
  "demandChargeUnit": "KRW/kW/월",
  "seasons": [
    { "season": "SUMMER", "months": [6, 7, 8] },
    { "season": "SPRING_FALL", "months": [3, 4, 5, 9, 10] },
    { "season": "WINTER", "months": [1, 2, 11, 12] }
  ],
  "timeBands": [
    { "seasons": ["SUMMER", "SPRING_FALL"], "ranges": [
      { "start": "08:00:00", "end": "11:00:00", "band": "MID_PEAK" },
      { "start": "11:00:00", "end": "12:00:00", "band": "ON_PEAK" },
      { "start": "12:00:00", "end": "13:00:00", "band": "MID_PEAK" },
      { "start": "13:00:00", "end": "18:00:00", "band": "ON_PEAK" },
      { "start": "18:00:00", "end": "22:00:00", "band": "MID_PEAK" },
      { "start": "22:00:00", "end": "08:00:00", "band": "OFF_PEAK" } ] },
    { "seasons": ["WINTER"], "ranges": [ ... ] }
  ],
  "holidayBand": "OFF_PEAK",
  "saturdayPeakBand": "MID_PEAK",
  "tariffs": [
    { "voltageType": "HIGH", "planOption": "OPTION_2",
      "effectiveFrom": "2026-01-01",
      "demandChargePerKw": 2580.00,
      "rates": {
        "summer":     { "offPeak": 78.20, "midPeak": 113.00, "peak": 198.60 },
        "springFall": { "offPeak": 80.20, "midPeak": 91.00,  "peak": 94.90 },
        "winter":     { "offPeak": 95.20, "midPeak": 105.50, "peak": 172.40 } } },
    { "voltageType": "HIGH", "planOption": "OPTION_4",
      "effectiveFrom": "2026-01-01",
      "demandChargePerKw": 2580.00,
      "rates": {
        "summer":     { "allTime": 137.40 },
        "springFall": { "allTime": 91.00 },
        "winter":     { "allTime": 127.70 } } }
  ]
}

충전 부하 예측 (v1.13.0 · 충전소 단위 v1.14.0)

키에 매핑된 CPO 의 시간별 충전 부하 예측입니다. CSMS 가 매일 05:50(KST)에 당일 06:00 ~ 다음날 05:00 24시간을 예측합니다(AWS SageMaker, 주 1회 재학습). 기준일(date, KST, 기본 오늘) 00:00~24:00 의 시각을 돌려주며, 같은 시각을 여러 번 예측했으면 가장 최근 생성분만 나옵니다 — 오늘 기준일의 00~05시는 전날 예측입니다. 예측 대상이 아닌 CPO(최근 2주 충전량이 적은 경우)나 예측 적재 전이면 points 가 빈 배열입니다.stationId 를 주면 그 충전소 하나의 예측과 그 충전소 충전기의 계약전력 합을 돌려줍니다(v1.14.0). 키의 CPO 소속이 아니면 404 이고, 주간 재학습의 홀드아웃 오차(WAPE)가 100% 를 넘는 충전소는 기준 미달로 points 가 빕니다.

요청 예시

curl "https://external-api.oasis-arca.com/api/v1/ext/load-forecast?date=2026-10-21" \
  -H "x-api-key: <API 키>"
# 충전소 하나 (v1.14.0)
curl "https://external-api.oasis-arca.com/api/v1/ext/load-forecast?date=2026-10-21&stationId=120" \
  -H "x-api-key: <API 키>"

응답 200

{
  "date": "2026-10-21",
  "stationId": null,
  "contractKw": 217.00,
  "modelVersion": "k3x9q2abcd1e",
  "points": [
    { "timestamp": "2026-10-21T01:00:00Z", "p50Kw": 10.42, "p90Kw": 38.92, "forecastMadeAt": "2026-10-20T20:50:12Z" },
    { "timestamp": "2026-10-21T02:00:00Z", "p50Kw": 9.93, "p90Kw": 43.65, "forecastMadeAt": "2026-10-20T20:50:12Z" }
  ]
}

• p50Kw — 예측 중앙값: 그 1시간 평균 부하(kW). 1시간 공급 에너지(kWh)와 같은 수입니다.
• p90Kw — 예측 90% 상단: 실제 부하가 이 값 이하일 것으로 보는 상단. 피크 대비·계약전력 초과 경보에 쓰십시오.
• contractKw — CSMS 에 등록된 충전기 계약전력 합(kW).
• 시각은 모두 UTC ISO-8601 입니다(timestamp 는 그 시각부터 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