Guias de uso
Documentação GlobalDeveloper HubSuporteStatus da API

Guia de uso

Suggest Edits

Introdução a API

O que é a API de tokens?

A Selling Partner API for Tokens (Tokens API) fornece uma maneira segura de acessar as informações de identificação pessoal (PII) de um cliente. Você pode chamar a API de tokens para obter um token de dados restrito (RDT) para um ou mais recursos restritos que você especificar. O RDT autoriza você a fazer chamadas subsequentes para as operações restritas que os recursos restritos representam. Para obter as definições, consulte Terminologia.

Ao chamar uma operação restrita, você inclui um RDT no cabeçalho x-amz-access-token. Isso está em contraste com outras operações SP-API, onde você inclui um token de acesso LWA no cabeçalho x-amz-access-token. Para obter mais informações, consulte a Etapa 3. Adicionar cabeçalhos ao URI no Selling Partner API Developer Guide.

Termos usados

  • Restricted Data Token (RDT): Um token de acesso de curta duração que autoriza você a chamar operações restritas.

  • Restricted operation: Uma operação que retorna dados restritos, como informações de identificação pessoal (PII). Você precisa de um RDT para chamar uma operação restrita.
    Consulte Operações restritas.

  • Restricted resource: Um método e caminho HTTP que representa uma operação restrita.

  • Restricted report type: A report type that contains PII. See Restricted report types

  • Specific path: Um caminho em um recurso restrito que contém um pedido específico ou identificador de envio. Por exemplo, orders/v0/orders/902-3159896-1390916/address

  • Generic path: Um caminho em um recurso restrito que contém um identificador genérico, tal como {orderId} ou {shipmentId}. Por exemplo orders/v0/orders/{orderId}/address

Operações restritas

As operações restritas retornam informações de identificação pessoal (PII) dos clientes.
Você precisa de um RDT para chamar uma operação restrita.

Lista de operações restritas

Aqui está uma lista de operações restritas, agrupadas por API:

Direct Fulfillment Orders API

  • getOrders
  • getOrder

Direct Fulfillment Shipping API

  • getShippingLabels
  • getPackingSlips
  • getCustomerInvoices

Orders API

  • getShipment
  • cancelShipment
  • cancelShipmentOld
  • createShipment

FBA onsite

  • getOrders
  • getOrder
  • getOrderItems

Merchant Fulfillment API

  • submitInvoice
  • getInvoiceStatus
  • getShipmentDetails

❗️

Importante

Recomendamos o uso das operações getOrder, getOrders e getOrderItems para recuperar PII usando o RDT porque as operações getOrderBuyerInfo, getOrderAddress e getOrderItemsBuyerInfo estão programadas para descontinuação em 12 de janeiro de 2022.

Reports API

  • getReportDocument

📘

Nota

A operação getReportDocument é considerada uma operação restrita apenas em alguns tipos de relatórios especificados. Veja a lista de relatórios restritos.

Ao chamar a operação createRestrictedDataToken para obter um RDT para a operação getReportDocument, o recurso restrito especificado pode conter apenas um caminho específico, não um caminho genérico, veja Terminologia.

Tipos de relatórios restritos

Os tipos de relatórios restritos contêm PII.

Ao especificar um tipo de relatório restrito em uma chamada para a operação getReportDocument, você deve passar um RDT na chamada.

Aqui está uma lista de tipos de relatórios restritos:

  • GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING
  • GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX
  • GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING
  • GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING
  • GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING
  • GET_FLAT_FILE_ORDER_REPORT_DATA_TAX
  • GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_TAX
  • GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_INVOICING
  • GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_SHIPPING
  • GET_ORDER_REPORT_DATA_INVOICING
  • GET_ORDER_REPORT_DATA_TAX
  • GET_ORDER_REPORT_DATA_SHIPPING
  • GET_EASYSHIP_DOCUMENTS
  • GET_GST_MTR_B2B_CUSTOM
  • GET_VAT_TRANSACTION_DATA
  • SC_VAT_TAX_REPORT

Informações de endereço de entrega e comprador do pedido

Tutorial

Você pode usar um RDT para obter informações do comprador, do endereço de entrega ou ambos, para pedidos em massa.

Os valores de dataElements que você especifica com a operação createRestrictedDataToken determinam o tipo de dados que o RDT autoriza seu aplicativo a acessar. Neste tutorial, solicitamos um RDT que autoriza o acesso às informações do comprador e do endereço de entrega.

Pré-requisitos

Para concluir este tutorial, você precisará:

1. Obter um token RDT

Chame a operação createRestrictedDataToken para obter um RDT.

ValorDescrição
restrictedResources

Obrigatório

Tipo: RestrictedResource		Modelo de recurso restrito. Máximo: 50

Exemplo de chamada 

{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/orders/v0/orders",
      "dataElements": ["buyerInfo", "shippingAddress"]
    }
  ]
}

Resposta

Exemplo de resposta com sucesso:

ValorDescrição
restrictedDataToken

Tipo: String		Um Token de Dados Restritos (RDT).
Este é um token de acesso de curta duração que autoriza você a chamar as operações restritas representadas pelos recursos restritos que você especificou. Passe o valor RDT no cabeçalho x-amz-access-token ao fazer chamadas subsequentes para as operações restritas.
expiresIn

Tipo: Integer		A vida útil do RDT, em segundos.
{
  "payload": {
    "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
    "expiresIn": 3600
  }
}

Salve o valor do restrictedDataToken (RDT) para usar em 2. Incluir RDT na chamada da getOrders.

2. Incluir RDT na chamada da getOrders

