Implementando Relatórios (Python SDK)

Com o intuito de implementar um caso de uso prático e simples para a utilização de relatórios na SP-API segue um exemplo ilustrado em Python nesta seção.

📘
Referência SP-API
Esta documentação utiliza a referência original da Selling Partner API do caso de uso para relatórios

1. PYTHON-AMAZON-SP-API (Instalando o SDK)

O SDK utilizado para a geração de relatórios foi o PYTHON-AMAZON-SP-API que pode ser acessado no link abaixo:

python-amazon-sp-api.readthedocs.io

Welcome to PYTHON-AMAZON-SP-API's documentation! - PYTHON-AMAZON-SP-API documentation

Como a implementação utilizou esta biblioteca em Python, sua utilização foi através do IDE Pycharm que pode ser encontrado no link abaixo:

jetbrains.com

Baixar PyCharm: o IDE Python da JetBrains para desenvolvedores profissionais

Após realizar a instalação do Pycharm é necessário realizar os seguintes passos:

Criar um projeto novo em Python
Instalar a biblioteca do SDK (Código abaixo) no projeto

pip install python-amazon-sp-api

1315 — Executando a linha de código em um projeto Python no Pycharm

2. Configurando o Ambiente

Existem algumas maneiras de configurar credenciais ao utilizar a PYTHON-AMAZON-SP-AP: deixando no próprio código, em variáveis de ambiente ou em um arquivo separado. Independentemente de qual escolha seja feita, é necessário configurar todos os parâmetros abaixo (arquivo-exemplo):

refresh_token: 'Atzr|IwEasdBIdMAbcPcKdGFHfasdYTSu6JUTqwXTTy5PoWA-rkrdmatnkhqnUSwdGjJoe2StpYTmn70bThHBeWCuVQ2xLFLhYePjQpgEzWqQndX9akbZn9D2KNKryrm5NZhdegR8B7mbmh8wdeF2_Iw2B87QffUd8wMeN_hQjNxxB205Dkq8gPGgo7ZDaa_wKWIYhAog8k2AWqwhWfmjK9rXHNfGDsudaamH1orck-hlAEVA87PxdwyXcqJuaENRTOgfGh1JREcBOCuXNxVYFFGA6ANwGjghr3xuT8NTA7V2_PF-nlXriGbNwznPttWoSPefEtaa0nyswp6weo'
  lwa_app_id: 'amzn1.application-oa2-client.cb35031aasdae9f94fdf57a4bgaf2ff2a8763'
  lwa_client_secret: '1cacedc7d606078f6231asdadeba8d764f6asdad683ad13acc54851245732ff2eb86a2e6c0'
  aws_secret_key: 'unTBt/mLwXrjvhV53TdnvoPmFVdasUUIr/pHNo0Z/O7'
  aws_access_key: 'AKIA2E5E7WFDFUETCZY'
  role_arn: 'arn:aws:iam::697749123927:role/role_test'

Todos esses parâmetros de configuração podem ser obtidos na seção de configurações

🚧
IMPORTANTE
É necessário apontar para o Marketplace correto em:
...\PYTHON-SP-API\venv\Lib\site-packages\sp_api\base\client.py
Linha de código (Exemplo Brasil):
marketplace: Marketplaces = Marketplaces.BR

3. Gerar o relatório

O exemplo específico que vamos ilustrar é a da árvore da Amazon (Browse Node Tree).
O primeiro passo é importar as seguintes libs para o projeto. Essas libs são específicas para a geração de relatórios e conversão de formatos.

import json
import xmltodict
from sp_api.api import Reports
from sp_api.base.reportTypes import ReportType

O próximo passo é o de realizar a chamada de criação de relatório . Para esta chamada, o único parâmetro obrigatório é o tipo de relatório (GET_XML_BROWSE_TREE_DATA). Os outros parâmetros (Intervalo de tempo) são opcionais.

rtype = ReportType.GET_XML_BROWSE_TREE_DATA
start_time = None #'2021-05-08'
end_time = None #'2020-07-15'
createReportResponse = Reports().create_report(reportType=rtype,dataStartTime=start_time,dataEndTime=end_time)
print(createReportResponse)

Segue o resultado desta chamada.

