개발가이드
시작하기
API Key를 발급하고, 개발 환경에서 검증한 뒤 상용으로 전환하는 순서예요.
API Key 발급하기
발급은 셀러 대표 계정만 할 수 있어요. 직원 계정에는 메뉴가 보이지 않아요.
- 설정 > API 연동 메뉴로 이동파트너센터에 로그인한 뒤 좌측 메뉴에서 설정 > API 연동을 열어요.
- 키 발급키 발급 버튼을 누르고 연동 목적(셀메이트·이지어드민 등)을 선택하면 발급돼요.
- 키 원문 복사발급 직후 화면에 키 원문이 표시돼요. 복사해서 연동 담당자에게 전달해요.
- 다시 봐야 할 때목록에서는 앞 12자만 보여요. 원문을 다시 확인하려면 해당 키의 재표시를 눌러요.
- 쓰지 않는 키는 폐기더 이상 쓰지 않는 키는 폐기해요. 폐기는 즉시 적용되고 되돌릴 수 없어요.
키는 자격증명이에요
API Key는 셀러 데이터 전체를 읽고 상태를 바꿀 수 있는 자격증명이에요. 소스코드·이슈트래커·메신저에 남기지 말고 시크릿 저장소에 보관해 주세요.개발 환경에서 상용까지
dev 환경은 상용과 동일한 API 계약을 제공하는 별도 환경이에요. API 도메인과 데이터가 완전히 분리돼 있고, 키도 발급된 환경에서만 유효해요. 마음 놓고 테스트해도 돼요.
발급된 키에는 환경 표시가 접두로 붙어 있어요 — 개발 환경 키는 vpk_test_, 실서비스 키는 vpk_live_로 시작해요. 키를 다른 환경에 등록하면 401 INVALID_API_KEY로 거절되는데, 그때 키의 접두를 보면 어느 환경 키인지 바로 알 수 있어요.
| 단계 | 주체 | 내용 |
|---|---|---|
| 1 | 뷰리티 | 연동사에 이 가이드와 API 레퍼런스를 전달해요 |
| 2 | 셀러 | 파트너센터에서 개발용 키(vpk_test_)를 발급해 연동사에 전달해요 |
| 3 | 연동사 | dev 환경(admin-api-dev.vurity.kr)에서 전 플로우를 개발·검증해요 |
| 4 | 셀러 | 검증이 끝나면 실서비스 키(vpk_live_)를 발급해 연동사에 전달해요 |
| 5 | 연동사 | 상용 환경(admin-api.vurity.kr)으로 전환해요 |
첫 호출로 확인하기
키를 발급했다면 주문 목록 조회 한 번으로 연결을 확인할 수 있어요. 발급받은 키를 X-Api-Key 헤더에 넣어 호출해요.
curl -H "X-Api-Key: (발급받은 키 전체 — vpk_test_로 시작)" \
"https://admin-api-dev.vurity.kr/open/v1/orders?updated_at_gte=2026-08-25T15:00:00Z&limit=10"정상이라면 아래처럼 meta.code가 200인 응답이 와요. 아직 주문이 없어도 list가 빈 배열로 오면 연결은 성공이에요.
{
"meta": { "code": 200, "message": "OK", "error_code": null, "error_data": null },
"data": { "list": [], "next_cursor": null }
}401이 온다면 키 값이나 환경(도메인)이 맞는지, 422가 온다면 시각 파라미터 형식을 확인해요 — URL에 +09:00을 쓸 때의 인코딩 주의는 공통 규약에 있어요.
키를 교체할 때
키 교체(회전)는 무중단으로 할 수 있어요. 새 키를 발급해 연동사에 전달하고, 전환이 끝난 뒤 구 키를 폐기하면 돼요.
다음으로
키를 준비했다면 공통 규약에서 인증 헤더와 응답 형식, 재시도 규칙을 확인해요.