본문 바로가기

API 가이드

1. API 사용 관련

  • 지마켓, 옥션 판매자 회원이어야 하며 ESM+ 로그인하여 마스터 ID 도 생성되어야 합니다.
  • 셀링툴 업체 경우도 지마켓, 옥션 사이트별 사업자 판매자 회원 가입 필수 입니다.
  • 궁금하신 점은 etapihelp@gmail.com 메일로 주시면 확인 후 회신 드릴 예정입니다.
  • 신청 승인은 사이트 검색성능 및 서비스 안정성을 저해하지 않는 수준 내 내부 지원 리소스 한도 내에서 가능합니다.
  • 검토 후 입점 순서에 따라 API Secret Key 발급해드립니다. (G마켓옥션 통합API 권한신청서 다운로드)
  • 내부 사정에 따라 API 연동이 거절될 수 있음을 미리 양해하여 주시면 감사하겠습니다.
[사용 신청 메일 Sample]
- 개발 API 범위 : 상품 등록/수정, 주문 수집, 주문 처리, 클레임 처리

- 서비스 중인 사이트 Url : (자사 사이트 또는 판매 상품 확인 가능 url)

- API 개발 기간 : **년 *월 *일 ~ **년 *월 *일

※ 셀링툴 서비스 경우 소개 자료 및 이용중 G마켓/옥션 셀러수 : 지마켓 #개, 옥션 #개

 

2. API 개발 가이드

  • API는 상품/주문/배송/클레임/정산/CS/서비스 별로 구성되어 있으며 가이드는 상단 메뉴별로 확인하실 수 있습니다.
  • API 개발 완료 후 개발 사항 테스트 완료되면 일정 협의하여 운영에서 실사용하실 수 있습니다.

 

3. API 이해하기

Description
ESM Trading API를 사용하기 위해서는 Header에 아래 내용을 참고한 인증값을 설정합니다. (모든 API 동일)
ESM Trading API 인증은 정상적으로 발급된 키의 사용자인지, 허용된 서버(IP address)에서 전달된 요청인지, 요청이 전달되는 과정에서 악의적으로 요청이 오염되었는지를 체크합니다.
권한은 인증된 사용자라 해도 특정 리소스(API)에 접근이 허용된 사용자인지를 판단합니다. 따라서, API를 사용할 때는 인증 및 권한도 부여받아야 합니다

 

API 인증방식

public/private key를 이용한 JWT 인증 방식(JWT 참고)

  • 청인증 방식은 HMAC 해싱 방식으로 생성된 비밀키(Secret Key)를 사용자에게 발행하며 Secret Key로 header와 payload를 해싱한 signature를 생성해서 JWT(JSON Web Token)을 만들어 이를 Http 헤더를 통해 API 인증 서버로 전송하는 방식으로 처리됩니다.
  • 클라이언트는 ESM+를 통해 관리자에게 사용할 key pair(Access Key/Secret Key) 발급 및 권한을 요청합니다. (현재는 ESM+ 메뉴를 오픈하지 않아 메일로 직접 판매자 마스터ID와 Secret Key 요청 필요 / 문의 메일: etapihelp@gmail.com) ESM+의 API 인증 담당 관리자는 요청을 검토하고 키를 발급한 후에, 사용할 API에 대한 접근 권한을 부여합니다. ESM+ API 인증 관리자를 통해 발급받은 인증 key pair는 분실 또는 유효기간 만료 등의 이유로 재발급이 가능하며 재발급 전에는 한번 발급받은 key pair를 계속 사용하면 됩니다.
  • 이런 과정을 통해 획득한 key pair를 사용해서 클라이언트는 API 인증 서버가 요구하는 값을 Base64로 인코딩하고 Signature를 생성해 API 호출 시 Header를 통해 전달합니다. Selling API는 호출 직전에 인증 및 권한을 체크하기 위해 인증 시스템이 요청을 확인하고 API의 사용 가능 여부를 판단합니다. 인증/권한 체크에서 실패가 떨어지면 인증 시스템은 요청을 중간에 차단하고 바로 UnAuthorization 오류를 클라이언트에 전달합니다. 하지만 인증/권한 체크가 통과하면 클라이언트의 요청은 호출한 API로 전달되고 그 결과가 클라이언트에 리턴됩니다.

인증 도식화

 

API 인증 토큰 구성 및 Sample Code

인증 토큰은 아래와 같이, Header와 Payload, Signature를 “.” 으로 연결하는 형태로 구성됩니다.

Header는 해싱(hashing) 알고리즘을 정의하는 정보와 사용자의 Identity를 나타내는 값으로 구성되며, 아래와 같이 json 포맷으로 표현하고 base64로 인코딩합니다.

{
	"alg": "HS256", // 인증 알고리즘
	"typ": "JWT", // 인증방식
	"kid": "{master id}" // ESM+ Master ID 입력
}

Payload는 사용자에 관한 정보와 몇 가지 API에 대한 메타 데이터를 포함하는 json 포맷의 구조로 Header와 마찬가지로 base64로 인코딩 됩니다.

