Amazon Seller India — Skill de Agente SP-API

Quando Usar Esta Skill

Use esta skill quando o usuário solicitar:

Configurar ou solucionar problemas de autenticação da Amazon SP-API (LWA OAuth, tokens de refresh, tokens de acesso)
Registrar-se como desenvolvedor privado no Seller Central India
Autoautorizar uma aplicação SP-API privada
Fazer qualquer chamada à API Selling Partner para o marketplace da Índia
Gerenciar pedidos, inventário, listagens, preços ou fulfillment via SP-API
Extrair relatórios (liquidação, GST/impostos, inventário, pedidos, FBA, desempenho)
Enviar feeds (listagens, preços, fulfillment de pedidos, entrada FBA)
Trabalhar com finanças, pagamentos ou reconciliação de liquidações da Amazon
Lidar com Restricted Data Tokens (RDT) para operações com dados sensíveis (PII)
Gerenciar remessas de entrada FBA, Easy Ship ou fulfillment externo
Recuperar itens do catálogo, tipos de produto ou análises de marca
Configurar notificações ou assinaturas SP-API
Integrar dados do Amazon Seller India com Zoho Books/Inventory ou outros sistemas contábeis

Constantes do Marketplace da Índia

Parâmetro	Valor
ID do Marketplace	`A21TJRUUN4KGV`
Código do País	`IN`
Endpoint SP-API	`https://sellingpartnerapi-eu.amazon.com`
Região AWS	`eu-west-1`
URL do Seller Central	`https://sellercentral.amazon.in`
Endpoint de Token LWA	`https://api.amazon.com/auth/o2/token`

A Índia faz parte da região de venda Europa na SP-API. Todas as chamadas de API vão para sellingpartnerapi-eu.amazon.com.

Referência Rápida

Para configuração de autenticação (primeiro registro, perfil do desenvolvedor, autoautorização, coleta de credenciais): Carregue references/auth-setup-guide.md
Para catálogo completo de operações da API (todas as APIs, endpoints, tipos de relatório, tipos de feed, papéis): Carregue references/api-operations-catalog.md
Para scripts prontos para uso (troca de token, chamadas de API): Veja o diretório scripts/

Instruções

Passo 1: Coleta de Credenciais

Antes de fazer qualquer chamada de API, colete estas credenciais do usuário:

LWA Client ID — amzn1.application-oa2-client.xxxxx (no Seller Central → Apps & Services → Develop Apps → LWA Credentials)
LWA Client Secret — o segredo correspondente ao Client ID
LWA Refresh Token — obtido durante a autoautorização (credencial de longa duração)

Se o usuário ainda não configurou seu perfil de desenvolvedor ou aplicação, guie-o pelo processo completo de configuração de autenticação. Carregue references/auth-setup-guide.md para o guia passo a passo.

Passo 2: Trocar Refresh Token por Access Token

Toda chamada SP-API requer um token de acesso de curta duração (expira em 3600 segundos / 1 hora).

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}"

Resposta:

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

Use scripts/get_access_token.py para uma implementação reutilizável em Python.

Passo 3: Fazer Chamadas SP-API

Todas as chamadas do marketplace da Índia usam:

Endpoint: https://sellingpartnerapi-eu.amazon.com
Parâmetro de consulta Marketplace ID: marketplaceIds=A21TJRUUN4KGV
Cabeçalhos:
- x-amz-access-token: {access_token}
- user-agent: {AppName}/{Version} (Language=Python/3.x; Platform=Linux)

Exemplo — Obter Pedidos:

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)"

Passo 4: Lidar com Dados Restritos (PII)

Algumas operações retornam PII (nome do comprador, endereço, telefone). Elas exigem um Restricted Data Token (RDT) em vez do token de acesso normal.

Obter um 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"]
      }
    ]
  }'

Depois use o valor restrictedDataToken retornado no cabeçalho x-amz-access-token para a chamada restrita.

Operações restritas incluem:

