CHAMADA DA SIMULATE
- Danillo (Unlicensed)
- Alessandro Holanda Machado
A Chamada da Simulate consiste em consultar e extrair as informações, com base no arquivos de parâmetros, da API. A integração fornecida para possibilitar a extração dessa informações é a conexão entre o SAP e a API. O retorno dessa chamada é no formato Json. O propósito do desenvolvimento desta chamada é obter informações de preço, valores totais e de impostos, em função do Tipo de Documento (ZDX, ZCPP e ZCPI), os quais apresentarão a utilidade de construir uma tabela com o cálculo.
Recursos Necessários
Os recursos utilizados devem ser mencionados para apoio no entendimento e desenvolvimento da Chamada Simulate. Abaixo segue a lista de todos os insumos utilizados para o estabelecimento deste projeto:
Postman: apresenta a utilidade de validar o retorno da API com os parâmetros especificados;
Amostra de Parâmetros: arquivo solicitante à área de negócios para fornecer os parâmetros necessários para o retorno das informações da chamada simulate.
Notebook do Databricks da Chamada da Simulate: desenvolvimento de script da Chamada Simulate que realiza a requisição das informações de preço, valores totais e impostos, a partir da leitura e configuração do arquivo de parâmetros, da API. (COLOCAR O LINK)
Notebook do Databricks para a leitura e configuração do arquivo de parâmetros: desenvolvimento de script da leitura do arquivo extraído, adequação das informações com o modelo atual e configuração do Tipo de Documento para ocorrer a chamada da simulate. (COLOCAR O LINK
Jira: este sistema pode ser usado para a consulta do Card DGA - 535 a qual apresenta todas as informações do projeto e o commit dos notebooks do Databricks.
METODOLOGIA
Arquivo de Parâmetros
Após a solicitação do arquivo de parâmetros em excel e a adaptação para csv, o processo de geração, importação e gravação do arquivo de parâmetros pode ser vista na Figura 1:
De acordo com a Figura 1, a área de negócios extrai um arquivo de parâmetros em excel e é enviado para o nosso domínio. Posteriormente, é criado um código Python que lê este arquivo (transformado em csv) e extrai para o storage como gravação de uma tabela relacional no Databricks.
Após a gravação do arquivo de parâmetros, deve-se adequar na mesma configuração de nomenclatura e tipos de dados das colunas da tabela genesis_pricing.parametersv4.
Observações: Pode ocorrer a ausência de algumas colunas no arquivo extraído pela área de negócios, por exemplo, “FuncaoParceiro”. Para este caso deve-se criar uma coluna com este nome e atribuir o valor “AG”. Caso este comportamento ocorra para outras colunas, verificar com a área de negócios.
A extração das informações de preço, valores totais e impostos é dependente do tipo de Documento. O Arquivo de parâmetros extraídos pela área de negócios geralmente está com o Tipo de Documento (coluna “Tp.Doc”) associado ao valor ZDX (Venda Normal). Para este caso, caso seja necessário buscar as informações para ZCPL (Preço Lucro) e ZCPI (Impostos), deve-se duplicar os registros para cada grupo baseado no ZDX e unir tudo conforme na Figura 2:
Para mais informações sobre o desenvolvimento do script, acessar:
Após essas configurações do arquivo de parâmetros, a tabela é gravada no database genesis_pricing e deve seguir este padrão.
Tp_Doc | Org_Vendas | Eq_Vendas | Escr_Vendas | Regiao_de_vendas | Cond_de_Pgto | Cond_Expedicao | Moeda | Entrega_Paletizada | Incoterms | Incoterms_2 | Setor_de_atividade | Canal_distribuicao | Louca_Embalada | Funcao_parceiro | Utilizacao | Emissor_da_Ordem | Centro | Material |
ZDX | DH01 | 35 | DB05 | MS02 | BP19 | 1 | BRL | 4 | CIF | CIF | HY | 45 | 4 | AG | ZR | 92001 | HY01 | 1167.METVMHMN |
ZDX | DH01 | 35 | DB05 | MS02 | BP19 | 1 | BRL | 4 | CIF | CIF | HY | 45 | 4 | AG | ZR | 92001 | HY01 | 1168.METPTHMN |
ZCPP - Consulta Preco | DH01 | 510 | DI05 | ZH02 | B120 | 1 | BRL | 4 | CIF | CIF | HY | 45 | null | AG | ZR | 1186836 | HY01 | DPBL.3SAR.532BR |
ZCPP - Consulta Preco | DH01 | 510 | DI05 | ZH25 | B100 | 1 | BRL | 4 | CIF | CIF | HY | 45 | null | AG | ZR | 712531 | HY01 | DPMD.4.622BR |
ZCPI - Consulta Imposto | DH01 | 35 | DB05 | MS02 | BP19 | 1 | BRL | 4 | CIF | CIF | HY | 45 | 4 | AG | ZR | 92001 | HY01 | 1167.METVMHMN |
ZCPI - Consulta Imposto | DH01 | 35 | DB05 | MS02 | BP19 | 1 | BRL | 4 | CIF | CIF | HY | 45 | 4 | AG | ZR | 92001 | HY01 | 1168.METPTHMN |
Os campos extraídos e configurados são:
'
Campos Origem SAP | Campos Extraídos | Data Types | Descrição do campo |
|---|---|---|---|
DOC_TYPE | Tp_Doc | CHAR | Tipo de Documento de Vendas |
SALES_ORG | Org_Vendas | CHAR | Organização de Vendas |
SALES_GRO | Eq_Vendas | CHAR | Equipe de Vendas |
SALES_OFF | Escr_Vendas | CHAR | Escritório de Vendas |
SALES_DIST | Regiao_de_Vendas | CHAR | Região de Vendas |
| Cond_de_Pgto |
| Condição de Pagamento |
SHIP_COND | Cond_Expedicao | CHAR | Condição de Expedição |
CURRENCY | Moeda | CUKY | Moeda do documento SD |
PRICE_LIST | Entrega_Paletizada | CHAR | Entrega Paletizada |
INCOTERMS1 | Incoterms | CHAR | Incoterms parte 1 |
INCOTERMS2 | Incoterms2 | CHAR | Incoterms parte 2 |
DIVISION | Setor_de_atividade | CHAR | Setor de Atividade |
DISTR_CHAN | Canal_distribuicao | CHAR | Canal de Distribuição |
CUST_GROUP | Louca_Embalada | CHAR | Louça Embalada |
PARTN_ROLE | Funcao_Parceiro | CHAR | Função do Parceiro |
| Utilizacao | CHAR | Utilização |
| Emissor_da_Ordem | CHAR | Emissor da Ordem |
| Centro | CHAR | Centro |
CUST_MAT | Material | CHAR | Material do Cliente |
Chamada Simulate
A chamada da Simulate ocorre a partir do payload em função do dataframe passado como parâmetro. Este dataframe é construída a partir da leitura do arquivo de parâmetros configurados e da sua relação com as tabelas de clientes e de expedição. Além disso, é feita adaptação em algumas colunas como no Tipo de Documento, Preço e entre outros. Esta adaptação é feita para que a requisição da API possa ocorrer com o êxito. Caso contrário, haverá erro de integração da chamada com o server do SAP.
Em relação a afirmativa do êxito do payload, mais um requisito é necessário: a construção da chamada do payload deve ter formato json com os parâmetros ajustados para que a requisição ocorra. Tais parâmetros deve ser usado desta forma para o ZDX:
{
"schedule": {
"Item": {
"scheduleLineDate": "",
"salesDocumentItem": "000150",
"orderQuantityInSalesUnits": "10"
}
},
"rotationHeader": {
"yourReference": "SF",
"valueShipping": "0",
"valueAccessoryCosts": "0",
"termsOfPaymentKey": "B028",
"shippingConditions": "Standard",
"sdDocumentCurrency": "BRL",
"salesOrganization": "DC01",
"salesOffice": "DB03",
"salesGroup": "091",
"salesDocumentType": "ZDX - Venda Normal",
"salesDistrict": "Deca - MG Região 07",
"requestedDeliveryDate": "",
"priceListType": "Não",
"incotermsPart2": "CIF - Custo, seguro & frete",
"incotermsPart1": "CIF - Custo, seguro & frete",
"division": "MS",
"distributionChannel": "40",
"dateForPricingAndExchangeRate": None,
"customerPurchaseOrderNumber": "",
"customerPurchaseOrderDate": "2020-07-30",
"customerGroup": "false",
"cup": "Revenda",
"completeDeliveryDefinedForEachSalesOrder": ""
},
"quotePartners": {
"Item": {
"partnerFunction": "EmissorOrdem",
"customerNumber": "0000032611"
}
},
"quoteItems": {
"Item": {
"salesDocumentItem": "000150",
"rateConditionRound": "0",
"rateConditionAmountOrPercentage": "0.00",
"plant": "D085",
"materialNumber": "4688.931"
}
},
"guuid": None,
"extension": {
"Item": {
"dataPartOfBapiExtensionParameter3": None,
"dataPartOfBapiExtensionParameter2": "",
"dataPartOfBapiExtensionParameter1": None,
"dataPartOfBapiExtensionParameter": ""
}
}
}Observações: para os casos de ZCPP ou ZCPI deve alterar os parâmetros "yourReference" para "HUB" e
"salesDocumentType" para "ZCPP - Consulta Preço" ou "ZCPI - Consulta Imposto", respectivamente.
Abaixo, segue o modelo testado para o ZCPL:
{
"schedule": {
"Item": {
"scheduleLineDate": "",
"salesDocumentItem": "000150",
"orderQuantityInSalesUnits": "10"
}
},
"rotationHeader": {
"yourReference": "HUB",
"salesDocumentType": "ZCPL",
"valueShipping": "0",
"valueAccessoryCosts": "0",
"termsOfPaymentKey": "B028",
"shippingConditions": "Standard",
"sdDocumentCurrency": "BRL",
"salesOrganization": "DC01",
"salesOffice": "DB03",
"salesGroup": "091",
"salesDistrict": "Deca - MG Região 07",
"requestedDeliveryDate": "",
"priceListType": "Não",
"incotermsPart2": "CIF - Custo, seguro & frete",
"incotermsPart1": "CIF - Custo, seguro & frete",
"division": "MS",
"distributionChannel": "40",
"dateForPricingAndExchangeRate": null,
"customerPurchaseOrderNumber": "",
"customerPurchaseOrderDate": "2020-07-30",
"customerGroup": "false",
"cup": "Revenda",
"completeDeliveryDefinedForEachSalesOrder": ""
},
"quotePartners": {
"Item": {
"partnerFunction": "EmissorOrdem",
"customerNumber": "0000032611"
}
},
"quoteItems": {
"Item": {
"salesDocumentItem": "000150",
"rateConditionRound": "0",
"rateConditionAmountOrPercentage": "0.00",
"plant": "D085",
"materialNumber": "4688.931"
}
},
"guuid": None,
"extension": {
"Item": {
"dataPartOfBapiExtensionParameter3": None,
"dataPartOfBapiExtensionParameter2": "",
"dataPartOfBapiExtensionParameter1": None,
"dataPartOfBapiExtensionParameter": ""
}
}
}O modelo para o ZCPI pode ser visto no código:
{
"schedule": {
"Item": {
"scheduleLineDate": "",
"salesDocumentItem": "000150",
"orderQuantityInSalesUnits": "1"
}
},
"rotationHeader": {
"yourReference": "HUB",
"salesDocumentType": "ZCPI",
"valueShipping": "0",
"valueAccessoryCosts": "0",
"termsOfPaymentKey": "B028",
"shippingConditions": "Standard",
"sdDocumentCurrency": "BRL",
"salesOrganization": "DC01",
"salesOffice": "DB03",
"salesGroup": "091",
"salesDistrict": "Deca - MG Região 07",
"requestedDeliveryDate": "",
"priceListType": "Não",
"incotermsPart2": "CIF - Custo, seguro & frete",
"incotermsPart1": "CIF - Custo, seguro & frete",
"division": "MS",
"distributionChannel": "40",
"dateForPricingAndExchangeRate": null,
"customerPurchaseOrderNumber": "",
"customerPurchaseOrderDate": "2020-07-30",
"customerGroup": "false",
"cup": "Revenda",
"completeDeliveryDefinedForEachSalesOrder": ""
},
"quotePartners": {
"Item": {
"partnerFunction": "EmissorOrdem",
"customerNumber": "0000032611"
}
},
"quoteItems": {
"Item": {
"salesDocumentItem": "000150",
"rateConditionRound": "0",
"rateConditionAmountOrPercentage": "0.00",
"plant": "D085",
"materialNumber": "4688.931"
}
},
"guuid": None,
"extension": {
"Item": {
"dataPartOfBapiExtensionParameter3": None,
"dataPartOfBapiExtensionParameter2": "",
"dataPartOfBapiExtensionParameter1": None,
"dataPartOfBapiExtensionParameter": ""
}
}
}
Os campos do payload podem ser especificados abaixo:
Campo do Payload | Descrição |
|---|---|
| Data de Agendamento |
| Item do Documento de Vendas |
| Unidades de Quantidade De Vendas |
| Referência: SF ou HUB |
| Tipo de Documento |
| Valor de Expedição |
| Valor de Custos Acessórios |
| Chave de Termos de Pagamento |
| Condições de Expedição |
| Moeda de Documento SD |
| Organização de Vendas |
| Escritório de Vendas |
| Grupo de Vendas |
| Região de Vendas |
| Data de Entrega do Pedido |
| Typo de Lista de Preço |
| Incoterms 2 |
| Incoterms 1 |
| Divisão |
| Canal de Distribuição |
| Data para Taxa de Preço e Troca |
| Número de Ordem do Pedido do Cliente |
| Data de Ordem do Pedido do Cliente |
| Grupo do cliente |
| Cup |
|
|
| Função Parceiro |
| Número do Cliente |
| Item do Documento de Vendas |
|
|
|
|
| Planta |
| Número do Material |
|
|
|
|
|
|
|
|
A Execução do Payload pode ser visto no comando abaixo. Para este caso, a chamada dos preços, vendas totais e impostos serão para o documento ZDX.
Para os casos de ZCPP e ZCPI, é só atribuir a cláusula else para o primeiro condição if para o Tipo de Documento do ZDX assim:
Throubleshoot
Para validar corretamento a chamada da API deve-se atentar a três principais etapas: header da função da chamada da simulate; parâmetros da chamada no formato json e verificação da execução do payload para o formato especificado no header.
Header da Função da Chamada Simulate
O desenvolvimento do notebook para realizar a requisição da API foi desenvolvido com a passagem de parâmetros no formato json. A primeira etapa é verificar se a definição da função da chamada simulate está contemplando este formato. Isto pode ser visto na especificação do header da url.
Parâmetros da Chamada Simulate
Um dos principais problemas que podem ocorrer com o retorno da chamada simulate é a definição dos parâmetros. A solução para este problema foi desenvolvida pelos testes de especificação um a um de cada parâmetro. O modelo ideal para a requisição ocorrer de maneira com êxito é definida no formato abaixo. Este formato pode ser usado para todas as chamadas.
A ideia usada para Throubleshoot é adicionar parâmetro por parâmetro e executar o seguinte comando:
Ao adicionar cada parâmetro e executar, se dar o erro no próprio parâmetro que foi especificado, então foi colocado de maneira errada. Caso, dê erro no próximo parâmetro (por não estar especificado. Lembre-se a adição é um a um), então significa que o parâmetro foi definido de maneira certo.
Observações: atentar aos parâmetros de "guuid", "dataPartOfBapiExtensionParameter3" e "dataPartOfBapiExtensionParameter1". No caso do postman, atribui null para estes parâmetros. Aqui no Databricks não deve ser especificado como “null”, e sim como None. Além disso, o parâmetro "yourReference" é case sensitive.
Para validar a ocorrência do êxito é verificar o retorno do SAP. Se o código for 200 significa que a ocorrência foi certa.
Utilizar apenas este parâmetro para validar não significa muito em relação ao retorno da chamada se ocorrerá com êxito. Para isso, é preciso verificar se o retorno, para os parâmetros que foram especificados, estão com valores conforme na figura abaixo. Caso dê problemas no retorno da chamada, os valores estão zerados. Isso pode estar associado com a adoção do valor do parâmetro None para “null” e caso do case sensitive do SF.
Verificação do retorno do Payload
Conforme discutido, o desenvolvimento do notebook do Databricks para a validação da chamada simulate espera-se o retorno no formato Json. Caso este formato não seja respeitado, o retorno dos preços, vendas totais e impostos para os tipos de documento estarão nulas. Para tanto, a validação do retorno pode ser definida na verificação do formato xml. Caso esteja, atribuirá os valores de acordo com a especificação do payload de retorno com os valores zerados. Isso significa que a API apresenta um bug que precisa ser consertado.
De acordo com a Figura abaixo pode-se a validação do retorno que ocorreu em xml e que identificamos que havia um bug na API.
Payload SAP ECC para o S4
O mapeamento dos campos permite realizar o de-para do payload das informações obtidas do SAP ECC para o S4. Tal processo foi realizada com o auxílio de uma planilha secundária (Anexo abaixo) que contém a dicionarização dos campos de cada tabela. Esta dicionarização possibilita mapear os campos do S4 a partir do SAP ECC, permitindo que a adequação dos campos sejam iguais.
Conforme o arquivo, a realização do mapeamento precisa do uso do notebook do databricks. O comando que cria o dataframe a partir dos campos do S4 está abaixo:
A metodologia para realizar o de-para é a seguinte:
Visualiza o campo no notebook do databricks (código acima), por exemplo, o campo customerNumber
Abre o arquivo do mapeamento em excel, utiliza a aba SAP ECC, procura este campo na coluna chamada “Campo Payload” e verifica o nome do campo na coluna “Parâmetro/Estrutura”.
Utiliza a aba SAP S4 Hana, do mesmo arquivo, e verifica o mesmo nome de campo da coluna “Parâmetro/Estrutura”. Para este registro, obtém o campo correto na coluna “Campo do Payload”.
Alterar o código
A partir do arquivo, na aba do SAP ECC, utiliza-se o campo chamado “Parâmetro/Estrutura” para visualizar o campo origem do SAP.
No código acima, realiza a adequação do campo para o mesmo nome do campo payload na cláusula que obtem o objeto do json -
get_json_object(to_json('d'),'$.results.Customer')