아마존 SP API 통합 방법: 단계별 튜토리얼

요약

아마존 셀링 파트너 API(SP-API)는 주문, 재고, 상품 목록, 주문 처리 등 셀러 데이터를 REST 방식으로 자동화할 수 있게 해주는 핵심 API입니다. 이 API는 IAM 역할 기반 OAuth 2.0 인증, AWS SigV4 요청 서명, 엔드포인트별 속도 제한(초당 0.1~100회 요청)을 요구합니다. 본 가이드는 계정 및 IAM 설정, 인증, 주요 엔드포인트 활용, 웹훅 구독, 프로덕션 배포 전략까지 실전 통합 방법을 단계별로 정리합니다.

지금 Apidog 사용해보세요

💡 Apidog는 SP-API 테스트 자동화에 최적화되어 있습니다. 엔드포인트 테스트, OAuth 흐름 검증, 요청 서명 검사, 인증 문제 디버깅을 한 번에. API 사양 가져오기, 응답 모의, 테스트 시나리오 협업까지 지원합니다.

아마존 SP-API란 무엇인가요?

아마존 셀링 파트너 API(SP-API) 는 셀러 센트럴의 핵심 데이터에 REST 방식으로 접근하는 공식 API입니다. 기존 MWS 대비 보안, 성능, 기능이 대폭 향상됐으며, 2025년 12월 MWS 종료 이후 필수로 전환해야 합니다.

주요 기능

• 주문 검색/상태 업데이트
• 다중 마켓플레이스 재고 관리
• 상품 목록 생성/수정/삭제
• FBA(아마존 배송) 관리
• 가격 책정 및 경쟁 분석
• 보고서/분석 생성
• A+ 콘텐츠, 브랜드/광고 데이터 활용

SP-API vs. MWS 비교

기능	SP-API	MWS(레거시)
아키텍처	RESTful JSON	XML 기반
인증	OAuth 2.0+IAM	MWS 인증 토큰
보안	AWS SigV4	단순 토큰
호출 속도	동적 제한	고정 할당량
마켓플레이스	통합 엔드포인트	지역별
상태	현재	2025년 종료예정

필수: 모든 MWS 연동은 즉시 SP-API로 마이그레이션하세요.

API 아키텍처 및 엔드포인트

• https://sellingpartnerapi-na.amazon.com (북미)
• https://sellingpartnerapi-eu.amazon.com (유럽)
• https://sellingpartnerapi-fe.amazon.com (극동)

모든 요청 필수:

1. AWS SigV4 서명
2. OAuth 액세스 토큰
3. IAM 역할 권한
4. 요청 ID

지원 마켓플레이스

지역	마켓플레이스	API 엔드포인트
북미	미국, 캐나다, 멕시코	sellingpartnerapi-na.amazon.com
유럽	영국, 독일, 프랑스 등	sellingpartnerapi-eu.amazon.com
극동	일본, 호주, 싱가포르 등	sellingpartnerapi-fe.amazon.com

시작하기: 계정 및 IAM 설정

1단계: 아마존 개발자 계정 생성

1. 아마존 개발자 센터 접속
2. 아마존 계정(셀러 센트럴 권한 필요)으로 로그인
3. 대시보드 → Selling Partner API
4. 개발자 계약 동의

2단계: 애플리케이션 등록

1. 셀러 센트럴 로그인
2. 앱 및 서비스 → 앱 개발
3. 새 앱 추가
4. 애플리케이션 정보 입력(이름, 유형, 목적, OAuth 리다이렉트 URI)

발급 정보:

• 애플리케이션 ID
• 클라이언트 ID/시크릿

보안: 자격 증명은 반드시 환경 변수에 보관

# .env 파일 예시
AMAZON_APPLICATION_ID="amzn1.application.xxxxx"
AMAZON_CLIENT_ID="amzn1.account.xxxxx"
AMAZON_CLIENT_SECRET="your_client_secret_here"
AMAZON_SELLER_ID="your_seller_id_here"
AWS_ACCESS_KEY_ID="your_aws_access_key"
AWS_SECRET_ACCESS_KEY="your_aws_secret_key"
AWS_REGION="us-east-1"

3단계: SP-API용 IAM 역할 생성