Orders API: getOrders, getOrder, getOrderItems, getOrderAddress, getOrderBuyerInfo, confirmShipment
Merchant Fulfillment API: getShipment, createShipment
Easy Ship API: createScheduledPackageBulk
Relatórios com PII (relatórios de remessa, relatórios fiscais)

Passo 5: Fluxos de Trabalho Comuns

Extrair Relatório de Liquidação (para reconciliação no Zoho Books)

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

Depois consulte GET /reports/2021-06-30/reports/{reportId} até o status ser DONE, então baixe via reportDocumentId.

Extrair Relatórios GST (específicos da Índia)

Relatório	Valor reportType	Papel Necessário
GST MTR B2B	`GST_MTR_B2B`	Tax Remittance (Restrito)
GST MTR B2C	`GST_MTR_B2C`	Tax Remittance (Restrito)
Transferência de Estoque GST	`GST_MTR_STOCK_TRANSFER_REPORT`	Tax Remittance (Restrito)
GST B2B Sob Demanda	`GET_GST_MTR_B2B_CUSTOM`	Tax Invoicing (Restrito)
GST B2C Sob Demanda	`GET_GST_MTR_B2C_CUSTOM`	Tax Invoicing (Restrito)
Transferência de Estoque Sob Demanda	`GET_GST_STR_ADHOC`	Amazon Fulfillment

Atualizar Inventário

Use a API Listings Items ou envie um feed:

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

Atualizar Preços

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

Use o endpoint patchListingsItem da API Listings Items para atualizações individuais de preço.

Tratamento de Erros

Código HTTP	Significado	Ação
400	Requisição inválida / parâmetros inválidos	Verifique parâmetros de consulta, ID do marketplace, formatos de data
401	Token de acesso inválido ou expirado	Troque novamente o refresh token por um novo access token
403	Papel ausente ou não autorizado	Verifique os papéis no perfil do desenvolvedor; pode ser necessário solicitar mais papéis
404	Recurso não encontrado	Verifique se o ID do pedido, ASIN, SKU existe
429	Limite de taxa excedido	Aguarde e tente novamente com backoff exponencial
500/503	Erro do servidor Amazon	Tente novamente com backoff exponencial (máx. 3 tentativas)

Limites de Taxa

A SP-API impõe limites de taxa por operação. Limites principais para operações de alto volume:

getOrders: 0.0167 requests/sec (rajada de 1 por minuto, máximo 20)
getOrder: 0.5 requests/sec (rajada de 30)
getOrderItems: 0.5 requests/sec (rajada de 30)
createReport: 0.0167 requests/sec (rajada de 1 por minuto, máximo 15)
getReport: 2 requests/sec (rajada de 15)
Catalog Items searchCatalogItems: 2 requests/sec (rajada de 2)
Listings patchListingsItem: 5 requests/sec (rajada de 10)
Feeds createFeed: 0.0083 requests/sec (rajada de 1 a cada 2 minutos, máximo 15)

Sempre implemente backoff exponencial para respostas 429.

Notas Importantes

Nenhum AWS IAM/STS necessário: Desde 2023, a SP-API não exige mais assinatura AWS Signature V4 ou assunção de papel IAM. Apenas tokens LWA OAuth são necessários.
Operações sem concessão (grantless): Algumas operações (ex.: assinaturas da Notifications API) usam a concessão client_credentials em vez de refresh_token. Use scope=sellingpartnerapi::notifications com grant_type=client_credentials.
Testes em Sandbox: A SP-API oferece ambientes sandbox estáticos e dinâmicos para testes. Use o cabeçalho x-amzn-sandbox: true (sandbox estático) ou padrões de endpoint sandbox.
Fuso horário da Índia: A Amazon India opera no IST (UTC+5:30). Datas de pedidos e relatórios estão em UTC; converta conforme necessário.
Ciclo de liquidação: A Amazon India normalmente liquida a cada 7 dias. Os relatórios de liquidação contêm todos os detalhes no nível de transação, incluindo taxas, reembolsos e pagamento líquido.

codeyogi911/amazon-seller-india

O que é amazon-seller-india?

Perguntar na sua IA favorita

Documentação