{
 'errors': None,
 'headers': {'Date': 'Thu, 10 Jun 2021 13:19:46 GMT', 'Content-Type': 'application/json', 'Content-Length': '38', 'Connection': 'keep-alive', 'x-amzn-RequestId': '656dc708-9d49-4c83-95b0-c126911479ed', 'x-amz-apigw-id': 'Atep0G2zoAMFjrg=', 'X-Amzn-Trace-Id': 'Root=1-60c21171-11238b8b61956fdc6a02ee69'},
 'kwargs': {},
 'next_token': None,
 'pagination': None,
 'payload': {'reportId': '50072018788'}
}

👍
Guarde!
Guarde a informação de reportId para utilizar na próxima chamada.

4. Obter a resposta do processamento do relatório

Depois de ter sido solicitado o processamento do relatório, agora precisamos ver se ele foi concluído com sucesso ou não (para mais detalhes dos status de execução do relatório, clique aqui)

Utilizando o reportId do passo anterior, executamos a chamada atual utilizando-o como parâmetro:

rep_id = '50072018788'
getReportResponse = Reports().get_report(report_id=rep_id)
print(getReportResponse)

Segue a resposta em JSON

{
 'errors': None,
 'headers': {'Date': 'Thu, 10 Jun 2021 13:28:26 GMT', 'Content-Type': 'application/json', 'Content-Length': '458', 'Connection': 'keep-alive', 'x-amzn-RequestId': '64b728e0-ec47-4dcb-8d33-c29c611977c0', 'x-amzn-RateLimit-Limit': '2.0', 'x-amz-apigw-id': 'Atf7IFgGoAMFQNg=', 'X-Amzn-Trace-Id': 'Root=1-60c2137a-290b84fc137cd20663648692'},
 'kwargs': {},
 'next_token': None,
 'pagination': None,
 'payload': {'createdTime': '2021-06-09T13:31:46+00:00',
             'dataEndTime': '2021-06-09T13:31:46+00:00',
             'dataStartTime': '2021-06-09T13:31:46+00:00',
             'marketplaceIds': ['A2Q3Y263D00KWC'],
             'processingEndTime': '2021-06-09T13:31:58+00:00',
             'processingStartTime': '2021-06-09T13:31:51+00:00',
             'processingStatus': 'DONE',
             'reportDocumentId': 'amzn1.spdoc.1.3.b4152bac-b979-4f8d-8029-37c4482e34b0.TJ7HRT2QFUUDH.316',
             'reportId': '50042018787',
             'reportType': 'GET_XML_BROWSE_TREE_DATA'}
}

👍
Guarde!
Guarde o reportDocumentId para a próxima chamada.

5. Baixar o relatório e decriptá-lo

O reportDocumentId do passo anterior é um link onde agora se encontra o relatório encriptado que pode ser baixado. A PYTHON-AMAZON-SP-API oferece a opção de baixar esse relatório e já decriptá-lo na sequência.

doc_id = 'amzn1.spdoc.1.3.b4152bac-b979-4f8d-8029-37c4482e34b0.TJ7HRT2QFUUDH.316'
desencriptar = True
path = open('C:/Users/Test/Desktop/SP-API/Reports/report.xml', 'w', encoding='iso-8859-1')
getReportDocument = Reports().get_report_document(document_id = doc_id, decrypt = desencriptar, file=path)
print(getReportDocument)

🚧
Encoding
É necessário utilizar o padrão de decodificação ISO-88590-1 em função dos caracteres especiais latinos (Acentuação, cedilhas).

🚧
Você sabia?
O padrão de encriptação dos relatórios é AES 256 bits CBC, de modo que utiliza os seguintes parâmetros (exemplo):

'initializationVector': 'IoxrY53t9Kpbk1CWzZn0LQ=='

'key': 'TtuDdpKcW3inpRb/y1nlLdctyzmmCUt0wcE+W2g98ew='

Essa chamada, além de retornar o link onde está o documento, retorna também o seu conteúdo (que no exemplo acima está sendo gravado em um arquivo) e o padrão de encriptação utilizado para decriptografar o arquivo.