1. AWS IAM 콘솔
2. 역할 → 역할 생성
3. 신뢰할 수 있는 엔터티: 다른 AWS 계정
4. 아마존 계정 ID 입력(북미: 906394416454, 유럽: 336853085554, 극동: 774466381866)

4단계: IAM 정책 연결

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "execute-api:Invoke"
      ],
      "Resource": [
        "arn:aws:execute-api:*:*:*/prod/*/sellingpartnerapi/*"
      ]
    }
  ]
}

역할명은 SellingPartnerApiRole 등으로 지정하고 ARN을 기록하세요.

5단계: IAM 역할을 애플리케이션에 연결

셀러 센트럴 → 앱 개발 > 애플리케이션 선택 → 편집 → IAM 역할 ARN 입력 → 저장

몇 분 후 "연결됨" 상태 확인

OAuth 2.0 인증 흐름

SP-API OAuth 전체 흐름

1. 셀러가 앱에서 인증 클릭
2. 아마존 인증 URL 리다이렉트
3. 셀러 로그인 및 권한 승인
4. 인증 코드로 콜백
5. 코드 → LWA 토큰 교환
6. LWA 토큰 → SP-API 액세스 토큰 교환
7. 액세스 토큰으로 API 호출(SigV4 서명)
8. 토큰 만료(1시간)시 자동 새로고침

6단계: 인증 URL 생성

const generateAuthUrl = (clientId, redirectUri, state) => {
  const baseUrl = 'https://www.amazon.com/sp/apps/oauth/authorize';
  const params = new URLSearchParams({
    application_id: process.env.AMAZON_APPLICATION_ID,
    client_id: clientId,
    redirect_uri: redirectUri,
    state: state, // CSRF 방지
    scope: 'sellingpartnerapi::notifications'
  });
  return `${baseUrl}?${params.toString()}`;
};

// 사용 예시
const authUrl = generateAuthUrl(
  process.env.AMAZON_CLIENT_ID,
  'https://your-app.com/callback',
  crypto.randomBytes(16).toString('hex')
);
console.log(`사용자를 다음으로 리다이렉션: ${authUrl}`);

필요한 OAuth 범위

범위	설명	사용 사례
sellingpartnerapi::notifications	알림 수신	웹훅 구독
sellingpartnerapi::migration	MWS 마이그레이션	레거시 통합

참고: 대부분 권한은 IAM 정책에서 제어

7단계: 인증 코드 → LWA 토큰 교환

const exchangeCodeForLwaToken = async (code, redirectUri) => {
  const response = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: process.env.AMAZON_CLIENT_ID,
      client_secret: process.env.AMAZON_CLIENT_SECRET,
      redirect_uri: redirectUri,
      code: code
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`LWA Token Error: ${error.error_description}`);
  }
  return await response.json();
};

8단계: LWA 토큰 → SP-API 자격 증명

const assumeRole = async (lwaAccessToken) => {
  const response = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.AMAZON_CLIENT_ID,
      client_secret: process.env.AMAZON_CLIENT_SECRET,
      scope: 'sellingpartnerapi::notifications'
    })
  });
  const data = await response.json();
  // STS AssumeRole 호출 생략(자세한 구현은 AWS SDK 권장)
  return data;
};

9단계: 토큰 새로고침 구현

const refreshLwaToken = async (refreshToken) => {
  const response = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: process.env.AMAZON_CLIENT_ID,
      client_secret: process.env.AMAZON_CLIENT_SECRET,
      refresh_token: refreshToken
    })
  });
  const data = await response.json();
  return data;
};

AWS SigV4 요청 서명

SigV4 서명 직접 구현

const crypto = require('crypto');

class SigV4Signer {
  constructor(accessKey, secretKey, region, service = 'execute-api') {
    this.accessKey = accessKey;
    this.secretKey = secretKey;
    this.region = region;
    this.service = service;
  }
  // ... (중략, 위 원문 코드 동일)
}

AWS SDK로 서명 간소화

const { SignatureV4 } = require('@aws-sdk/signature-v4');
const { Sha256 } = require('@aws-crypto/sha256-js');

const signer = new SignatureV4({
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
  },
  region: 'us-east-1',
  service: 'execute-api',
  sha256: Sha256
});