{
	"iss": "{token issuer}", // 토큰 발행자. 보통 클라이언트 도메인 주소 사용 ex)www.shinsegaemall.ssg.com, www.playauto.com
	"sub": "{domain}", // Sell API는 "sell"
	"aud": "sa.esmplus.com", // 좌측 정보로 고정해서 사용
	"iat": "{issued timestamp(long type)}", // JWT 발행 시간 (필수 정보 아님)
	"ssi": "{site Id}:{site seller id}" // Site Id : 옥션 “A”, 지마켓 “G” 입력
}

Signature는 위에서 정의한 Header와 Payload 값을 사용해서 해싱하여 고유의 기호를 만들어 내는 작업입니다. 마찬가지로 base64로 인코딩된 Header와 Payload 값을 사용해서 HmacSHA256으로 값을 해싱합니다.

HS256(base64UrlEncode(header) + "." +base64UrlEncode(payload), secret key)

 

Sample Code
예를 들어, sell 도메인의 특정 API를 호출하려는 사용자가 있는데, 이 사용자의 ESM+의 masterId는 “test_masterId_1” 이며 Selling API를 사용하기 위해 발급받은 Access Key는 입니다.

ZDE2YjlmZjUtYTc0Mi00ZWU3

그리고, 이 요청을 보내는 시점을 “2017-08-21 14:40:00(KST 기준)”라고 했을 때 이 값을 timestamp로 변환하면 “1503294000”가 됩니다. (timestamp 변환은 https://www.epochconverter.com / 참조)


그럼 이 상황대로 토큰을 발행하기 위해 Header와 Payload 값을 구성해 보면 아래와 같습니다.

  • 호스팅사의 경우, kid는 무조건 호스팅사의 마스터ID를 넣어주셔야 합니다.
Header
{
	"alg": "HS256",
	"typ": "JWT",
	"kid": "ESM+마스터ID"
}
Payload
{
	"iss": "www.esmplus.com",
	"sub": "sell",
	"aud": "sa.esmplus.com", //  좌측 정보 고정해서 사용
	"ssi": "A:옥션판매자ID, G:지마켓판매자ID" // "," 구분자로 지마켓/옥션 ID 입력 가능(단 1개씩)
}

 

그리고, 이 Header와 Payload를 base64로 인코딩한 후 Secret Key로 해싱해서 각각 아래와 같은 값들을 얻었다고 가정해 보면,

Base64 encoded Header: "4eadf432lkjavnasdfkje32lkadjsf09"
Base64 encoded Payload: "zxcvlkjq234i8jl/+02jkldq341lkjzxdfckj"
Signature: "MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAUAwggE8AgEAAkEAsEdjazrTLHbg4z9CgYQrg+1O"

이 요청의 토큰은 아래와 같이 됩니다. (“.”으로 구분된 형태 확인)

"Authorization" : "Bearer 4eadf432lkjavnasdfkje32lkadjsf09.zxcvlkjq234i8jl/+02jkldq341lkjzxdfckj.MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAUAwggE8AgEAAkEAsEdjazrTLHbg4z9CgYQrg+1O"

 

API 요청 보내기/결과

토큰을 생성했다면, 이제 API를 호출하면 됩니다. API를 호출할 때는 인증 과정을 통과하기 위해서 Http Request의 Header에 인증 토큰을 실어 보내야 합니다. 토큰을 실어 보낼 Http Header의 키는 "Authorization"이며, 스키마는 Bearer입니다. 그래서, 요청을 보낼 때는 Http Header에 아래의 키/값을 추가해야 합니다. (참고로, Authorization 헤더 값의 포맷은 “{Schema} {Token}” 입니다.)

// http header
“Authorization” : “Bearer 4eadf432lkjavnasdfkje32lkadjsf09.zxcvlkjq234i8jl/+02jkldq341lkjzxdfckj.MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAUAwggE8AgEAAkEAsEdjazrTLHbg4z9CgYQrg+1O”

 

Http Header에 Authorization 키로 토큰을 실어 보냈고 Selling API 인증 시스템에서 전달된 토큰으로 문제없이 인증과 권한을 모두 통과했다면 API 호출은 정상적으로 API 서버에 전달될 것입니다. 그리고 처리 결과는 클라이언트에 리턴 됩니다.
하지만, 인증 또는 권한에서 요구하는 조건을 만족시키지 못했다면 요청은 API 서버로 전달되지 않고 곧바로 Selling API 인증 시스템에서 클라이언트로 오류를 리턴하게 되며 리턴 결과는 상황에 맞는 Http Status Code가 전달됩니다.


예를 들면, 접근 권한이 없는 API에 요청을 보내면 아래와 같은 결과가 클라이언트로 리턴 됩니다.

{
	"status": {
		"message": "The user does not have right access to the api",
		"status_code": 401
	}
}

 

JWT를 소개하고 있는, jwt.io 웹사이트에서는 다양한 플랫폼별로 사용할 수 있는 jwt 라이브러리들 역시 소개하고 있습니다.
https://jwt.io 웹사이트에 접근 후, 상단의 “Libraries” 메뉴를 보면 다양한 플랫폼별로 여러 개의 라이브러리가 제공되고 있는 것을 쉽게 알 수 있습니다. 따라서, 개발 플랫폼에 맞는 라이브러리들을 선택해서 쉽게 인증 코드를 구현할 수 있습니다.

티스토리툴바