O recurso Impostos sobre produto permite integrar o checkout da Uappi a um serviço externo responsável pelo cálculo de impostos dos itens do carrinho.
Nesse fluxo, a Uappi envia os dados disponíveis do carrinho para o serviço configurado pela loja. O serviço externo realiza o cálculo e devolve o preço unitário calculado e as taxas correspondentes, que são aplicados no checkout.
O cálculo fiscal é realizado pelo serviço externo. A Uappi é responsável por enviar as informações disponíveis, receber o resultado e aplicar os valores retornados.
Importante: o recurso é exclusivo para lojas que utilizam o modelo de negócio B2B. Ele não é executado em lojas B2C ou B2B2C.
O fluxo funciona da seguinte forma:
Para isso, o ERP, integrador ou motor de cálculo deve disponibilizar um endpoint compatível com o contrato esperado pela Uappi.
A comunicação utiliza:
No fluxo do App Impostos sobre produto, a Uappi não envia autenticação adicional no header da requisição. Caso o serviço exija uma chave de acesso, a autenticação deve ser tratada pelo próprio serviço, por exemplo, por meio da URL ou de outra estratégia definida pelo integrador.
Para utilizar o cálculo de impostos sobre produtos, é necessário:
No painel administrativo:
A URL informada será utilizada pela Uappi para enviar as requisições de cálculo de impostos.
Ao realizar a consulta, a Uappi envia um JSON contendo informações dos itens, cliente, entrega e frete.
A estrutura da requisição é organizada conforme apresentado abaixo:
Importante: a modalidadePedido enviada atualmente pela integração é consumo.
Cada objeto de itens pode conter:
| Campo | Descrição |
| indice | Identificador do item no carrinho. Deve ser devolvido pelo integrador exatamente como recebido |
| id | ID do produto na Uappi |
| sku | SKU do produto |
| tipo | Tipo do item: produto ou servico |
| quantidade | Quantidade considerada no cálculo |
| valor | Preço unitário antes da aplicação do imposto |
| valorFrete | Valor do frete correspondente ao item. Pode ser null quando não houver um valor numérico disponível. |
| ean | Campo destinado ao EAN do item. Atualmente, pode ser enviado vazio (“”). |
| idMarca | Identificador da marca |
| idCategoria | Identificador da categoria |
| armazem.cep | CEP do armazém de origem |
| armazem.codigo | Código do armazém |
O campo indice é utilizado pela Uappi para relacionar o item enviado ao resultado retornado pelo serviço. Por isso, o mesmo valor recebido deve ser devolvido na resposta.
Quando disponíveis, são enviados dados cadastrais e tributários do cliente, como:
O campo statusTributario pode utilizar:
O campo naturezaJuridica utiliza:
A Uappi também envia informações relacionadas ao destino da entrega e à origem do produto.
Entre elas estão:
O CEP de entrega é necessário para a consulta do App.
Atenção: sem um CEP de entrega informado, a Uappi não realiza a chamada ao serviço de cálculo. Em operações com multiestoque, o item também precisa possuir frete calculado para ser enviado na consulta. Por isso, durante a homologação, realize os testes com CEP informado e frete calculado.
O cadastro e as regras fiscais necessárias para realizar o cálculo devem estar disponíveis no próprio ERP, integrador ou motor externo.
Nesta integração, a Uappi não envia informações como:
Para localizar o cadastro fiscal correspondente ao produto, o serviço externo pode utilizar informações enviadas pela Uappi, como sku ou id.
Importante: o serviço externo é responsável pela regra e pelo cálculo fiscal. A Uappi utiliza o resultado devolvido para atualizar o checkout.
Para cada item recebido, o serviço externo deve retornar um objeto correspondente dentro de taxasItens.
Importante: os nomes das taxas apresentados são apenas ilustrativos. O campo nome é livre e não possui uma lista fixa de impostos definida pela Uappi.
| Campo | Descrição |
| id | ID numérico do produto |
| indice | Deve ser exatamente o mesmo indice recebido na requisição |
| precoOriginal | Preço unitário original recebido pela integração |
| precoFinal | Preço unitário que deverá ser utilizado após o cálculo |
| taxas | Lista das taxas aplicadas |
Cada objeto de taxas deve possuir:
| Campo | Descrição |
| nome | Nome da taxa. Obrigatório quando houver imposto |
| valor | Valor da taxa. Obrigatório quando houver imposto |
| descricao | Descrição adicional da taxa. Campo opcional |
Quando houver alteração de preço, o retorno deve conter pelo menos uma taxa válida. Uma resposta com precoFinal diferente de precoOriginal e taxas vazio pode até ter o preço processado, mas o item permanece inválido para a conclusão da compra e pode bloquear a finalização do checkout.
Atenção: precoOriginal e precoFinal representam valores unitários. Não envie em precoFinal o valor total do item multiplicado pela quantidade.
Por exemplo, para um produto com:
o checkout utilizará 2 × R$ 118,00.
Mesmo quando não houver imposto a aplicar ao item, o serviço deve retornar uma resposta válida utilizando HTTP 200.
Nesse caso, precoOriginal e precoFinal devem possuir o mesmo valor e taxas deve ser um array vazio.
Quando os preços são iguais e não existem taxas, a venda pode continuar normalmente sem a exibição do detalhamento de impostos.
Quando o precoFinal retornado pelo integrador é diferente do preço original, a Uappi utiliza esse valor como novo preço unitário do produto no checkout.
O imposto, portanto, não é acrescentado como uma linha separada ao total da compra. O valor retornado passa a compor o preço do próprio item.
Quando houver taxas aplicadas, o checkout pode apresentar o indicador Impostos, permitindo visualizar o detalhamento retornado pelo integrador.
O cálculo considera itens dos tipos:
Itens configurados como brinde não participam do cálculo.
O frete também pode fazer parte das informações utilizadas pelo motor:
A consulta ao serviço externo acontece durante a jornada do checkout sempre que a plataforma precisa obter ou atualizar as informações de imposto dos itens elegíveis.
Entre os cenários identificados estão:
O objetivo é garantir que os itens elegíveis estejam com o cálculo sincronizado antes da finalização da compra.
O retorno do serviço precisa utilizar HTTP 200 e possuir uma estrutura JSON válida.
Respostas com outros status HTTP, timeout ou JSON inválido não são utilizadas para aplicação dos impostos. Nesses casos, o item pode permanecer sem cálculo e impedir a finalização da compra.
Quando ocorre uma falha de sincronização, o checkout pode apresentar:
Houve um problema na sincronização dos impostos. Clique aqui para sincronizar novamente!
Ao solicitar a nova sincronização, o checkout realiza uma nova tentativa de consulta.
Antes de concluir a compra, a Uappi verifica se os itens que precisam participar do cálculo possuem uma resposta correspondente.
O indice retornado pelo serviço deve ser exatamente igual ao recebido na requisição. Caso contrário, a Uappi não consegue relacionar o resultado ao item do carrinho.
Se um item permanecer sem imposto calculado, a finalização pode ser bloqueada com a mensagem:
Um ou mais produtos do carrinho, não possuem imposto calculado.
Quando existe diferença entre precoOriginal e precoFinal, a Uappi armazena as informações relacionadas ao cálculo junto ao pedido.
Entre os dados registrados estão:
A persistência dessas informações é realizada pela própria Uappi após a geração do pedido.
O detalhamento pode ser apresentado posteriormente no pedido do painel administrativo e na área Minha Conta do cliente enquanto o recurso de cálculo de impostos permanecer ativo.
Antes de colocar a integração em produção, valide se:
Um item enviado e não retornado corretamente pode permanecer sem imposto e bloquear a finalização do checkout.
Em quais modelos de negócio o cálculo de impostos sobre produtos funciona?
O recurso é exclusivo para lojas configuradas no modelo de negócio B2B. Ele não é executado em lojas B2C ou B2B2C.
Sim. A URL de consulta configurada no App deve apontar para um serviço compatível com o contrato da integração.
Esse serviço receberá os dados enviados pela Uappi, realizará o cálculo e devolverá o resultado.
Não. O cálculo fiscal é responsabilidade do serviço externo. A Uappi envia as informações disponíveis e aplica os valores retornados pelo motor no checkout.
Não. Essas informações não fazem parte do payload desta integração. O serviço externo deve possuir o cadastro e as regras fiscais necessárias e pode utilizar informações como sku ou id para identificar o produto.
Unitário.
A Uappi utiliza precoFinal como preço unitário do produto. A quantidade é considerada posteriormente na totalização do checkout.
O item ainda deve ser devolvido dentro de taxasItens, utilizando o mesmo indice, com precoFinal igual a precoOriginal e taxas como um array vazio.
O item pode permanecer sem imposto calculado. Se a Uappi não conseguir relacionar o retorno ao item correspondente, a finalização da compra pode ser bloqueada.
Não. Itens configurados como brinde não participam da consulta de impostos.
Não. A integração trata do cálculo dos valores que serão utilizados no checkout. A emissão fiscal não faz parte da responsabilidade desse motor.
Deixe um comentário