const makeSpApiRequest = async (method, endpoint, accessToken, body = null) => {
  // ... (원문 코드와 동일)
};

주문 API

주문 검색

const getOrders = async (accessToken, options = {}) => {
  // ... (원문 코드와 동일)
};

주문 항목, 배송 처리 등은 위의 코드 참고

재고 API

재고 요약 가져오기

const getInventorySummaries = async (accessToken, options = {}) => {
  // ... (원문 코드와 동일)
};

FBA 입고 계획 생성

const createInboundShipmentPlan = async (accessToken, shipmentData) => {
  // ... (원문 코드와 동일)
};

상품 목록 API

상품 목록 조회/수정/삭제 실전 예제

const getListings = async (accessToken, options = {}) => {
  // ... (원문 코드와 동일)
};

보고서 API

보고서 생성 및 다운로드

const createReport = async (accessToken, reportType, dateRange) => {
  // ... (원문 코드와 동일)
};

알림 API

SNS 기반 실시간 이벤트 구독

const createSubscription = async (accessToken, subscriptionData) => {
  // ... (원문 코드와 동일)
};

호출 속도 제한 및 처리

엔드포인트별 속도 제한

엔드포인트 카테고리	호출 속도 제한	버스트 제한
주문	초당 10회	20
주문 항목	초당 5회	10
재고	초당 2회	5
상품 목록	초당 10회	20
보고서	초당 0.5회	1
알림	초당 1회	2
FBA 입고	초당 2회	5

x-amzn-RateLimit-Limit 헤더로 현재 제한 확인

지수 백오프/큐잉 예제

const makeRateLimitedRequest = async (method, endpoint, accessToken, body = null, maxRetries = 5) => {
  // ... (원문 코드와 동일)
};

class RateLimitedQueue {
  // ... (원문 코드와 동일)
}

보안 모범 사례

자격 증명/토큰 관리

• 자격 증명은 환경 변수/시크릿 관리자로 관리
• 저장 토큰은 AES-256 암호화
• 접근 제어, 감사 로깅, 자동 로테이션 구현

class TokenStore {
  // ... (원문 코드와 동일)
}

IAM 최소 권한 정책

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SPAPIOrdersAccess",
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:*:*:*/prod/*/sellingpartnerapi/orders/*"
    },
    {
      "Sid": "SPAPIInventoryAccess",
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:*:*:*/prod/*/sellingpartnerapi/fba/inventory/*"
    }
  ]
}

Apidog를 사용한 SP-API 통합 테스트

Apidog로 SP-API 테스트 자동화

1. SP-API OpenAPI 사양 가져오기

   • 아마존 공식 리포지토리에서 사양 다운로드
   • Apidog 신규 프로젝트에 가져오기

2. 환경 변수 구성
   

   기본 URL (샌드박스): https://sandbox.sellingpartnerapi-na.amazon.com
   기본 URL (프로덕션): https://sellingpartnerapi-na.amazon.com
   LWA 액세스 토큰: {{lwa_access_token}}
   AWS 액세스 키: {{aws_access_key}}
   AWS 시크릿 키: {{aws_secret_key}}
   지역: us-east-1

1. 사전 요청 스크립트로 SigV4 자동화

   // Apidog 사전 요청 스크립트 예시
   // ... (원문 코드와 동일)

1. 테스트 시나리오 생성

   // 주문 데이터 가져오기, 응답 검증, 변수 저장 등
   // ... (원문 코드와 동일)

1. 스마트 모의 응답 활용

   // GetOrders에 대한 예시 모의 응답
   {
     "payload": {
       "orders": [
         {
           "amazon_order_id": "112-{{randomNumber}}-{{randomNumber}}",
           "order_status": "Unshipped",
           "purchase_date": "{{now}}",
           "order_total": {
             "currency_code": "USD",
             "amount": "{{randomFloat 10 500}}"
           }
         }
       ],
       "next_token": null
     }
   }

---

위 단계를 따라가면 실전 아마존 SP-API 자동화 통합 및 테스트를 빠르고 견고하게 구현할 수 있습니다.

복잡한 인증, 요청 서명, 속도 제한, 보안까지 모든 과정을 코드와 예시로 직접 적용해보세요.

지금 Apidog로 SP-API 개발 생산성을 극대화하세요.