'encryptionDetails': {'initializationVector': 'IoxrY53t9Kpbk1CWzZn0LQ==','key': 'TtuDdpKcW3inpRb/y1nlLdctyzmmCUt0wcE+W2g98ew=','standard': 'AES'},
'reportDocumentId': 'amzn1.spdoc.1.3.b4152bac-b979-4f8d-8029-37c4482e34b0.TJ7HRT2QFUUDH.316',
'url': 'https://tortuga-prod-na.s3-external-1.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.b4152bac-b979-4f8d-8029-37c4482e34b0.TJ7HRT2QFUUDH?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210610T134028Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Credential=AKIA5U6MO6RAKE6ZSV4V%2F20210610%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=d6552176b65ad6abc25cbe897342c95fe0275835d4cb4ee7ce6322b9b4c7b2b0'}}

Consulte abaixo o resultado do relatório XML gerado.

github.com

amzn-tools/sp-api-sdk

6. (Opcional) Conversão do XML para JSON

Além disso, também é possível realizar a conversão deste relatório para um formato JSON mais fácil de ser utilizado.

# open the input xml file and read
# data in form of python dictionary
# using xmltodict module
with open('C:/Users/test/Desktop/SP-API/Reports/report.xml', encoding='iso-8859-1') as xml_file:
  data_dict = xmltodict.parse(xml_file.read())
  xml_file.close()
  json_data = json.dumps(data_dict,indent=True, ensure_ascii=False)
  print(data_dict)
  with open('C:/Users/test/Desktop/SP-API/Reports/report.json', "w", encoding='iso-8859-1') as json_file:
    json_file.write(json_data)
    json_file.close()

Consulte abaixo o resultado do relatório JSON gerado.

github.com

amzn-tools/sp-api-sdk

Exemplo de nó gerado no JSON completo da árvore de relacionamentos:

{
 "Result": {
  "Node": [
   {
    "browseNodeId": "17938239011",
    "browseNodeAttributes": {
     "@count": "1",
     "attribute": {
      "@name": "recommended_browse_nodes",
      "#text": "17938239011"
     }
    },
    "browseNodeName": "Alexa Skills",
    "browseNodeStoreContextName": "Alexa Skills",
    "browsePathById": "17938238011,17938239011",
    "browsePathByName": "Alexa Skills",
    "hasChildren": "true",
    "childNodes": {
     "@count": "23",
     "id": [
      "18078004011",
      "18078005011",
      "18078006011",
      "18078007011",
      "18078008011",
      "18078065011",
      "18078009011",
      "18078010011",
      "18078011011",
      "18078012011",
      "18078013011",
      "18078014011",
      "18078015011",
      "18078016011",
      "18078017011",
      "18078018011",
      "18078019011",
      "18078020011",
      "18078021011",
      "18078039011",
      "18078022011",
      "18078023011",
      "18078024011"
     ]
    },
    "productTypeDefinitions": null,
    "refinementsInformation": {
     "@count": "0"
    }
   }
}

👍
Árvore de Relacionamentos
Para entender como utilizar a árvore de relacionamentos, clique aqui

Implementando Relatórios (Python SDK)

📘
Referência SP-API

1. PYTHON-AMAZON-SP-API (Instalando o SDK)

2. Configurando o Ambiente

🚧
IMPORTANTE

3. Gerar o relatório

👍
Guarde!

4. Obter a resposta do processamento do relatório

👍
Guarde!

5. Baixar o relatório e decriptá-lo

🚧
Encoding

🚧
Você sabia?

6. (Opcional) Conversão do XML para JSON

👍
Árvore de Relacionamentos

📘Referência SP-API

1. PYTHON-AMAZON-SP-API (Instalando o SDK)

2. Configurando o Ambiente

🚧IMPORTANTE

3. Gerar o relatório

👍Guarde!

4. Obter a resposta do processamento do relatório

👍Guarde!

5. Baixar o relatório e decriptá-lo

🚧Encoding

🚧Você sabia?

6. (Opcional) Conversão do XML para JSON

👍Árvore de Relacionamentos

📘
Referência SP-API

🚧
IMPORTANTE

👍
Guarde!

👍
Guarde!

🚧
Encoding

🚧
Você sabia?

👍
Árvore de Relacionamentos