Guia de uso
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 exemploorders/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:
- getOrders
- getOrder
- getShippingLabels
- getPackingSlips
- getCustomerInvoices
- getShipment
- cancelShipment
- cancelShipmentOld
- createShipment
- getOrders
- getOrder
- getOrderItems
- 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.
- 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á:
- Autorização do parceiro de vendas para o qual você está fazendo chamadas.
Para mais informações de como Registrar desenvolvedor no SellerCentral.
1. Obter um token RDT
Chame a operação createRestrictedDataToken para obter um RDT.
Valor | Descrição |
---|---|
restrictedResources Obrigatório Tipo: RestrictedResource | Modelo de recurso restrito. Máximo: 50 |
{
"restrictedResources": [
{
"method": "GET",
"path": "/orders/v0/orders",
"dataElements": ["buyerInfo", "shippingAddress"]
}
]
}
Exemplo de resposta com sucesso:
Valor | Descriçã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á:
- Autorização do parceiro de vendas para o qual você está fazendo chamadas.
Para mais informações de como Registrar desenvolvedor no SellerCentral.
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.
-
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 -
Dos pedidos que são devolvidos, identifique aquele para o qual deseja informações do item do pedido.
-
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.
Valor | Descrição |
---|---|
restrictedResources Obrigatório Tipo: RestrictedResource | Modelo de recurso restrito. Máximo: 50 |
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"]
}
]
}
Exemplo de resposta com sucesso:
Valor | Descriçã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:
Valor | Descrição |
---|---|
restrictedResources Obrigatório Tipo: RestrictedResource | Modelo de recurso restrito. Máximo: 50 |
{
"restrictedResources": [
{
"method": "GET",
"path": "/mfn/v0/shipments/{shipmentId}"
}
]
}
Exemplo de resposta com sucesso:
Valor | Descriçã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 almost 2 years ago