Faça a chamada em getOrders da API de pedidos, especificando os parâmetros apropriados para filtrar os pedidos que você deseja.

Certifique-se de incluir o RDT (que você salvou na Etapa 1. Obtenha um token RDT no cabeçalho x-amz-access-token de sua chamada para getOrders.

Como você especificou buyerInfo e shippingAddress na Etapa 1. Obtenha um token RDT, sua chamada para getOrders retorna as informações do comprador e do endereço de entrega para cada pedido.

Se você tivesse especificado apenas buyerInfo na Etapa 1, getOrders retornaria apenas informações do comprador para cada pedido.

Se você tivesse especificado apenas shippingAddress na Etapa 1, getOrders retornaria apenas informações de endereço de entrega para cada pedido.

Informações do comprador nos itens do pedido

Tutorial

Você pode usar um RDT para obter informações do comprador para os itens do pedido em um pedido que você especificar.

Neste fluxo de trabalho, você especifica dataElements = buyerInfo para indicar que o RDT irá autorizar seu aplicativo a acessar as informações do comprador para os itens de pedido especificados.

Pré-requisitos

Para concluir este tutorial, você precisará:

1. Obter um order ID

Você precisa de um ID de pedido para fazer a chamada passando o a informações do item do pedido. Esse ID também será usado para obter um RDT que autoriza seu aplicativo a acessar as informações do comprador para os itens do pedido, pode usar a chamada getOrders da API de pedidos para obter uma lista de pedidos, obtendo assim o ID necessário.

  1. Faça a chamada em getOrders da API de pedidos, especificando os parâmetros apropriados para filtrar o pedido que você deseja.
    A operação retorna pedidos que correspondem à sua solicitação. Cada pedido inclui um ID de pedido

  2. Dos pedidos que são devolvidos, identifique aquele para o qual deseja informações do item do pedido.

  3. Salve a ID do pedido que deseja para usar na Etapa 2. Obtenha um token RDT e a Etapa 3. Inclua o RDT na chamada de getOrderItems.

2. Obter um token RDT

Chame a operação createRestrictedDataToken para obter um RDT.

ValorDescrição
restrictedResources

Obrigatório

Tipo: RestrictedResource		Modelo de recurso restrito. Máximo: 50

Exemplo de chamada 

Sem RDT
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/orders/v0/orders",
      "dataElements": ["buyerInfo", "shippingAddress"]
    }
  ]
}

Com RDT
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/orders/v0/orders/123-1234567-1234567/orderItems",
      "dataElements": ["buyerInfo"]
    }
  ]
}

Resposta

Exemplo de resposta com sucesso:

ValorDescrição
restrictedDataToken

Tipo: String		Um Token de Dados Restritos (RDT).
Este é um token de acesso de curta duração que autoriza você a chamar as operações restritas representadas pelos recursos restritos que você especificou. Passe o valor RDT no cabeçalho x-amz-access-token ao fazer chamadas subsequentes para as operações restritas.
expiresIn

Tipo: Integer		A vida útil do RDT, em segundos.
{
  "payload": {
    "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
    "expiresIn": 3600
  }
}

Salve o valor do restrictedDataToken (RDT) para usar em 2. Incluir RDT na chamada da getOrders.

3. Inclua o RDT na chamada de getOrderItems

Chame a operação getOrderItems da API de pedidos, especificando o ID do pedido que você identificou na Etapa 1. Obtenha um ID do pedido. Certifique-se de incluir o RDT da Etapa 1 no cabeçalho x-amz-access-token de sua chamada para getOrderItems.

RDT para vários envios

Você pode obter um RDT que fornece autorização para obter detalhes de remessa para qualquer remessa de um parceiro de vendas.

Pré-requisitos

Para concluir este tutorial, você precisará:

  • Autorização do parceiro de vendas para o qual você está fazendo chamadas.
    Para mais informações de como Registrar desenvolvedor no SellerCentral.

  • IDs de envio para as remessas cujos detalhes você deseja obter.

1. Obter um token RDT

Faça a requisição para createRestrictedDataToken, passando os seguintes parâmetros:

ValorDescrição
restrictedResources

Obrigatório

Tipo: RestrictedResource		Modelo de recurso restrito.

Máximo: 50

Exemplo de chamada 

{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/mfn/v0/shipments/{shipmentId}"
    }
  ]
}

Resposta

Exemplo de resposta com sucesso:

ValorDescrição
restrictedDataToken

Tipo: String		Um Token de Dados Restritos (RDT).
Este é um token de acesso de curta duração que autoriza você a chamar as operações restritas representadas pelos recursos restritos que você especificou. Passe o valor RDT no cabeçalho x-amz-access-token ao fazer chamadas subsequentes para as operações restritas.
expiresIn

Tipo: Integer		A vida útil do RDT, em segundos.
{
  "payload": {
    "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
    "expiresIn": 3600
  }
}

Salve o valor do restrictedDataToken (RDT) para usar em 2. Inclua o RDT na chamada getShipment.

2. Inclua o RDT na chamada getShipment

Faça a requisição em getShipment da API Merchant Fulfillment, usando o caminho genérico que você especificou na Etapa 1. Obter um token RDT e substitua {shipmentId} por um ID de remessa do parceiro de vendas. Por exemplo, /mfn/v0/shipments/FBA1234ABC5D.
Certifique-se de incluir o RDT da Etapa 1 no cabeçalho x-amz-access-token de sua chamada para getShipment. Você pode usar o RDT para qualquer uma das IDs de remessa do parceiro de vendas.

Updated about 2 years ago