01. DADOS GERAIS
| Produto: | | Solucoes_totvs |
|---|
| Solucao | TOTVS Distribuição e Varejo |
|---|
|
| Solucoes_totvs_parceirosexptotvs |
|---|
|
|
|---|
| Linha de Produto: | |
|---|
| Segmento: | |
|---|
| Módulo: | | Modulos_totvs_prestadores_de_servicos |
|---|
Pedido de Venda |
|---|
| Função: | Integrações Winthor |
|---|
| País: | Brasil |
|---|
| Requisito/Story/Issue (informe o requisito relacionado) : | DINTVENDAS-116 |
|---|
02. SITUAÇÃO/REQUISITO
A necessidade
...
é garantir a correta aplicação dos descontos patrocinados pela loja (merchant) nos itens de um pedido importado da plataforma iFood.
O grupo benefits no payload identifica os descontos existentes no pedido. Conforme a documentação oficial do iFood e testes realizados, apenas os descontos cujos grupos contenham o campo Benefits.Sponsorships.Liability com valor "PARTNER" ou "CHAIN" devem ser considerados como desconto e aplicados no preço dos itens.
Descontos com liability igual a 'OWN' ou 'EXTERNAL' devem ser tratados como tipo de pagamento, pois o iFood fará o repasse ou subsídio desses valores para a loja.
Descontos aplicados na taxa de entrega (DELIVERY_FEE) não serão considerados nesta entrega, devido à falta de clareza sobre como tratá-los.
03. SOLUÇÃO
Foi implementado um mecanismo de integração que atua como uma ponte, buscando o pedido no iFood e convertendo os dados para o formato aceito pelo Winthor.
Fluxo de Transformação de Dados
1. Consumo da API: O sistema Winthor consome a API Order do iFood (utilizando a busca desenvolvida na ISSUE DINTVENDAS-46) para buscar o payload do pedido.
2. Mapeamento e Conversão (DE/PARA): O JSON do iFood é transformado para o layout aceito pelo Winthor.
3. Envio ao Winthor: O pedido transformado é enviado para a API de entrada do Winthor (api/wholesale/v1/orders/).
Regras Especiais de Dados
A importação garante que os pedidos sejam processados utilizando parâmetros fixos pré-configurados, independentemente do payload recebido do iFood:
...
implementada a lógica de identificação e aplicação dos descontos patrocinados pelo parceiro (PARTNER ou CHAIN) nos itens do pedido importado, garantindo que o preço de venda final (PVENDA) registrado no Winthor reflita o valor líquido do desconto.
Os seguintes tipos de targets de desconto foram implementados:
- Desconto no Item (target = ITEM ou target = PROGRESSIVE_DISCOUNT_ITEM):
- O campo targetId identifica o item específico.
- O valor do desconto informado no JSON corresponde ao total para a linha, devendo ser dividido pela quantidade do item para obter o desconto unitário.
- O desconto unitário é aplicado diretamente ao preço de venda.
- Desconto de Rodapé (target = CART):
- O valor total do desconto deve ser rateado proporcionalmente ao valor total dos itens do pedido.
- Após o rateio (cálculo proporcional), o desconto unitário resultante deve ser aplicado em cada item antes do envio do preço de venda para a API B2C.
- Exemplo de Cálculo de Rateio Proporcional: Se o Item A é 60% do total bruto e o desconto total é R$ 20,00, o Item A recebe R$ 12,00 (60% de R$ 20,00) de desconto.
O JSON final enviado para a API B2C deve conter o preço unitário já líquido do desconto aplicado.
• Parâmetros Fixos do HUB (WSH): Campos que não dependem do iFood nem da configuração do usuário, como o Tipo de Venda, são definidos como "1" (fixo) nos Parâmetros WSH. Código da Filial também é um valor fixo definido pelo token.
• Preço do Item: O Valor unitário (sellPrice) é tratado por uma regra especial: o valor recebido (em centavos) é dividido por 100 para ser convertido em valor real.
• Identificação do Item: Para que o produto seja reconhecido no Winthor, o campo de referência do item (listOfOrderItem.productSKUERPReferenceKey) é montado pela concatenação do Código de Barras (EAN) com o Código do Produto (PLU), separados por hífen (e.x., items.EAN || "-" || items.Product.Plu).
Suporte a Layouts
A solução permite a integração utilizando vários layouts. O Layout 1 trabalha com Tabela de Preços, enqquanto o Layout 2 deve ser utilizado se a empresa trabalhar com Precificação por Embalagem/Caixa (quando os parâmetros 1973 e 2291 na Rotina 132 estão marcados como “Sim”)
| Totvs custom tabs box |
|---|
| tabs | Pré-requisitos e Atualizações, Configuração de Integração, Autenticação e Obtenção do Token (API), Processamento de Pedidos no iFood,Verificação da ImportaçãoComo Utilizar |
|---|
| ids | passo1,passo2,passo3,passo4,passo5 |
|---|
|
| Totvs custom tabs box items |
|---|
| default | yes |
|---|
| referencia | passo1 |
|---|
| Pré-requisitos e AtualizaçõesPara iniciar utilizar a funcionalidade, o ambiente deve estar nas versões mínimas ou superiores: Atualizar o objeto winthor-venda para a versão é necessário garantir que as seguintes rotinas e dependências estejam atualizadas: Tipo | Nome | Versão Mínima | Objeto | winthor-venda | 0.38. |
| Objeto | winthor-pedido-venda | 1.38.3.5 |
ou superior | Layout | Layout iFood |
0.20 ou superior no WSH | Rotina | Rotina 2670 | É necessário cadastrar uma Integração |
Pré-condições Adicionais: - Acesso à API do iFood.
- Produtos precificados corretamente, com estoque no Winthor e cadastrados
Os produtos devem ter sido carregados - na plataforma iFood via API Ingestion -
send items- Send Items.
- É necessário ter ao menos uma promoção de cada tipo (Desconto no Item, Desconto no Pedido, Leve X Pague Y) cadastrada na plataforma iFood e ativada.
|
| Totvs custom tabs box items |
|---|
| default | no |
|---|
| referencia | passo2 |
|---|
| Na Rotina 2650 - Configuração de Integrações, é necessário cadastrar a integração e definir os parâmetros fixos: - Crie a Integração E-commerce informando o código de layout (1 ou 2) e as filiais associadas.
- Defina os parâmetros de utilização e requisição, que são os valores fixos (Código de Cliente Padrão, Vendedor Padrão, etc.) que serão utilizados no Winthor.
| | Totvs custom tabs box items |
|---|
A aplicação dos descontos ocorre durante o processo de recepção do pedido do iFood, refletindo-se nos registros de venda do Winthor (e.g., Rotina 336). Para homologação do comportamento: - Autenticação na API iFood: Realize a autenticação seguindo os passos descritos:
| | default | no |
|---|
| referencia | passo3 |
|---|
| É necessário obter o accessToken para que o Winthor possa se comunicar com a API do iFood. Execute o endpoint/oauth/userCode para gerar um userCode e uma URL de verificação completa (verificationUrlComplete)- Execute o endpoint {{baseUrl}}/oauth/userCode para obter o userCode e o authorizationCodeVerifier
e abra-a - (verificationUrlComplete), abra no navegador
. Faça login na conta - , faça login com a conta iFood de desenvolvedor
iFood o aplicativo - /dê permissão para a loja.
- O iFood exibirá o código de autorização.
- Execute o endpoint {{baseUrl}}/oauth/token
, - preenchendo o authorizationCode (código
obtido no passo anterior- retornado após autorização) e o authorizationCodeVerifier (valor gerado no primeiro passo).
O retorno deve ser o accessToken, que será utilizado para a busca dos pedidos. |
| Totvs custom tabs box items |
|---|
| default | no |
|---|
| referencia | passo4 |
|---|
| Para que um pedido seja importado, ele precisa passar pelo fluxo de separação do iFood até atingir o status SPE (Separação Finalizada). - O pedido é gerado no iFood (e passa pelos status PLC e CFM).
- Utilize o App Separador para iniciar a separação do pedido.
- Confirme os itens, geralmente digitando os 6 últimos dígitos do Código de Barras (EAN) do produto.
- Ao clicar em Finalizar Separação, o polling do sistema iFood gera o status SPE (SEPARATION_ENDED).
- Somente com o status SPE o pedido está pronto para ser consumido e importado para o Winthor.
IMPORTANTE: É fundamental que os produtos cadastrados na loja iFood DEVAM ter o mesmo Código de Barras (EAN) e Código de Produto (CODPROD/SKU) cadastrados no Winthor. Caso contrário, será gerado um erro de produto não encontrado. |
| Totvs custom tabs box items |
|---|
|
| default | no |
|---|
| referencia | passo5 |
|---|
|
Após o pedido alcançar o status SPE, o sistema Winthor tentará a importação.
Verificação da API (Postman/Virtual Bag)
Ao executar o endpointvirtual-bag com o orderId gerado, o status esperado é 200 OK.Verificação na Rotina 2650
Na Rotina 2650, ao acessar a opção Detalhes Técnicos, a importação do pedido deve apresentar o Status S (Sucesso).
Verificação no Winthor (Rotina 336)
- Os pedidos importados são gravados no sistema Winthor com a origem de pedido "R" (Balcão Reserva).
- Os pedidos podem ser consultados e gerenciados na Rotina 336 - Alterar Pedido de Venda.
- Se a configuração Multi Filial estiver ativa na Rotina 2650, pedidos originados em uma loja iFood associada à Filial 2, por exemplo, serão recebidos corretamente na Filial 2 no Winthor.
...
- Obtenha o accessToken retornado com Status 200.
- Cadastro de Promoções: Certifique-se de que as promoções patrocinadas pela loja (Liability = PARTNER ou CHAIN) estejam cadastradas e ativas no portal iFood (https://portal.ifood.com.br/promotions/all).
- Existem três tipos principais de cadastro: Leve X Pague Y, Desconto no pedido (cupons), e Desconto no Item.
- Criação e Envio do Pedido no iFood:
- Crie um pedido que contenha itens elegíveis para o desconto desejado (Item ou Carrinho).
- Para testes, podem ser usados os cupons VOUCHER_REST (emula descontos patrocinados pela loja) e VOUCHER_IFOOD (emula descontos patrocinados pelo iFood).
- Verificação do Desconto no Virtual Bag:
- Importação e Verificação no Winthor:
- Após a importação do pedido para o Winthor, acesse, por exemplo, a Rotina 336 - Alterar Pedido de Venda.
- Valide o preço de venda (PVENDA) dos itens e o valor total na linha do item.
Exemplo de Validação (Desconto de Rodapé - target = CART) Rateio é aplicado proporcionalmente de forma que os produtos de maior valor tenham um desconto maior em relação aos demais, conforme a lógica abaixo: Produto | Vl. unitário (Bruto) | % sobre o total | Desconto Rateado (R$ 10,00 total) | Vl. unitário Líquido | A (3 un) | 9,99 | 83,38% | R$ 8,34 (total) | R$ 7,21 | B (2 un) | 2,99 | 16,62% | R$ 1,66 (total) | R$ 2,16 |
Com isso, o valor do pedido deve refletir o somatório dos totais líquidos dos itens - R$ 25,95 (não adicionando a taxa de entrega). |
|
04. DEMAIS INFORMAÇÕES
Cálculo e Filtro de Benefícios:
Para saber o valor do item com desconto, deve-se obter o valor de targetId do benefício para correlacionar com o item (bag.items com uniqueId de mesmo valor). O valor no item (prices.grossValue.value) está sem desconto, e o valor do desconto (sponsorships.amount.value do benefício) deve ser subtraído.
É necessário filtrar os benefícios em que o target seja ITEM e que possuam somente 1 elemento em sponsorships, e que este possua liability como PARTNER ou CHAIN.
| Aviso |
|---|
Importante! As versões estarão disponíveis para download no CCW. https://centraldecontrole.pcinformatica.com.br/
Mantenha suas rotinas sempre atualizadas! |
05. ASSUNTOS RELACIONADOS
