codeyogi911/amazon-seller-india

Amazon Seller India — SP-API 에이전트 스킬

이 스킬을 사용해야 하는 경우

사용자가 다음을 요청할 때 이 스킬을 사용하세요:

• Amazon SP-API 인증(LWA OAuth, 리프레시 토큰, 액세스 토큰) 설정 또는 문제 해결
• Amazon Seller Central India에 비공개 개발자로 등록
• 비공개 SP-API 애플리케이션 자체 승인
• 인도 마켓플레이스에 대한 Amazon Selling Partner API 호출
• SP-API를 통한 주문, 재고, 리스팅, 가격 또는 물류 관리
• 보고서 풀링(정산, GST/세금, 재고, 주문, FBA, 성과)
• 피드 제출(리스팅, 가격, 주문 처리, FBA 입고)
• Amazon 금융, 지불 또는 정산 조정 작업
• PII 민감 작업을 위한 제한된 데이터 토큰(RDT) 처리
• FBA 입고 배송, Easy Ship 또는 외부 물류 관리
• 카탈로그 항목, 제품 유형 또는 브랜드 분석 검색
• SP-API 알림 또는 구독 설정
• Amazon Seller India 데이터를 Zoho Books/Inventory 또는 기타 회계 시스템과 통합

인도 마켓플레이스 상수

매개변수	값
마켓플레이스 ID	A21TJRUUN4KGV
국가 코드	IN
SP-API 엔드포인트	https://sellingpartnerapi-eu.amazon.com
AWS 리전	eu-west-1
Seller Central URL	https://sellercentral.amazon.in
LWA 토큰 엔드포인트	https://api.amazon.com/auth/o2/token

인도는 SP-API에서 유럽 판매 지역에 속합니다. 모든 API 호출은 sellingpartnerapi-eu.amazon.com으로 전송됩니다.

빠른 참조

• 인증 설정(최초 등록, 개발자 프로필, 자체 승인, 자격 증명 수집)의 경우: references/auth-setup-guide.md 로드
• 전체 API 작업 카탈로그(모든 API, 엔드포인트, 보고서 유형, 피드 유형, 역할)의 경우: references/api-operations-catalog.md 로드
• 즉시 사용 가능한 스크립트(토큰 교환, API 호출)의 경우: scripts/ 디렉토리 참조

지침

1단계: 자격 증명 수집

API 호출을 하기 전에 사용자로부터 다음 자격 증명을 수집하세요:

1. LWA 클라이언트 ID — amzn1.application-oa2-client.xxxxx (Seller Central → Apps & Services → Develop Apps → LWA Credentials)
2. LWA 클라이언트 시크릿 — 클라이언트 ID와 쌍을 이루는 시크릿
3. LWA 리프레시 토큰 — 자체 승인 중 획득(장기 자격 증명)

사용자가 아직 개발자 프로필이나 애플리케이션을 설정하지 않은 경우 전체 인증 설정 과정을 안내하세요. 단계별 가이드는 references/auth-setup-guide.md를 로드하세요.

2단계: 리프레시 토큰을 액세스 토큰으로 교환

모든 SP-API 호출에는 단기 액세스 토큰(3600초/1시간 후 만료)이 필요합니다.

curl -X POST "https://api.amazon.com/auth/o2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=${REFRESH_TOKEN}" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}"

응답:

{
  "access_token": "Atza|IQEBLjAs...",
  "token_type": "bearer",
  "expires_in": 3600
}

재사용 가능한 Python 구현은 scripts/get_access_token.py를 사용하세요.

3단계: SP-API 호출

모든 인도 마켓플레이스 호출은 다음을 사용합니다:

• 엔드포인트: https://sellingpartnerapi-eu.amazon.com
• 마켓플레이스 ID 쿼리 매개변수: marketplaceIds=A21TJRUUN4KGV
• 헤더:
  • x-amz-access-token: {access_token}
  • user-agent: {AppName}/{Version} (Language=Python/3.x; Platform=Linux)

예시 — 주문 가져오기:

curl -X GET "https://sellingpartnerapi-eu.amazon.com/orders/v0/orders?MarketplaceIds=A21TJRUUN4KGV&CreatedAfter=2026-01-01T00:00:00Z" \
  -H "x-amz-access-token: ${ACCESS_TOKEN}" \
  -H "user-agent: MyApp/1.0 (Language=Python/3.10)"

4단계: 제한된 데이터 처리 (PII)

일부 작업은 PII(구매자 이름, 주소, 전화번호)를 반환합니다. 이러한 작업에는 일반 액세스 토큰 대신 **제한된 데이터 토큰(RDT)**이 필요합니다.

RDT 가져오기:

curl -X POST "https://sellingpartnerapi-eu.amazon.com/tokens/2021-03-01/restrictedDataToken" \
  -H "x-amz-access-token: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "restrictedResources": [
      {
        "method": "GET",
        "path": "/orders/v0/orders/{orderId}",
        "dataElements": ["buyerInfo", "shippingAddress"]
      }
    ]
  }'

