API 마이그레이션 가이드
v1에서 v2로 마이그레이션
이 API 마이그레이션 가이드는 현재 통합을 업데이트하여 새로운 Gori API v2와 함께 작동하도록 하기 위해 수행해야 하는 작업에 대한 구체적인 세부 정보를 제공하기 위해 작성되었습니다.
📌 중요해요!
이 마이그레이션 가이드는 2024년 6월에 지원 중단되는 Gori API v2와 Gori API v1의 차이점에 대해 설명합니다. 사용자는 가능한 한 빨리 마이그레이션할 것을 강력히 권장합니다. Swagger로 이전된 Gori API v2 문서는 다음 링크에서 참조하세요. https://docs-dev.goricompany.com/api/documentation.
API 인증을 OAuth 2.0으로 업데이트하기
Gori는 보안을 강화하고, 사기를 줄이며, 향상된 API 기능을 제공하기 위해 모든 API에 OAuth 2.0 보안 모델을 구현했습니다. 새로운 보안 프로세스의 일환으로 Gori는 API에 대한 기존 API 키 인증을 더 이상 사용하지 않을 것입니다. 2024년 5월 31일 이후에는 더 이상 API 키를 배포하지 않으며, 모든 API 요청 시 베어러 토큰을 전송하여 OAuth 2.0 보안 모델을 구현해야 하는 모든 API 트랜잭션에 대해 클라이언트를 요구할 것입니다. 향후 서비스 중단을 방지하기 위해 가능한 한 빨리 OAuth 2.0으로 통합을 마이그레이션하시기 바랍니다.
OAUTH 2.0을 사용하여 인증하는 방법에 대한 자세한 지침은 이 가이드의 마지막에 있는 API 인증을 참조하세요.
엔드포인트 URL을 v1에서 v2로 업데이트하기
Gori는 API 요청을 할 수 있는 두 가지 다른 API 환경을 지원합니다. 서로 다른 환경에서는 애플리케이션을 프로덕션 환경으로 이동하기 전에 Gori API 호출을 테스트할 수 있습니다. API의 기본 URL을 사용하여 타겟팅하려는 특정 환경을 지정할 수 있습니다.
다음 표는 Gori API v2에서 사용 가능한 스테이징 및 프로덕션 기반 URL을 보여줍니다.
| 환경 | URL |
|---|---|
|
스테이징 |
https://staging.api.goricompany.com/v2 |
|
프로덕션 |
https://api.goricompany.com/v2 |
GET https://api.goricompany.com/v1/shipments
v2의 경우 URL을 다음과 같이 업데이트합니다:GET https://api.goricompany.com/v2/shipments
필요한 변경 사항 적용
새로운 OAUTH 2.0 인증 방법을 구현하는 것 외에도 아래에 설명된 몇 가지 획기적인 API 변경 사항을 도입했습니다.
📌 참고!
기존 Gori API 사용과 관련된 필수 변경 사항만 수행하면 됩니다. 미국 영토, 군대 주소, 외교 주소 또는 해외로 배송하는 경우 배송 생성 요청에 새 HS 관세 번호 및 원산지 속성을 포함해야 합니다(https://docs-dev.goricompany.com/api/documentation#/Shipments/createShipment).
1. 새로운 OAUTH 2.0 POST /auth/token 엔드포인트. 새로운 OAUTH 2.0 액세스 토큰 엔드포인트를 사용하여 인증하는 방법에 대한 자세한 지침은 다음 API 인증 섹션을 참조하세요.
2. ship_date라는 새 속성이 POST /shipments 엔드포인트에 추가되었습니다. 이 속성은 USPS 및 FedEx One Rate 배송에 대해 지정해야 합니다. 지정하지 않으면 배송이 생성된 날짜가 기본값으로 사용됩니다.
📌 중요해요!
지정한 날짜는 배송이 생성된 날짜로부터 7일을 넘지 않아야 합니다. 지정한 날짜가 배송 날짜보다 작으면 오류가 반환되고 배송이 생성되지 않습니다.
3. GET /배송/요금, POST /배송 및 POST /return_배송 엔드포인트의 packageType 속성이 package_type으로 변경되었습니다.
4. 요청에 제공된 우편번호 속성에 대한 값이 없는 경우 응답에 반환되는 값은 빈 문자열 대신 null이 됩니다.
5. HS 관세 번호는 세계관세기구에서 개발한 통일 상품 설명 및 코딩 시스템을 기반으로 해야 합니다. 자세한 내용은 다음을 참조하세요: https://hts.usitc.gov/current. HS 관세 번호를 지정하려면 아래와 같이 배송 요청 생성에 hs_tariff_number 속성 및 HTS 코드(6~14자)를 포함합니다:
{"shipment": {"customs": {"items": [ {"hs_tariff_number": "3926.20"} ] } } }
6. 원산지 국가는 ISO에서 정의한 2자리 영문 국가 코드로, 국제 주소에 필수입니다. 참조하세요: https://www.iso.org/obp/ui/#search 에서 전체 코드 목록을 확인하세요. 원산지를 지정하려면 아래와 같이 배송 요청 생성에 country_of_origin 속성 및 ISO Alpha-2 코드(2자)를 포함하세요:
{ "shipment": {"customs": {"items": [ {"country_of_origin" : "US"} ] } } }
7. 이제 오류 응답에 "log_id"라는 새로운 속성이 포함됩니다.
8. POST /shipments 엔드포인트 및 POST /return_shipments 엔드포인트의 참조1 및 참조2 속성이 참조_1 및 참조_2로 변경되었습니다.
테스트
도움 받기
API 인증
Gori는 각 클라이언트에 대해 클라이언트 ID 및 클라이언트 비밀이라는 고유한 스테이징 및 프로덕션 OAuth 2.0 자격 증명 집합을 생성합니다. 각 인증 요청의 본문에 이러한 자격 증명을 전달하여 OAuth 2.0 서버에서 새 액세스 토큰을 검색합니다. 그런 다음 액세스 토큰을 사용하여 후속 요청에서 API 요청의 인증 역할을 수행합니다. 다음 섹션에서는 이러한 각 단계에 대해 설명합니다.
OAuth 2.0 자격 증명 얻기
📌 중요해요!
공개적으로 자격 증명을 사용하거나 공개해서는 안 됩니다.
액세스 토큰 받기
유효한 자격증명 집합이 있으면(OAuth 2.0 자격증명 가져오기 참조) 다음 단계에 따라 인증 요청을 구성하고 만들 수 있습니다:
1. 권한 부여 API 엔드포인트를 지정합니다:
https://staging.api.goricompany.com/auth/token
2. 콘텐츠 유형 헤더를 추가하여 미디어 유형을 JSON으로 설정합니다:
콘텐츠 유형: application/json
3. 마지막으로 curl과 같은 도구를 사용하여 API 요청을 합니다:
curl -location'https://staging.api.goricompany.com/v2/auth/token/'
-헤더 '콘텐츠 유형: 애플리케이션/json'\
-data '{
"client_id": "{your-client-id}",
"client_secret": "{your-client-secret}",
"grant_type": "client_credentials"
}'
4. API 요청이 완료되면 다음 예시와 같이 OAuth 2.0 서버가 새 토큰으로 응답해야 합니다:
'{
"토큰 유형": "무기명",
"expires_in": 43200,
"access_token": "{access_token}"
}'
📌 중요해요!
액세스 토큰은 12시간 동안 유효합니다. 현재 액세스 토큰이 만료되기 전에 권한 부여 API 엔드포인트에서 새 액세스 토큰을 받는 것이 좋습니다.
유효한 액세스 토큰이 있으면 다음 섹션에 설명된 대로 보호된 리소스에 API 요청을 할 수 있습니다.
요청하기
보호된 리소스에 액세스하려면 클라이언트 인증(액세스 토큰 가져오기) 중에 OAuth 2.0 서버에서 반환한 액세스 토큰을 사용해야 합니다. 이 액세스 토큰은 베어러 HTTP 인증 체계(베어러 인증이라고 함)를 사용하는 후속 API 요청에서 "베어러 토큰"으로 사용됩니다. 클라이언트는 보호된 리소스에 요청할 때 이 베어러 토큰을 HTTP 권한 부여 헤더로 보내야 합니다. 다음은 베어러 토큰(액세스 토큰)과 함께 권한 부여 헤더의 형식을 보여줍니다:
Authorization: Bearer {access_token}
The way to do this using a tool like curl is to use the –header flag, which is used to include an extra header in the request when sending HTTP requests to a server. In our case, –header "Authorization: Bearer {access_token}". For example, to authenticate and retrieve all shipments execute:
curl --location'https://staging.api.goricompany.com/v2/shipments?
page_size=100&page=1&id_after=0&reference_1=12345&created_at_before=2021-07-27'\
--헤더 '수락: 애플리케이션/json'\.
‐‐header 'Authorization: Bearer {access_token)'
Requests with no Authorization header will be rejected with a 401 status code. If this occurs, you need to get a new access token and try the request again
API 마이그레이션 가이드
v1에서 v2로 마이그레이션
이 API 마이그레이션 가이드는 새로운 Gori API v2를 사용하기 위해 현재 통합 환경을 업데이트하는 데 필요한 구체적인 단계에 대한 정보를 제공하기 위해 마련되었습니다.
📌 중요!
이 마이그레이션 가이드는 Gori API v2와 2024년 6월에 서비스가 종료될 Gori API v1 간의 차이점을 설명합니다.
사용자들은 가능한 한 빨리 마이그레이션할 것을 강력히 권장합니다.
Swagger로 이전된 Gori API v2 문서를 참조해 주십시오(주소: https://docs‑dev.goricampany.com/api/documentation ).
API 인증을 OAuth 2.0으로 업데이트
OAUTH 2.0을 사용하여 인증을 수행하는 방법에 대한 자세한 내용은 이 가이드 마지막 부분의 ‘API 인증’을 참조하십시오.
엔드포인트 URL을 v1에서 v2로 업데이트
Gori는 두 가지 서로 다른 API 환경을 지원하며, 사용자는 이 환경들에 API 요청을 보낼 수 있습니다. 각기 다른 환경을 통해 애플리케이션을本番 환경으로 이전하기 전에 Gori API 호출을 테스트해 볼 수 있습니다. API의 기본 URL을 사용하여 원하는 특정 환경을 지정할 수 있습니다.
| 환경 | 웹사이트 |
|---|---|
|
할부 |
https://api-staging.goricompany.com/v2 |
|
생산 |
https://api.goricompany.com/v2 |
https://api.goricampany.com/v1/shipments 다운로드
v2의 경우 URL을 다음과 같이 업데이트하십시오:https://api.goricompany.com/v2/shipments 다운로드
필요한 변경 사항을 적용하십시오
새로운 OAuth 2.0 인증 방식을 도입한 것 외에도, 다음과 같이 API에 여러 가지 주요 변경 사항을 적용했습니다.
📌 주의:
현재 사용 중인 Gori API와 관련된 필수 변경 사항만 적용하시면 됩니다. 미국 영토, 군부대 주소, 외교 주소 또는 해외 주소로 화물을 발송하려는 경우, 발송 요청 생성 시 다음을 시작해야 합니다. https://docs-dev.goricampany.com/api/documentation#/Shipments/createShipment 에 새로운 HS 관세 번호 및 원산지 속성을 포함시켜야 합니다.
1. 새로운 OAuth 2.0 POST /auth/token 엔드포인트. 새로운 OAuth 2.0 액세스 토큰 엔드포인트를 사용하여 인증하는 방법에 대한 자세한 내용은 아래의 API 인증 섹션을 참조하십시오.
2. POST /shipments 엔드포인트에 ship_date라는 새로운 속성이 추가되었습니다. USPS 및 FedEx 단일 요금 배송물의 경우 이 속성을 반드시 지정해야 합니다. 지정하지 않을 경우, 배송물 생성 날짜가 기본값으로 사용됩니다.
📌 주의!
지정된 날짜는 화물 생성일로부터 7일 이내여야 합니다. 지정된 날짜가 화물 생성일보다 앞선 경우 오류가 발생하며 화물이 생성되지 않습니다.
3. GET /shipments/rates의 packageType 속성이 POST /shipments 및 POST /return_shipments 엔드포인트에서 package_type으로 변경되었습니다.
4. 요청에 zipcode 속성의 값이 제공되지 않은 경우, 응답에 반환되는 값은 빈 문자열이 아닌 null이 됩니다.
5. HS 관세 번호는 세계관세기구가 제정한 《상품명 및 코드 조화 체계(HS)》를 기준으로 해야 합니다. 자세한 내용은 https://hts.usitc.gov/current을 참조하십시오. HS 관세 번호를 지정하려면, 다음과 같이 화물 요청 생성 시 hs_tariff_number 속성과 HTS 코드(6~14자)를 포함시켜 주십시오:
{"shipment": {"customs": {"items": [ {"hs_tariff_number": "3926.20"} ] } } }
6. 원산지는 ISO에서 정의한 2자리 모국 국가 코드이며 국제 주소가 필요합니다. 참고: https://www.iso.org/obp/ui/#search获取完整的代码列表. 원산지를 지정하려면 상품 요청에 country_of_origin 속성과 ISO Alpha-2 코드(2자리)를 포함하세요.
{ "shipment": {"customs": {"items": [ {"country_of_origin ": "US"} ] } } }
7. 오류 응답에는 "로그_ID"라는 새로운 속성이 포함됩니다.
8. POST /배송 단점과 POST /return_배송 단점의 참조1 및 참조2 속성이 참조_1 및 참조2로 변경되었습니다.
테스트
도움말 찾기
API 신원 인증
Gori는 각 고객단말이 고객단말 ID와 고객단말 비밀번호라고 하는 고유한 OAuth 2.0 데이터를 생성하고 생성하도록 지원합니다. 您可以在每个身份验证请求的正⽂中传递这些凭据, OAuth 2.0 서버에서 새 방문 인증서를 검색한 후 API 요청에 대한 본인 인증으로 요청 중사 방문 인증서를 계속 사용할 수 있습니다. 아래에서 각 단계에 대해 설명해 드리겠습니다.
OAuth 2.0 데이터 획득
📌 주의!
공개 파트너사에 신청하거나 인증서를 공개할 수 없습니다.
인증 토큰 받기
1. 지정 권한 API 단점:
https://api.goricompany.com/auth/token
2. 콘텐츠 유형 표식을 추가하여 미디어 유형을 JSON으로 설정합니다:콘텐츠 유형: application/json
3. 마지막으로, 컬 등 도구 출시 API 요청하기curl -location 'https://api-staging.goricompany.com/v2/auth/token/'
-헤더 '콘텐츠 유형: 애플리케이션/json'\
-data '{
"client_id": "{你的客⼾端id}",
"client_secret": "{你的客⼾端秘密}",
"grant_type": "client_credentials"
}'
4. API 요청 후, 다음과 같은 예시처럼 인증 2.0 서버가 새 레이블을 적용합니다.'{
"토큰 유형": "무기명",
"expires_in": 43200,
"access_token": "{access_token}"
}'
📌 주의!
방문자 권한 유효기간은 12시간이며, 이전 방문자 권한이 만료되기 전에 권한 API 단점을 통해 새 방문자 권한을 얻어야 합니다.
유효한 방문 권한이 있는 경우 아래 설명과 같이 보호 리소스 출력 API 요청을 받을 수 있습니다.
출시 요청
리소스를 보호하려면 OAuth 2.0 서버에서 고객 단의 인증(방문 권한 획득) 기간에 OAuth 2.0 서버에서 반환된 방문 권한이 필요합니다. 방문 권한은
Bearer HTTP 신원 인증 방법(이하 Bearer 신원 인증)의 후속 API 요청 중에 "승격"을 수행합니다. 고객 단에서 보호 대상 리소스 출력을 요청할 때 반드시
HTTP 授权标头에서 이 승격 패드를 전송해야 합니다.
授权：持有者{access_token}
使⽤ curl 等⼯具执⾏此操作的方法是使⽤ ‒header ag，它⽤于在向服务器发送 HTTP 请求时在请求中包含额外的标头。在我们的例⼦中，‒header
“Authorization: Bearer {access_token}”。例如，要验证和检索所有货件，请执⾏：
卷曲 -location https://api-staging.goricompany.com/v2/shipments?
page_size=100&page=1&id_after=0&reference_1=12345&created_at_before=2021-07-27'\\.
--헤더 接受：응용프로그램/json \
‐‐header 授权：承载 {access_token)
没有授权标头的请求将被拒绝，并显示 401 状态代码。如果发生这种情况，您需要获取新的访问令牌并再次尝试请求