Authentication
딜리버리 트래커 API들을 사용하기 위해서는 아래 두 방법 중 하나를 선택하여 인증하여야 합니다.
Method 1. API Key (Recommended)
Step 1. Delivery Tracker Console 에서 Credentials 를 가져옵니다.
Delivery Tracker Console 에서 프로젝트의 Credentials 을 가져옵니다.
프로젝트 생성 및 Credentials 생성 방법은 본 문서 하단의 Console 을 사용하여 Credentials 생성 항목을 참고해주세요.
Step 2. API 에 액세스 토큰 보냅니다.
Step 2에서 획득한 Access Token 을 사용하여 아래와 같이 사용하고자 하는 API 를 호출 합니다.
Request
POST https://apis.tracker.delivery/graphql
Authorization: TRACKQL-API-KEY [YOUR_CLIENT_ID]:[YOUR_CLIENT_SECRET]
Content-Type: application/json
{"query": "query AuthTestQuery { carriers(first: 10) { edges { node { id name } } } }"}
Request Header 의 [YOUR_CLIENT_ID], [YOUR_CLIENT_SECRET] 를 Console 을 사용하여 Credentials 생성을 통해 획득한 Client Id, Client Secret로 대체하여야 합니다.
2024-05-13 이전에 등록된 Client ID는 API Key로 사용할 수 없으며, oauth2 방식만 제공합니다. API Key 사용을 위해 새로운 Credentials를 생성하여 주십시오.
Method 2. OAuth2 Access Token
Step 1. Delivery Tracker Console 에서 Credentials 를 가져옵니다.
Delivery Tracker Console 에서 프로젝트의 Credentials 을 가져옵니다.
프로젝트 생성 및 Credentials 생성 방법은 본 문서 하단의 Console 을 사용하여 Credentials 생성 항목을 참고해주세요.
Step 2. Delivery Tracker 인증 서버로부터 액세스 토큰 가져옵니다.
Delivery Tracker 인증 서버는 OAuth 2.0 Client Credentials 표준을 준수 합니다.
Step 1 과정을 통해 획득한 Credentials 정보를 이용하여 다음과 같이 HTTP Request를 전송하여 Access Token 을 생성 합니다.
Request
POST https://auth.tracker.delivery/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]
Request Body 의 [YOUR_CLIENT_ID], [YOUR_CLIENT_SECRET] 를 Credentials 정보 (Client ID, Client Secret) 로 대체하여야 합니다.
Response
{
"access_token": "[YOUR_ACCESS_TOKEN]",
...
}
Step 3. API 에 액세스 토큰 보냅니다.
Step 2에서 획득한 Access Token 을 사용하여 아래와 같이 사용하고자 하는 API 를 호출 합니다.
Request
POST https://apis.tracker.delivery/graphql
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/json
{"query": "query AuthTestQuery { carriers(first: 10) { edges { node { id name } } } }"}
Request Header 의 [YOUR_ACCESS_TOKEN] 를 Step 2 과정을 통해 획득한 Access Token 으로 대체하여야 합니다.
Step 4. 필요한 경 우 액세스 토큰을 갱신합니다.
Access Token 이 만료 된 경우 API 응답에 다음과 같이 에러가 발생합니다.
HTTP Response Status Code 는 무관하며 Request Body의 errors 항목을 조회하여야 합니다.
{
"errors": [
...,
{
"extensions": { "code": "UNAUTHENTICATED" }
},
...
]
}
위와 같이 UNAUTHENTICATED 에러가 발생한 경우 Step 2 과정을 통해 다시 Access Token 을 받아와야 합니다.
에러 처리에 대해 더 자세한 설명은 Error Handling 문서를 참고해주세요.
Appendix. Console 을 사용하여 Credentials 생성
이 파트에서는 Delivery Tracker 인증을 위한 Credentials 을 생성하는 방법에 대해 다룹니다.
Step 1. Console 에서 프로젝트 생성하기
Step 1-1. 콘솔 접 속
Delivery Tracker Console 에 접속 합니다.
Step 1-2. 콘솔 가입 및 로그인
콘솔에서 Google 계정 혹은 Email 을 통하여 회원가입 및 로그인 합니다.
Step 1-3. 프로젝트 생성
로그인 이후 프로젝트 목록 페이지에서 "Create Project" 버튼을 클릭하여 프로젝트 생성 페이지로 이동합니다.
이후 프로젝트 정보를 입력하고 "Create Project" 버튼을 클릭하여 프로젝트를 생성하고 생성한 프로젝트 페이지로 이동 합니다.
Step 2. Console 에서 Credentials 생성하기
Step 2-1. 프로젝트 선택
"Project List" 페이지에서 Credentials 생성을 원하는 프로젝트를 클릭하여 프로젝트 페이지로 이동합니다.
Step 2-2. Credentials 생성
프로젝트 페이지의 좌측 메뉴에서 "Credentials" 를 클릭하여 Credentials 목록 페이지로 이동 합니다.
이후 Credentials 목록 페이지에 존재하는 "Create Credentials" 버튼을 클릭하여 Credentials을 생성합니다.
생성된 "Client Id" 와 "Client Secret" 를 확인해주세요. 이 정보는 이 문서 상단의 "기본 단계" 파트에서 사용 됩니다.
"Client Secret" 의 경우 외부에 노출되지 않도록 주의가 필요하며, 발급된 이후 재조회가 불가능 합니다.
만약, Client Secret 를 분실한 경우 재조회가 불가능하여 새로운 Credentials 를 발급 받아 사용해야 합니다.
