Tendo o entendimento que a WebAPI no StoreFront é o que conecta o front-end com o back-end, a API é o conectará o beck-end com a API externa do parceiro ou serviço promocional externo, para tal, este tutorial irá auxiliar na realização no desenvolvimento da integração com um serviço promocional externo através da nossa API.
Através do documento abaixo, é possível obter a Collection do Postman com todos os métodos necessários para o desenvolvimento, mas nesta documentação também explicaremos todas funcionalidades.
Benefits.postman_collection_v2.json
Os métodos recomendados para o desenvolvimento, estarão disponíveis em "Integration-Partiner" após a importação do arquivo em seu Postman, conforme imagem abaixo:
O mesmo será composto por 4 métodos (POSTs), sendo eles:
1. NotifyPartner utilização recomendada para a notificação dos parceiros de serviços promocionais externos para o Consumo e Cancelamento (exemplo de POST abaixo):
NotifyPartner
{
"Transaction": {
"CreatedDate": "2023-09-20T08:48:00.6015414-03:00",
"SessionID": "nq3uxsd2ofkfs1sp1mbx3gmv",
"ShopperTicketID": "cc822356-0ef8-443a-8324-61d24c40a95f",
"BasketID": 34436,
"Source": "Loja",
"PromotionID": 6129,
"PromotionName": "Benefício Externo",
"PromotionDocumentNumber": ""
},
"Order": {
"OrderID": "ce93264b-56b3-415f-b1da-7d70be26d950",
"CreatedDate": "2023-09-20T08:38:01.99",
"Status": 1,
"ModifiedDate": "2023-09-20T08:47:41.3848978-03:00"
},
"Customer": {
"CustomerID": 252493,
"Cpf": "0782830897",
"Rg": "",
"Email": "atendimento@ezcommerce.com.br",
"CellPhone": "21999999999",
"Birthday": "1999-06-08"
},
"AppliedBenefits": {
"ExternalPromotionIDs": [
"promo1-order-discount"
],
"Cashback": {
"Amount": 200
}
}
}
2. Benefits utilização recomendada para a obtenção de benefícios disponíveis para um pedido (sendo o mesmo composto por um carrinho, item, meio de pagamento, solução logística ou cashback) nos parceiros de serviços promocionais externos (exemplo de POST abaixo):
Benefits
{
"Transaction": {
"SessionID": "nq3uxsd2ofkfs1sp1mbx3gmv",
"ShopperTicketID": "0ff71625-b70c-4120-aeba-328fd5a650d3",
"BasketID": 28298,
"Source": "Loja",
"PromotionID": 5121,
"PromotionName": "Benefício Externo Bemol",
"PromotionDocumentNumber": "41414141414114"
},
"Customer": {
"CustomerID": 252493,
"Cpf": "91290488002",
"Rg": "",
"Email": "atendimento@ezcommerce.com.br",
"CellPhone": "21999999999",
"Birthday": "08/06/1999",
"DeliveryRegion": {
"UF": "RS",
"Cep": "94410970"
}
},
"Items": [
{
"BasketItemID": 67493,
"ProductName": "Camera Fotográfica Canon - teste 1",
"ProductID": 984994,
"SkuId": 984995,
"IntegrationID": "TESTE-REPLICAÇÃOO",
"Quantity": 2,
"Price": 500.00,
"SpecialType": "N",
"Brand": "5 Estrelas",
"Categories": "Esporte e Lazer/Fitness"
},
{
"BasketItemID": 69492,
"ProductName": "Produto sem Estoque e sem Avaliações",
"ProductID": 985094,
"SkuId": 985095,
"IntegrationID": "",
"Quantity": 1,
"Price": 10.00,
"SpecialType": "N",
"Brand": "Padrão",
"Categories": "Musical"
}
],
"DeliveryMethods": [
{
"DeliveryMethodID": "25",
"DeliveryAmount": 62.43,
"DeliveryName": "Entrega própria",
"Alias": "fe_offline"
}
],
"PaymentMethods": [
{
"PaymentMethodID": 1064,
"PaymentType": "Pix",
"IntegrationID": null,
"Alias": "PIX",
"MinInstallmentAmount": 0.0,
"MaxInstallments": 0,
"MaxInstallmentsNoInterest": 0,
"InterestRate": 0.0
},
{
"PaymentMethodID": 1263,
"PaymentType": "CreditCard",
"IntegrationID": null,
"Alias": "VISA",
"MinInstallmentAmount": 0.000,
"MaxInstallments": 10,
"MaxInstallmentsNoInterest": 0,
"InterestRate": 0.000
},
{
"PaymentMethodID": 1253,
"PaymentType": "PaymentSlip",
"IntegrationID": null,
"Alias": "SANTANDER",
"MinInstallmentAmount": 0.0,
"MaxInstallments": 1,
"MaxInstallmentsNoInterest": 1,
"InterestRate": 0.0
},
{
"PaymentMethodID": 1078,
"PaymentType": "CustomCard",
"IntegrationID": "Teste",
"Alias": "CUSTOMCARD",
"MinInstallmentAmount": 0.000,
"MaxInstallments": 1,
"MaxInstallmentsNoInterest": 1,
"InterestRate": 0.000
},
{
"PaymentMethodID": 1248,
"PaymentType": "Pix",
"IntegrationID": null,
"Alias": "PIX",
"MinInstallmentAmount": 0.0,
"MaxInstallments": 0,
"MaxInstallmentsNoInterest": 0,
"InterestRate": 0.0
},
{
"PaymentMethodID": 1065,
"PaymentType": "GenericExternal",
"IntegrationID": null,
"Alias": "GENERICEXTERNAL",
"MinInstallmentAmount": 0.0,
"MaxInstallments": 0,
"MaxInstallmentsNoInterest": 0,
"InterestRate": 0.0
}
],
"SubTotal": 1010.00,
"Total": 1062.43
}
3. BenefitsByItems utilização recomendada para a obtenção de benefícios disponíveis para um item (recomendo a utilização de forma singular pois a utilização em massa pode gerar impacto na performance do lojista) nos parceiros de serviços promocionais externos (exemplo de POST abaixo):
BenefitsByItems:
{
"Transaction": {
"SessionID": "nq3uxsd2ofkfs1sp1mbx3gmv",
"ShopperTicketID": "9bc03718-9395-4105-be74-2c438b71cfed",
"BasketID": 31306,
"Source": "Loja",
"PromotionID": 5122,
"PromotionName": "Benefício Externo Bemol",
"PromotionDocumentNumber": "41414141414114"
},
"Customer": {
"CustomerID": 0,
"Cpf": "11627623736",
"Rg": null,
"Email": null,
"CellPhone": null,
"Birthday": null,
"DeliveryRegion": {
"UF": null,
"Cep": null
}
},
"Items": [
{
"BasketItemID": 67493,
"ProductName": "Camera Fotográfica Canon - teste 1",
"ProductID": 984994,
"SkuId": 984995,
"IntegrationID": "TESTE-REPLICAÇÃOO",
"Quantity": 1,
"Price": 500.0,
"SpecialType": "N",
"Brand": "5 Estrelas",
"Categories": "Esporte e Lazer/Fitness"
},
{
"BasketItemID": 67493,
"ProductName": "Camera Fotográfica Canon - teste 1",
"ProductID": 984994,
"SkuId": 984995,
"IntegrationID": "TESTE-REPLICAÇÃOO",
"Quantity": 1,
"Price": 500.0,
"SpecialType": "N",
"Brand": "5 Estrelas",
"Categories": "Esporte e Lazer/Fitness"
}
],
"DeliveryMethods": [],
"PaymentMethods": [],
"SubTotal": 0.0,
"Total": 0.0
}
4. Token. No caso da requisição Token não há Body, a API apenas guardará internamente os dados recebidos pela API (Key & Value) para que haja a autenticação.
Abaixo há o exemplo de retorno das consultas em que o parceiro irá retornar através da API, de modo que o lojista receba os dados no back-end e realize o devido tratamento dos dados, podendo desta maneira manusear benefícios de um Pedido, Item do Pedido, Meios de Entrega, Meios de Pagamento ou para o Cashback, mas sempre para um carrinho (pedido) específico:
ResponseBenefits:
[
{
"Benefits": {
"Cashback": {
"BalanceAmount": 242.04
},
"DeliveryDiscounts": [
{
"ActivationQty": 0,
"CalculationBasisType": "O",
"DeliveryMethods": [
{
"Alias": "fe_offline",
"DeliveryAmount": 62.43,
"DeliveryMethodID": "25",
"DeliveryName": "Entrega própria"
}
],
"DiscountPercent": 5,
"DiscountType": "P",
"DiscountValue": 0,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "CUPOM123",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-delivery-coupon",
"ExternalPromotionName": "Desconto de 10% em todos os itens - V",
"ExternalPromotionTargetID": 2,
"ExternalPromotionType": 0,
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
},
{
"ActivationQty": 0,
"CalculationBasisType": "O",
"DeliveryMethods": [
{
"Alias": "fe_offline",
"DeliveryAmount": 62.43,
"DeliveryMethodID": "25",
"DeliveryName": "Entrega própria"
}
],
"DiscountPercent": 0,
"DiscountType": "V",
"DiscountValue": 10,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-delivery-discount",
"ExternalPromotionName": "Desconto de 10 reais em todos os itens",
"ExternalPromotionTargetID": 2,
"ExternalPromotionType": 1,
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
},
{
"ActivationQty": 2,
"CalculationBasisType": "D",
"DeliveryMethods": [
{
"Alias": "fe_offline",
"DeliveryAmount": 62.43,
"DeliveryMethodID": "25",
"DeliveryName": "Entrega própria"
}
],
"DiscountPercent": 5,
"DiscountType": "P",
"DiscountValue": 0,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-delivery-promotion",
"ExternalPromotionName": "Desconto de 10% em todos os itens - Valor descontado",
"ExternalPromotionTargetID": 2,
"ExternalPromotionType": 2,
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
}
],
"ItemsDiscounts": [
{
"ActivationQty": 0,
"CalculationBasisType": "O",
"DiscountPercent": 5,
"DiscountType": "P",
"DiscountValue": 0,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "CUPOM123",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-item-coupon",
"ExternalPromotionName": "Desconto de 10% em todos os itens - V",
"ExternalPromotionTargetID": 0,
"ExternalPromotionType": 0,
"Items": [
{
"BasketItemID": 71577,
"Brand": "5 Estrelas",
"Categories": "Esporte e Lazer/Fitness",
"IntegrationID": "TESTE-REPLICAÇÃOO",
"Price": 500,
"ProductID": 984994,
"ProductName": "Camera Fotográfica Canon - teste 1",
"Quantity": 5,
"SkuID": 984995,
"SpecialType": "N"
},
{
"BasketItemID": 71578,
"Brand": "Padrão",
"Categories": "Musical",
"IntegrationID": "",
"Price": 10,
"ProductID": 985094,
"ProductName": "Produto sem Estoque e sem Avaliações",
"Quantity": 1,
"SkuID": 985095,
"SpecialType": "N"
}
],
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
},
{
"ActivationQty": 0,
"CalculationBasisType": "O",
"DiscountPercent": 0,
"DiscountType": "V",
"DiscountValue": 10,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-item-discount",
"ExternalPromotionName": "Desconto de 10 reais em todos os itens",
"ExternalPromotionTargetID": 0,
"ExternalPromotionType": 1,
"Items": [
{
"BasketItemID": 71577,
"Brand": "5 Estrelas",
"Categories": "Esporte e Lazer/Fitness",
"IntegrationID": "TESTE-REPLICAÇÃOO",
"Price": 500,
"ProductID": 984994,
"ProductName": "Camera Fotográfica Canon - teste 1",
"Quantity": 5,
"SkuID": 984995,
"SpecialType": "N"
},
{
"BasketItemID": 71578,
"Brand": "Padrão",
"Categories": "Musical",
"IntegrationID": "",
"Price": 10,
"ProductID": 985094,
"ProductName": "Produto sem Estoque e sem Avaliações",
"Quantity": 1,
"SkuID": 985095,
"SpecialType": "N"
}
],
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
},
{
"ActivationQty": 2,
"CalculationBasisType": "D",
"DiscountPercent": 5,
"DiscountType": "P",
"DiscountValue": 0,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-item-promotion",
"ExternalPromotionName": "Desconto de 10% em todos os itens - Valor descontado",
"ExternalPromotionTargetID": 0,
"ExternalPromotionType": 2,
"Items": null,
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
}
],
"OrderDiscounts": [
{
"ActivationQty": 0,
"CalculationBasisType": "O",
"DiscountPercent": 5,
"DiscountType": "P",
"DiscountValue": 0,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "CUPOM123",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-order-coupon",
"ExternalPromotionName": "Desconto de 10% em todos os itens - V",
"ExternalPromotionTargetID": 1,
"ExternalPromotionType": 0,
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
},
{
"ActivationQty": 0,
"CalculationBasisType": "O",
"DiscountPercent": 0,
"DiscountType": "V",
"DiscountValue": 10,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-order-discount",
"ExternalPromotionName": "Desconto de 10 reais em todos os itens",
"ExternalPromotionTargetID": 1,
"ExternalPromotionType": 1,
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
},
{
"ActivationQty": 2,
"CalculationBasisType": "D",
"DiscountPercent": 5,
"DiscountType": "P",
"DiscountValue": 0,
"ExpiresIn": "2023-09-13T09:07:18.9601815-03:00",
"ExternalCouponCode": "",
"ExternalDescriptionRules": "Regras da promoção",
"ExternalPromotionID": "promo1-order-promotion",
"ExternalPromotionName": "Desconto de 10% em todos os itens - Valor descontado",
"ExternalPromotionTargetID": 1,
"ExternalPromotionType": 2,
"ShowExternalPromotionNameInStore": false,
"UrlImage": "https://example.com/promo1.jpg"
}
],
"PaymentDiscounts": [
{
"ExternalPromotionID": "promo1-delivery-coupon",
"PaymentMethods": [
{
"Alias": "VISA",
"IntegrationID": null,
"InterestRate": 0,
"MaxInstallments": 10,
"MaxInstallmentsNoInterest": 10,
"MinInstallmentAmount": 0,
"PaymentMethodID": 979,
"PaymentType": "CreditCard"
},
{
"Alias": "PIX",
"IntegrationID": null,
"InterestRate": 0,
"MaxInstallments": 0,
"MaxInstallmentsNoInterest": 0,
"MinInstallmentAmount": 0,
"PaymentMethodID": 964,
"PaymentType": "Pix"
}
]
},
{
"ExternalPromotionID": "promo1-item-discount",
"PaymentMethods": [
{
"Alias": "VISA",
"IntegrationID": null,
"InterestRate": 0,
"MaxInstallments": 10,
"MaxInstallmentsNoInterest": 10,
"MinInstallmentAmount": 0,
"PaymentMethodID": 979,
"PaymentType": "CreditCard"
},
{
"Alias": "PIX",
"IntegrationID": null,
"InterestRate": 0,
"MaxInstallments": 0,
"MaxInstallmentsNoInterest": 0,
"MinInstallmentAmount": 0,
"PaymentMethodID": 964,
"PaymentType": "Pix"
}
]
},
{
"ExternalPromotionID": "promo1-order-discount",
"PaymentMethods": [
{
"Alias": "VISA",
"IntegrationID": null,
"InterestRate": 0,
"MaxInstallments": 10,
"MaxInstallmentsNoInterest": 10,
"MinInstallmentAmount": 0,
"PaymentMethodID": 979,
"PaymentType": "CreditCard"
},
{
"Alias": "PIX",
"IntegrationID": null,
"InterestRate": 0,
"MaxInstallments": 0,
"MaxInstallmentsNoInterest": 0,
"MinInstallmentAmount": 0,
"PaymentMethodID": 964,
"PaymentType": "Pix"
}
]
}
]
},
"BenefitsErrors": [],
"Transaction": {
"BasketID": 33369,
"PromotionDocumentNumber": null,
"PromotionID": 6129,
"PromotionName": "Benefício Externo",
"SessionID": "nq3uxsd2ofkfs1sp1mbx3gmv",
"ShopperTicketID": "e784f4c0-9a00-46bd-94a5-99f8a376e189",
"Source": "Loja"
}
}
]
Para eventuais dúvidas, nosso time de relacionamento ao cliente estará 100% a disposição para lhe auxiliar tanto no processo de configuração quanto as dúvidas que surgirem durante a utilização da nova funcionalidade.