그런 다음 반환된 restrictedDataToken 값을 제한된 호출의 x-amz-access-token 헤더에 사용하세요.

제한된 작업에는 다음이 포함됩니다:

• Orders API: getOrders, getOrder, getOrderItems, getOrderAddress, getOrderBuyerInfo, confirmShipment
• Merchant Fulfillment API: getShipment, createShipment
• Easy Ship API: createScheduledPackageBulk
• PII가 포함된 보고서(배송 보고서, 세금 보고서)

5단계: 일반적인 워크플로우

정산 보고서 풀링 (Zoho Books 조정용)

POST /reports/2021-06-30/reports
{
  "reportType": "GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2",
  "marketplaceIds": ["A21TJRUUN4KGV"]
}

그런 다음 상태가 DONE이 될 때까지 GET /reports/2021-06-30/reports/{reportId}를 폴링하고, reportDocumentId를 통해 다운로드합니다.

GST 보고서 풀링 (인도 전용)

보고서	reportType 값	필수 역할
GST MTR B2B	GST_MTR_B2B	세금 송금 (제한됨)
GST MTR B2C	GST_MTR_B2C	세금 송금 (제한됨)
GST 재고 이동	GST_MTR_STOCK_TRANSFER_REPORT	세금 송금 (제한됨)
온디맨드 GST B2B	GET_GST_MTR_B2B_CUSTOM	세금 청구 (제한됨)
온디맨드 GST B2C	GET_GST_MTR_B2C_CUSTOM	세금 청구 (제한됨)
온디맨드 재고 이동	GET_GST_STR_ADHOC	Amazon 물류

재고 업데이트

Listings Items API를 사용하거나 피드를 제출하세요:

POST /feeds/2021-06-30/feeds
{
  "feedType": "JSON_LISTINGS_FEED",
  "marketplaceIds": ["A21TJRUUN4KGV"],
  "inputFeedDocumentId": "{feedDocumentId}"
}

가격 업데이트

POST /feeds/2021-06-30/feeds
{
  "feedType": "JSON_LISTINGS_FEED",
  "marketplaceIds": ["A21TJRUUN4KGV"],
  "inputFeedDocumentId": "{feedDocumentId}"
}

개별 가격 업데이트에는 Listings Items API patchListingsItem을 사용하세요.

오류 처리

HTTP 코드	의미	조치
400	잘못된 요청 / 잘못된 매개변수	쿼리 매개변수, 마켓플레이스 ID, 날짜 형식 확인
401	잘못되었거나 만료된 액세스 토큰	리프레시 토큰을 새 액세스 토큰으로 재교환
403	역할 누락 또는 권한 없음	개발자 프로필 역할 확인; 추가 역할 요청 필요할 수 있음
404	리소스를 찾을 수 없음	주문 ID, ASIN, SKU 존재 여부 확인
429	속도 제한 초과	백오프 후 지수 백오프로 재시도
500/503	Amazon 서버 오류	지수 백오프로 재시도 (최대 3회)

속도 제한

SP-API는 작업별 속도 제한을 적용합니다. 대량 작업의 주요 제한:

• getOrders: 0.0167 요청/초 (1분당 버스트 20)
• getOrder: 0.5 요청/초 (버스트 30)
• getOrderItems: 0.5 요청/초 (버스트 30)
• createReport: 0.0167 요청/초 (1분당 버스트 15)
• getReport: 2 요청/초 (버스트 15)
• Catalog Items searchCatalogItems: 2 요청/초 (버스트 2)
• Listings patchListingsItem: 5 요청/초 (버스트 10)
• Feeds createFeed: 0.0083 요청/초 (2분당 1회, 버스트 15)

429 응답에 대해 항상 지수 백오프를 구현하세요.

중요 참고 사항

• AWS IAM/STS 불필요: 2023년 이후 SP-API는 더 이상 AWS Signature V4 서명 또는 IAM 역할 가정이 필요하지 않습니다. LWA OAuth 토큰만 필요합니다.
• 권한 없는 작업: 일부 작업(예: Notifications API 구독)은 refresh_token 대신 client_credentials 권한 부여를 사용합니다. scope=sellingpartnerapi::notifications와 함께 grant_type=client_credentials를 사용하세요.
• 샌드박스 테스트: SP-API는 테스트를 위한 정적 및 동적 샌드박스 환경을 제공합니다. 정적 샌드박스의 경우 x-amzn-sandbox: true 헤더를 사용하거나 샌드박스 엔드포인트 패턴을 사용하세요.
• 인도 시간대: Amazon India는 IST(UTC+5:30)로 운영됩니다. 주문 날짜와 보고서 날짜는 UTC 기준입니다. 필요에 따라 변환하세요.
• 정산 주기: Amazon India는 일반적으로 7일마다 정산합니다. 정산 보고서에는 수수료, 환불 및 순 지불액을 포함한 모든 거래 수준 세부 정보가 포함됩니다.