본문으로 건너뛰기

Versioning

카페24 API는 날짜 기반 버전(yyyy-mm-dd) 으로 관리됩니다. 이전 버전과 호환되지 않는 변경사항(Breaking Changes)이 발생할 때 새로운 날짜 버전이 릴리즈되며, 호출 시 원하는 버전을 명시적으로 지정할 수 있습니다.

📌 버전 포맷​

Version yyyy-mm-dd

예) 2021-03-01, 2024-09-01

이전 버전과 호환되지 않는 변경사항이 있을 때마다 해당 시점의 날짜로 새로운 버전이 릴리즈됩니다.

🔧 버전 지정 방법​

요청 시 X-Cafe24-Api-Version 커스텀 헤더를 통해 사용할 버전을 지정할 수 있습니다.

curl -X GET \
  'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'X-Cafe24-Api-Version: yyyy-mm-dd'

헤더 미지정 시 동작​

X-Cafe24-Api-Version 헤더를 지정하지 않을 경우, 개발자센터 > 개발정보에 설정된 앱 버전으로 동작합니다.

⚙️ 앱 버전 설정 경로​

앱 버전은 개발자센터에서 직접 확인 및 변경할 수 있습니다.

개발자센터(로그인) > Apps > 개발정보 > 인증정보 내 버전관리
단계위치
1개발자센터 로그인
2Apps 메뉴 진입
3해당 앱의 개발정보 선택
4인증정보 > 버전관리 에서 버전 변경

⏳ 버전 만료 정책​

항목정책
만료 기간최신 버전 릴리즈가 출시된 시점부터 최대 1년
만료 후 동작만료되지 않은 버전 중 가장 오래된 버전으로 자동 대체

⚠️ 사용 중이던 버전이 만료된 경우 동작이 달라질 수 있으므로, 신규 버전이 릴리즈되면 호환성을 검토하고 명시적으로 업그레이드하는 것을 권장합니다.

🌐 적용 범위​

X-Cafe24-Api-Version 헤더는 다음 API 전반에 동일하게 적용됩니다.

  • Admin API — 어드민용 REST API
  • Front API — 프론트엔드 REST API
  • Cafe24 Analytics API — 분석용 API

세 API 모두 동일한 날짜 기반 버전 체계와 1년 만료 정책을 따릅니다.

💡 Best Practices​

1. 운영 환경에서는 버전을 명시적으로 지정​

# ✅ 권장: 버전을 명시하여 예측 가능한 동작 보장
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'X-Cafe24-Api-Version: 2024-09-01'

명시적으로 버전을 지정하면 개발자센터의 앱 버전 설정이 변경되어도 호출 동작이 영향을 받지 않습니다.

2. 신규 버전 릴리즈 시 호환성 검토​

  • 새로운 날짜 버전이 릴리즈되면 변경사항(Breaking Changes)을 검토하세요.
  • 스테이징 환경에서 신규 버전으로 테스트한 뒤 운영에 반영합니다.

3. 만료 임박 버전 모니터링​

  • 사용 중인 버전이 1년 만료에 가까워지면 사전에 업그레이드를 진행하세요.
  • 만료된 버전은 자동으로 다른 버전으로 대체되어 의도치 않은 동작이 발생할 수 있습니다.

📚 참고 자료​