Módulo: Comercial › PDV
Caminho de acesso: Menu Principal › Configurações › Rotinas › Configuração Integração PDV
Você encontra neste artigo:
O que é e para que serve
A tela Configuração Integração PDV reúne as credenciais, as empresas participantes e o acompanhamento da integração entre o Sankhya Om e o Portal PDV (Ponto de Venda). A integração funciona em dois sentidos independentes: o Sankhya Om exporta cadastros (produtos, parceiros, preços, regras tributárias e outros) para o Portal PDV, e o Portal PDV devolve ao Sankhya Om as vendas, trocas, cancelamentos, inutilizações e movimentações de caixa para escrituração. Serve para implantadores, consultores e times de TI que configuram, mantêm ou personalizam a integração. A tela não cadastra produtos, preços nem regras tributárias — esses dados vêm das telas de cadastro do Sankhya Om — e não configura o aplicativo do caixa.
Antes de começar
- Tenha em mãos a API Key e o API Secret emitidos para o ambiente da base: homologação ou produção.
- Confirme que cada empresa participante tem uma nota modelo cuja TOP (Tipo de Operação) use o modelo de documento 65 (Nota Fiscal de Consumidor Eletrônica — NFC-e) e operação presencial.
- Preencha o campo CPF no Cadastro de Usuários de todas as pessoas que vão operar o caixa. Acesse Identificação do operador do caixa.
- Confirme que as rotinas automáticas da integração estão ativas. Acesse Rotinas automáticas.
Aba Configuração
A aba Configuração reúne as credenciais de acesso à API (Interface de Programação de Aplicações) do Portal PDV e a grade de entidades, que mostra a situação da exportação de cada cadastro.
Credenciais de acesso à API
API Key e API Secret
O que faz
Autenticam o Sankhya Om na API do Portal PDV. A API Key é a chave pública: identifica a instalação e segue no cabeçalho X-Api-Key de cada requisição. O API Secret é a chave privada: gera a assinatura HMAC (Hash-based Message Authentication Code) de cada requisição e garante a integridade e a autenticidade da chamada.
Quando usar
Use na implantação da integração e sempre que as credenciais forem renovadas ou a base mudar de ambiente.
Como funciona
Não há campo de URL para preencher: os endereços do Portal PDV são fixos por ambiente, e cada instalação se comunica automaticamente com o ambiente correspondente à sua base, conforme a configuração da base no SAS. Uma base de homologação nunca aponta para a API de produção, nem o contrário.
Ao salvar, o Sankhya Om testa a credencial no ambiente correspondente e exibe o resultado:
| Resultado | O que significa | O que fazer |
|---|---|---|
| "Credencial confirmada" | O ambiente testou e aceitou a credencial. | Nenhuma ação necessária. |
| "Credencial recusada" | O ambiente recusou a credencial. Nenhum evento do PDV é consumido até a correção. | Confira se a API Key e o API Secret são os emitidos para o ambiente da base. |
| "Serviço indisponível ou inalcançável" | Não foi possível confirmar a credencial. Pode ser uma condição temporária. | Aguarde. O consumo de eventos volta a funcionar quando o serviço responder ou a conexão for restabelecida. |
| "Credencial ausente" | A API Key e o API Secret não foram informados. Nada foi verificado e nenhum evento é consumido. | Preencha as duas chaves e salve novamente. |
O resultado é um aviso, não um bloqueio: as configurações são salvas mesmo quando a credencial não é confirmada.
Configurações relacionadas
| Necessidade | Onde configurar |
|---|---|
| Alterar a API Key e o API Secret | Só o usuário administrador (SUP) edita esses campos. Os demais usuários visualizam a tela, mas não alteram as chaves. |
| Definir o ambiente da base (homologação ou produção) | Configuração da base no SAS |
|
⚠️ Atenção Use a API Key e o API Secret emitidos para o ambiente da base: credenciais de homologação não são aceitas em produção, e vice-versa. Se a base for promovida de homologação para produção, substitua as credenciais pelas de produção. |
Outros campos
- Top Integração NFCe — campo sem uso. Ainda aparece na tela, mas não interfere na integração: a TOP usada é sempre a da Nota Modelo de cada empresa. Acesse Nota Modelo.
Grade de entidades
A grade de entidades mostra a situação da exportação de cada entidade de dados (Produtos, Clientes etc.). A ordem e os requisitos de cada entidade estão em Entidades exportadas.
- Último Retorno — resposta da última comunicação com a API para a entidade. Como o envio é feito em lotes, mostra o retorno do último lote processado. É o primeiro lugar a consultar quando algo falha.
Carga Completa
O que faz
Indica se a entidade ainda precisa passar pela sincronização inicial completa.
Quando usar
Use para acompanhar a carga inicial de cada entidade. Marque Sim manualmente só quando precisar reenviar todos os registros da entidade, depois de combinar com a equipe do Portal PDV.
Como funciona
- Sim: a entidade ainda não passou pela carga inicial. O processo tenta enviar todos os registros válidos.
- Não: a carga inicial já foi concluída. O processo passa a monitorar só alterações e exclusões e envia também os registros criados depois da carga.
Impacto no sistema
Ao alterar para Sim e salvar, o Sankhya Om apaga todo o histórico de integração da entidade e reenvia todos os registros ao Portal PDV.
|
⚠️ Atenção A alteração para Sim apaga o histórico de integração da entidade e não pode ser desfeita. Combine o reenvio com a equipe do Portal PDV antes: a API pode recusar registros que já existem do lado do Portal PDV se eles não forem removidos antes. |
View Adicional
O que faz
Ativa o uso da VIEW personalizada da instalação para a entidade, no lugar da VIEW padrão.
Quando usar
Use quando a instalação precisa de uma regra de negócio própria na extração dos dados da entidade.
Como funciona
- Desmarcada: o Sankhya Om lê a VIEW padrão — por exemplo, VW_PORTALPDV_CLIENTE. É o comportamento normal.
- Marcada: o Sankhya Om lê só a VIEW personalizada, com sufixo
_AD— por exemplo, VW_PORTALPDV_CLIENTE_AD. Se essa VIEW não existir, a entidade falha no ciclo e o erro aparece em Último Retorno, com o nome da VIEW que faltou.
A exportação de imagens de produtos e as VIEWs de exclusão (_DLT) não aceitam VIEW personalizada. A tela avisa quando View Adicional é marcada para a entidade de imagens.
Configurações relacionadas
| Necessidade | Onde configurar |
|---|---|
Criar a VIEW _AD com a estrutura de colunas esperada |
Banco de dados. Acesse Personalização com VIEWs. |
|
⚠️ Atenção Crie a VIEW |
Aba Configuração por empresa
Na aba Configuração por empresa, você cadastra as empresas que participam da integração. Cada empresa define onde as vendas, trocas e movimentações de caixa daquele PDV são escrituradas no Sankhya Om.
Dados da empresa
- Empresa — código da empresa no Sankhya Om (TSIEMP).
- Banco e Agência — usados no cadastro automático da conta do PDV.
- Conta Tesouraria — conta de tesouraria que recebe os lançamentos financeiros do PDV.
- Usuário — usuário do Sankhya Om responsável pelos registros que a integração cria para a empresa. Não identifica o operador do caixa: Acesse Identificação do operador do caixa.
- Nota Modelo Troca — opcional. Nota usada como modelo na escrituração das trocas. Só é validada quando preenchida.
- Local Padrão Troca — opcional. Local de estoque padrão para a devolução de mercadorias em trocas.
Ao salvar, o Sankhya Om valida cada código informado no cadastro correspondente. Se algum código não existir ou estiver inativo, nada é salvo e a tela exibe a lista de campos com problema.
Nota Modelo
O que faz
Define a nota usada como modelo na escrituração das vendas do PDV e, com ela, a TOP da integração.
Quando usar
Use para toda empresa participante. Não há campo específico para a TOP: a integração usa sempre a TOP da Nota Modelo.
Como funciona
A lista mostra só notas cuja TOP usa o modelo de documento 65 (NFC-e) e o Indicador de Presença de operação presencial — basta escolher a nota modelo correta. Da TOP dessa nota vem o Indicador de Presença, exportado com as Regras Tributárias: ele informa ao PDV em que condição a venda ocorre e aparece no campo indPres do XML (Extensible Markup Language) da NFC-e.
Impacto no sistema
Escrituração das vendas do PDV e Indicador de Presença enviado nas Regras Tributárias.
Aba Processamento
A aba Processamento lista os eventos recebidos do PDV, para acompanhamento e diagnóstico. Use a lista para responder a perguntas como "a venda do cupom X chegou?" e "por que ela não foi escriturada?". Cada linha corresponde a um evento e mostra, entre outras informações:
- Identificador, ID Caixa e Operação
- Status — situação do evento. Acesse Situações de um evento.
- Data de Recebimento e Data de Processamento
- Número de Tentativas
- Mensagem de Erro, quando houver
- Conteúdo JSON (JavaScript Object Notation) original recebido
Caminho de um evento
Toda operação feita no PDV volta para o Sankhya Om para ser escriturada. O retorno é assíncrono: o PDV não espera a resposta do Sankhya Om para concluir a operação no caixa.
- A operação é feita no PDV e publicada na fila de mensageria do Portal PDV.
- O Sankhya Om consome a fila e grava o conteúdo recebido, ainda sem tratamento, na tabela de entrada TPPSQS.
- Uma rotina lê os registros pendentes da tabela de entrada e os transfere para a tabela de processamento TPPINT, já identificando o tipo de operação.
- Rotinas específicas, uma para cada tipo de operação, processam os registros pendentes e fazem a escrituração no Sankhya Om.
O uso de duas tabelas garante que uma falha na escrituração nunca cause a perda do evento: o conteúdo original continua gravado e o registro pode ser processado novamente.
Tipos de operação
Cada evento recebido é classificado em um dos tipos abaixo, que define qual rotina vai processá-lo.
| Tipo | Descrição |
|---|---|
| VENDA | Venda feita no PDV. É escriturada a partir do XML da NFC-e e da Nota Modelo da empresa. |
| TROCA | Troca ou devolução de mercadoria. É escriturada com base na Nota Modelo Troca e no Local Padrão Troca da empresa. |
| CANCELAMENTO | Cancelamento de um documento emitido pelo PDV. |
| INUTILIZACAO | Inutilização de numeração fiscal. |
| MOV_CAIXA | Movimentações do caixa, como sangrias, suprimentos e fechamento, com a conferência dos valores apurados por espécie de pagamento. |
Situações de um evento
| Status | Descrição |
|---|---|
| PENDENTE | Recebido, aguardando processamento. |
| PROCESSADO | Escriturado com sucesso no Sankhya Om. |
| ERRO | O processamento falhou. A mensagem de erro fica registrada na própria linha, e o número de tentativas é contabilizado. |
| SEM_PROCESSADOR | O evento chegou com um tipo de operação que nenhuma rotina sabe tratar. Normalmente indica incompatibilidade de versão entre o Portal PDV e o módulo do Sankhya Om. |
Um evento com ERRO não bloqueia os demais: cada registro é processado de forma isolada.
Entidades exportadas
A exportação de cadastros funciona assim:
- Um conjunto de VIEWs prepara os dados de cada entidade.
- Um processo Java (PortalPDVHelper) lê essas VIEWs, monta os objetos JSON e os envia para a API.
- O Sankhya Om guarda um hash do conteúdo de cada registro. A comparação desse hash identifica se um registro é novo ou alterado e evita reenviar o que não mudou.
- O envio é feito em lotes. As entidades são processadas em paralelo, respeitando a ordem de dependência entre elas: uma entidade só é enviada depois das entidades que ela referencia.
| Nº | Entidade | VIEW | Endpoint |
|---|---|---|---|
| 1 | Empresas | VW_PORTALPDV_EMPRESA | /empresas |
| 2 | Regiões | VW_PORTALPDV_REGIAO | /regioes |
| 3 | Perfis | VW_PORTALPDV_PERFIL | /perfis |
| 4 | Clientes | VW_PORTALPDV_CLIENTE | /clientes |
| 5 | Produtos | VW_PORTALPDV_PRODUTO | /produtos |
| 6 | Tabela de Preço | VW_PORTALPDV_TAB_PRECO_FIN | /precos-contexto |
| 7 | Prioridades Tributárias | VW_PORTALPDV_PRI_TRIB | /prioridades-tributarias |
| 8 | Impostos Federais | VW_PORTALPDV_IMP_FED | /impostos-federais |
| 9 | Regras Tributárias | VW_PORTALPDV_REGRA_TRIB | /regras-tributarias |
| 10 | Imposto CBS | VW_PORTALPDV_IMPOSTO_CBS | /impostos-reforma-cbs |
| 11 | Imposto IBS | VW_PORTALPDV_IMPOSTO_IBS | /impostos-reforma-ibs |
| 12 | Notas Técnicas | VW_PORTALPDV_NOTA_TECNICA | /notas-tecnicas |
| 13 | Promoções | VW_PORTALPDV_PROMOCAO | /promocoes |
| 14 | Vendedores | VW_PORTALPDV_VENDEDOR | /vendedores |
As imagens de produto seguem um fluxo próprio, porque transportam conteúdo binário. Acesse Imagens de Produtos.
|
ℹ️ Nota Algumas VIEWs usam nomes abreviados (IMP_FED, REGRA_TRIB, PRI_TRIB) porque o banco de dados limita a quantidade de caracteres no nome de um objeto. |
Empresas
VIEW: VW_PORTALPDV_EMPRESA. Cada registro representa uma empresa cadastrada na Aba Configuração por empresa, com os dados cadastrais e o objeto aninhado endereco. É a primeira entidade enviada, porque quase todas as outras dependem dela.
- Origem dos dados: TSIEMP (cadastro da empresa) e TPPEMP (empresas selecionadas para a integração, com banco, agência, conta e notas modelo). Endereço em TSIEND, TSIBAI, TSICID, TSIUFS e TSIPAI.
- Requisitos para integração: a empresa está cadastrada na tela de configuração da integração, e os dados de endereço estão preenchidos no cadastro da empresa.
Regiões e Perfis de Cliente
VIEWs: VW_PORTALPDV_REGIAO e VW_PORTALPDV_PERFIL. Objetos simples e planos, só com os dados básicos da entidade.
- Origem dos dados: Regiões em TSIREG; Perfis de Cliente em TGFTPP (Tipo de Parceiro).
- Requisitos para integração: o registro existe na tabela correspondente e está ativo.
Clientes
VIEW: VW_PORTALPDV_CLIENTE. O objeto reúne os dados principais do parceiro e dois arrays aninhados: enderecos e contatos. A VIEW retorna uma linha para cada contato do parceiro (forma desnormalizada), e a aplicação agrupa essas linhas em um único objeto, com os arrays preenchidos.
- Origem dos dados: TGFPAR (nome, razão social, CNPJ/CPF etc.); endereço principal em TSIEND, TSIBAI, TSICID e TSIUFS; contatos em TGFCTT.
- Requisitos para integração:
- Parceiro ativo (ATIVO = 'S') e marcado como cliente (CLIENTE = 'S').
- Endereço principal completo: logradouro, número, bairro, cidade, UF (Unidade Federativa) e CEP (Código de Endereçamento Postal).
- Dados de identificação preenchidos: razão social, nome, CNPJ (Cadastro Nacional da Pessoa Jurídica) ou CPF (Cadastro de Pessoas Físicas) e inscrição estadual.
Produtos
VIEW: VW_PORTALPDV_PRODUTO. O objeto tem um corpo principal com os dados do produto e objetos aninhados para unidadePadrao, produtoImposto e grupo. O destaque é o array produtoUnidades, que representa as diferentes formas de venda de um mesmo item.
- Regra de unidades: se o produto tem unidades de venda alternativas ativas (TGFVOA), todas entram no array. Se não tem nenhuma, a unidade padrão (TGFPRO.UNIDADE) é incluída automaticamente, para que todo produto integrado tenha ao menos uma unidade de venda.
- Chave composta: a chaveERP de cada item de produtoUnidades é formada por CODPROD|CODVOL|CONTROLE, o que garante a unicidade.
- Origem dos dados: TGFPRO (descrição, pesos, NCM etc.); preço — último preço de venda vigente — em TGFEXC com TGFTAB; grupo em TGFGRU; unidades em TGFVOA e TGFVOL.
- Requisitos para integração:
- Produto ativo (ATIVO = 'S') e para revenda (USOPROD = 'R').
- Peso bruto e peso líquido maiores que zero.
- Unidade padrão definida.
- Grupo de produtos ativo.
- Ao menos um preço de venda cadastrado e vigente em TGFEXC.
Imagens de Produtos
VIEW: VW_PORTALPDV_IMAGENS. As imagens seguem um fluxo separado, porque transportam conteúdo binário em vez de um objeto JSON comum. Cada registro corresponde à imagem principal de um produto, e a chave é o código do produto com o sufixo _principal.
- Origem dos dados: repositório de imagens do Sankhya Om; produtos elegíveis em TGFPRO, TGFGRU, TGFEXC e TGFTAB, com os mesmos critérios do cadastro de produtos.
- Requisitos para integração: o produto é válido pelos critérios de Produtos e tem imagem cadastrada.
Esta é a única entidade que não aceita VIEW personalizada (_AD).
Preços
VIEW: VW_PORTALPDV_TAB_PRECO_FIN. Cada registro representa um contexto de preço. A lógica reúne diferentes cenários de precificação — por parceiro, por região, por perfil etc. — em uma única consulta, e o objeto final é plano, com o preço calculado de um produto dentro de um desses contextos. A VIEW é a camada final, montada a partir de VW_PORTALPDV_TABELA_PRECO, e é a única entidade cujos registros não são agrupados: cada linha vira um objeto.
- Origem dos dados: contextos em TGFPAEM (Parceiro/Empresa), TGFPAR (Parceiro), TGFTPP (Perfil de Parceiro) e TSIREG (Região). A consulta usa as VIEWs de produtos, clientes e regiões para gerar preços só para entidades que já foram ou serão integradas. O cálculo usa a função SNK_PRECO.
- Requisitos para integração: o preço calculado por SNK_PRECO é maior que zero, e o contexto (produto, parceiro, região etc.) é válido e está ativo.
Como o PDV usa as entidades tributárias
Prioridades Tributárias, Impostos Federais, Regras Tributárias e Impostos da Reforma Tributária determinam os tributos calculados e os valores no XML da NFC-e emitida no caixa.
O PDV calcula os impostos localmente, no próprio dispositivo, usando só o que foi exportado pelo Sankhya Om — não há consulta ao Sankhya Om durante a venda para buscar uma alíquota ausente. Isso permite que o caixa continue vendendo sem internet, mas tem três consequências:
- Se uma regra não foi exportada, o PDV não consegue aplicá-la.
- Uma alteração no Sankhya Om só vale no caixa depois que o ciclo de exportação a envia e o PDV a recebe.
- Um erro de cadastro no Sankhya Om passa para o documento fiscal e só aparece na emissão.
O cálculo no PDV segue sempre a mesma sequência:
- Reúne as configurações tributárias aplicáveis à venda.
- Calcula os impostos item a item.
- Gera o XML da NFC-e, que é validado e assinado digitalmente.
Para que uma venda seja tributada corretamente no PDV, confira nesta ordem:
- Cada empresa tem Nota Modelo cadastrada, porque a TOP dela fornece o Indicador de Presença.
- Existem Regras Tributárias de ICMS (Imposto sobre Circulação de Mercadorias e Serviços) para cada par de UF de origem (empresa) e UF de destino (parceiro) praticado na loja.
- Existem Prioridades Tributárias para esses mesmos pares, definindo qual regra vale quando mais de uma se aplica.
- Existem Impostos Federais — PIS (Programa de Integração Social) e COFINS (Contribuição para o Financiamento da Seguridade Social) — para as empresas e os parceiros envolvidos, ou regras globais que os cubram.
- Se a empresa já opera na Reforma Tributária, a Nota Técnica correspondente está ativa e existem alíquotas de CBS (Contribuição sobre Bens e Serviços) e IBS (Imposto sobre Bens e Serviços) para os NCMs (Nomenclatura Comum do Mercosul) vendidos.
Depois de ajustar qualquer um desses cadastros, aguarde o ciclo de exportação e confirme, na Grade de entidades, que Último Retorno não mostra erro.
Prioridades Tributárias
VIEW: VW_PORTALPDV_PRI_TRIB. Representa a ordem de aplicação das regras tributárias em um contexto de operação. A chaveERP é formada por UF_ORIGEM|UF_DESTINO|PRIORIDADE.
- Origem dos dados: TGFPRI. A VIEW busca os pares (UFORIG, UFDEST) existentes em TGFICM que sejam válidos — com origem em uma empresa integrada e destino em um parceiro integrado — e integra só as prioridades desses contextos.
- Requisitos para integração: a prioridade está vinculada a um contexto de operação (UF de origem × UF de destino) que existe em ao menos uma regra tributária válida em TGFICM, e os tipos de restrição (TIPRESTRICAO1, TIPRESTRICAO2) não são do tipo 'O'.
Efeito no PDV: é comum que mais de uma regra de ICMS se aplique ao mesmo item — uma genérica para a UF, outra para um grupo de produtos, outra para um parceiro. A prioridade é o critério de desempate e define qual regra vale. Se as prioridades não forem exportadas ou estiverem incompletas para um par de UFs, o PDV pode aplicar uma regra diferente da esperada, com CST (Código de Situação Tributária) ou alíquota de ICMS divergentes no XML. Ao analisar um cupom com tributação inesperada, confira a ordem de prioridade antes de revisar a regra em si.
Impostos Federais
VIEW: VW_PORTALPDV_IMP_FED. Objeto plano que representa uma regra de PIS ou COFINS. A chaveERP é a concatenação de CODEMP, CODPARC, GRUPOIMP e NOMEIMP. Se CODEMP ou CODPARC for 0, a VIEW trata a regra como global e envia empresaChaveERP e clienteChaveERP como nulos, conforme o contrato da API.
- Origem dos dados: TGFIFE.
- Requisitos para integração:
- O imposto é 'PIS' ou 'COFINS'.
- O tipo de operação (ENTSAI) é 'S' (Saída) ou 'A' (Ambos).
- A empresa e o parceiro da regra são 0 ou existem nas VIEWs de integração correspondentes.
Efeito no PDV: essas regras geram os valores de PIS e COFINS de cada item do cupom, com o respectivo CST, nos grupos correspondentes do XML. Regras globais são o caminho mais simples de manter: uma única regra vale para todas as empresas e parceiros, e só as exceções reais precisam de cadastro.
|
⚠️ Atenção Se um item não encontrar nenhuma regra aplicável, PIS e COFINS saem zerados no documento. Isso costuma ser percebido só na conferência fiscal, e não no caixa. |
Regras Tributárias
VIEW: VW_PORTALPDV_REGRA_TRIB. Cada registro representa uma regra de ICMS, e a lógica gera só uma regra por chave.
- Chave composta: UF_ORIGEM|UF_DESTINO|TIPO_RESTRICAO1|COD_RESTRICAO1|TIPO_RESTRICAO2|COD_RESTRICAO2.
- Campos calculados: cfop é calculado a partir da igualdade entre as UFs de origem e destino e do perfil do parceiro; regimeTributario vem da primeira empresa integrada; consumidorFinal é derivado do campo CLASSIFICMS de TGFPAR.
- Origem dos dados: TGFICM; dados complementares em TGFPRI (prioridade), TSIUFS (UFs), TGFPAR (consumidorFinal), TSIEMP (regimeTributario), TGFTOP e TSICFG (indPresenca).
- Requisitos para integração: a regra está associada a uma UF de origem de uma empresa integrada e a uma UF de destino de um parceiro integrado.
Efeito no PDV: a entidade define a tributação de ICMS do item — o CST (ou o CSOSN, Código de Situação da Operação no Simples Nacional), a alíquota, a base de cálculo e a alíquota de substituição tributária —, além do CFOP (Código Fiscal de Operações e Prestações) e do Indicador de Presença gravados no XML. Na configuração, observe:
- O CFOP depende da comparação entre a UF da empresa e a UF do parceiro, combinada com o perfil do parceiro (consumidor final ou revenda). Um parceiro cadastrado com o perfil errado muda o CFOP do cupom.
- O regime tributário vem do cadastro da empresa e define se o documento sai com CST ou CSOSN.
- Vendas para consumidor não identificado usam a UF da própria empresa. Uma venda com parceiro identificado de outro estado usa a UF desse parceiro e precisa de regra cadastrada para esse par.
|
⚠️ Atenção Se faltar regra para um par de UFs praticado na loja, o item fica sem tributação de ICMS definida e o documento pode ser rejeitado pela SEFAZ (Secretaria da Fazenda). |
Impostos da Reforma Tributária: CBS e IBS
VIEWs: VW_PORTALPDV_IMPOSTO_CBS e VW_PORTALPDV_IMPOSTO_IBS — duas entidades distintas, com a mesma estrutura. Cada registro representa uma alíquota da Reforma Tributária aplicável a um contexto de produto, empresa e parceiro, e alimenta o cálculo de CBS e IBS no cupom emitido pelo PDV.
- Origem dos dados: CBS em TLFALIQCBS; IBS em TLFALIQIBS; contexto geográfico em TSICID e TSIUFS.
- Requisitos para integração: a alíquota está vinculada a produtos, empresas e parceiros já válidos para a integração, e o contexto de cidade e UF está cadastrado corretamente.
Efeito no PDV: para que CBS e IBS apareçam no XML, duas condições independentes precisam ser atendidas:
- Nota Técnica ativa: o PDV só calcula os tributos da reforma se a Nota Técnica 2025.002-RTC estiver cadastrada e ativa para a empresa emitente. Sem ela, o XML sai sem os grupos de CBS e IBS, mesmo com as alíquotas já exportadas. Acesse Notas Técnicas.
- Alíquota cadastrada: a busca usa a combinação de empresa, município, UF e NCM do produto.
Consequências práticas da busca de alíquota:
- O NCM precisa estar preenchido no cadastro do produto. Sem NCM, não é possível localizar a alíquota.
- A alíquota pode ser cadastrada sem empresa, como regra geral, ou para uma empresa específica. Quando existe cadastro específico para a empresa, ele prevalece.
- As alíquotas variam por município e UF. Uma rede com lojas em praças diferentes precisa de cadastro para cada praça onde emite.
Se não houver alíquota para a combinação, o item sai sem os valores da reforma, mesmo com a Nota Técnica ativa.
|
💡 Dica Ao homologar a reforma em uma loja, emita um cupom de teste com os NCMs mais vendidos e confira os grupos de CBS e IBS no XML antes de liberar a operação. |
Notas Técnicas
VIEW: VW_PORTALPDV_NOTA_TECNICA. Reúne, no array notasTecnicas, as notas técnicas aplicáveis a cada empresa integrada. O documento emitido pelo PDV é a NFC-e (modelo 65), e estas notas técnicas controlam o leiaute dela.
Mais do que informativa, a entidade ativa e desativa funcionalidades fiscais no caixa. O uso atual é a Reforma Tributária: a Nota Técnica 2025.002-RTC precisa estar cadastrada e ativa para a empresa emitente. Como a verificação é feita a cada emissão, ativar ou inativar a nota técnica no Sankhya Om muda o comportamento do caixa assim que a informação é sincronizada, sem atualizar o aplicativo.
- Origem dos dados: TGFNFENT; opções e campos em TDDCAM e TDDOPC.
- Requisitos para integração: a nota técnica está ativa (ATIVONT = 'S') e associada a uma empresa integrada.
Para ativar a Reforma Tributária em uma empresa:
- Cadastre a Nota Técnica 2025.002-RTC para a empresa.
- Deixe a nota técnica ativa.
- Aguarde o ciclo de exportação.
- Emita um cupom de teste e confirme que os grupos de CBS e IBS aparecem no XML.
Para desativar, inative a nota técnica.
Promoções
VIEW: VW_PORTALPDV_PROMOCAO. Cada registro representa uma promoção aplicável no PDV, com os produtos e as condições envolvidos, detalhados no array detalhes. É uma das entidades com mais dependências: a VIEW usa as VIEWs de empresas, clientes, produtos e preços e só envia a promoção quando todos os elementos referenciados também estão integrados.
- Origem dos dados: cadastro de promoções do Sankhya Om; entidades relacionadas em VW_PORTALPDV_EMPRESA, VW_PORTALPDV_CLIENTE, VW_PORTALPDV_PRODUTO e VW_PORTALPDV_TAB_PRECO_FIN.
- Requisitos para integração: a promoção está vigente e se enquadra em um dos seis tipos reconhecidos, e os produtos, parceiros e empresas referenciados são válidos para a integração.
O PDV aplica a promoção automaticamente quando o item (ou o parceiro) atende aos critérios. O tipo não é escolhido em um campo: ele é definido pela forma como a promoção foi preenchida no Sankhya Om, na ordem abaixo. O primeiro critério atendido define o tipo.
| Nº | Tipo | Como configurar no Sankhya Om |
|---|---|---|
| 1 | Leve X Pague Y | Marque a promoção para usar desconto especial. É o único tipo com faixas de leve e pague. |
| 2 | Desconto por Quantidade | Marque a promoção para usar desconto por quantidade ou cadastre faixas de quantidade. Cada faixa define a quantidade mínima e o desconto correspondente. |
| 3 | Desconto por Produto | Informe um produto específico. |
| 4 | Desconto por Grupo de Produto | Informe um grupo de desconto de produto. |
| 5 | Desconto por Cliente | Informe um parceiro específico. Só é aplicada quando esse parceiro está identificado na venda. |
| 6 | Desconto por Grupo de Clientes | Informe um grupo de desconto de parceiro. |
Nos tipos 2 a 6, o desconto pode ser percentual ou em valor:
- Com percentual preenchido, a promoção é exportada como percentual.
- Com só o valor preenchido, é exportada como valor.
- No desconto por valor, o número informado é o preço final do item, e não um abatimento sobre o preço de tabela.
|
⚠️ Atenção Preencha só o critério do tipo desejado. Como o tipo é definido na ordem da tabela, preencher mais de um critério na mesma promoção faz prevalecer o primeiro. Por exemplo, uma promoção com produto e grupo de produto preenchidos é exportada como Desconto por Produto. |
Exemplo — Leve 3, Pague 2: um produto vendido a R$ 89,40 vai entrar na campanha. No Sankhya Om, cadastre a promoção marcada para usar desconto especial (tipo 1), com a faixa de desconto especial "leve 3, pague 2" e com data de início e fim cobrindo o período da campanha. No caixa, se o cliente levar 4 unidades, o PDV forma um ciclo completo de 3 unidades com desconto e cobra a quarta pelo preço normal:
- Cada unidade do ciclo: R$ 89,40 × 2/3 = R$ 59,60.
- Total da compra: 3 × R$ 59,60 + R$ 89,40 = R$ 268,20.
Exemplo — Desconto por Quantidade: um refrigerante de R$ 10,50 tem faixas de 10% a partir de 2 unidades e 20% a partir de 5 unidades. Cadastre as duas faixas de quantidade na mesma promoção. No caixa, 2 unidades saem a R$ 9,45 cada, e 5 unidades saem a R$ 8,40 cada, porque a faixa maior prevalece assim que a quantidade a atinge.
Use estes comportamentos para validar a configuração no caixa:
- Vigência: promoção vencida ou que ainda não começou não é aplicada, e o item sai pelo preço de tabela.
- Prioridade entre promoções: o desconto por produto prevalece sobre o desconto por grupo de produto. O desconto por quantidade também prevalece sobre o de grupo quando a quantidade atinge a faixa mínima.
- Desconto no total da venda: itens que já receberam promoção automática ficam fora do rateio do desconto de rodapé. Assim, o mesmo item nunca recebe dois descontos.
- Identificação do cliente: as promoções dos tipos 5 e 6 só são aplicadas quando o operador identifica o cliente na venda. Essa costuma ser a causa quando uma promoção cadastrada "não funciona" no caixa.
Vendedores
VIEW: VW_PORTALPDV_VENDEDOR. Estrutura simples e plana, com os dados do vendedor e a região a que ele pertence. Permite identificar o vendedor na venda feita no PDV.
- Origem dos dados: TGFVEN; região em TSIREG.
- Requisitos para integração: o vendedor está ativo (ATIVO = 'S').
Exclusão de registros
Quando um registro deixa de ser válido para a integração — um produto é inativado, um parceiro perde um dado obrigatório, uma promoção expira —, ele também precisa ser excluído do Portal PDV. Isso é feito por um segundo conjunto de VIEWs, identificadas pelo sufixo _DLT. Cada entidade tem, portanto, um par de VIEWs:
- VIEW principal: lista o que deve existir no Portal PDV. Exemplo: VW_PORTALPDV_PRODUTO.
- VIEW de exclusão: lista o que deve ser excluído. Exemplo: VW_PORTALPDV_PRODUTO_DLT.
Exclusões de entidades com chave simples são enviadas em lote. Exclusões de entidades com chave composta são enviadas uma a uma, porque o lote não suporta esse tipo de chave. As VIEWs de exclusão nunca usam a personalização _AD, mesmo quando a entidade está com View Adicional marcada.
Personalização com VIEWs
Com VIEWs personalizadas no banco de dados, você personaliza a extração de dados sem alterar o código-fonte da aplicação. Crie uma VIEW com sufixo _AD, com a própria lógica de negócio, mantendo a mesma estrutura de colunas esperada pelo Sankhya Om, e marque View Adicional para a entidade na Grade de entidades.
Nomes das colunas
Para que a aplicação monte os objetos JSON corretamente, os nomes das colunas (aliases) da VIEW precisam seguir um padrão:
- Propriedades: escreva os nomes em SNAKE_CASE maiúsculo. A aplicação converte para camelCase no JSON final. Exemplo: o alias RAZAO_SOCIAL vira a propriedade "razaoSocial".
- chaveERP: use o alias CHAVE_ERP. A aplicação trata esse caso de forma específica para garantir a grafia chaveERP, e não chaveErp.
Objetos aninhados (1 para 1)
Separe os níveis do objeto no nome da coluna com dois underscores (__). Por exemplo, para criar o objeto endereco dentro de uma empresa, use os aliases:
ENDERECO__LOGRADOURO
ENDERECO__CIDADE
ENDERECO__ESTADO
Resultado no JSON:
"endereco": {
"logradouro": "...",
"cidade": "...",
"estado": "..."
}
Arrays de objetos (1 para N)
Use como prefixo do nome da coluna um dos grupos de array predefinidos na aplicação, e faça a VIEW retornar uma linha para cada item do array. Grupos suportados: ENDERECOS, CONTATOS, PRODUTO_UNIDADES, PRODUTO_CONTROLES, NOTAS_TECNICAS e DETALHES.
Por exemplo, para criar o array contatos de um parceiro, use os aliases:
CONTATOS__CHAVE_ERP
CONTATOS__NOME_CONTATO
CONTATOS__FONE
Se um parceiro tem 3 contatos, a VIEW retorna 3 linhas para ele, cada uma com os dados de um contato. A aplicação agrupa as 3 linhas em um único objeto, com um array contatos de 3 objetos. Regras de agrupamento:
- Um item só entra no array quando a chave dele está preenchida. Linhas com a chave do grupo vazia são descartadas.
- Chaves repetidas são consideradas uma única vez, e a primeira ocorrência é mantida.
Consultas em tempo real
Além dos cadastros exportados, o Portal PDV consulta o Sankhya Om em tempo real para informações que não faz sentido replicar, porque mudam o tempo todo ou dependem do contexto da operação. Essas consultas são atendidas por serviços publicados pelo próprio módulo.
| Consulta | Descrição |
|---|---|
| Estoque | Saldo disponível de um produto, consultado no momento da venda. |
| Pedidos | Pedidos em aberto de um parceiro e itens de um pedido, para que o PDV possa faturá-los. |
| Trocas | Cupom para troca, cupons de um parceiro e crédito disponível do parceiro. |
| Licença | Verificação da licença de uso do Portal PDV. |
|
ℹ️ Nota Por serem feitas em tempo real, essas consultas dependem da disponibilidade do Sankhya Om no momento da operação no caixa. |
Pontos de atenção
Identificação do operador do caixa
Quando um evento chega do PDV (venda, troca, movimentação de caixa ou inutilização), o Sankhya Om identifica quem fez a operação pelo CPF do operador, e não pelo campo Usuário da empresa:
- O PDV envia o CPF de quem está operando o caixa.
- O Sankhya Om busca esse CPF no Cadastro de Usuários (campo CPF da TSIUSU) para encontrar o código do usuário.
- Se o CPF não for encontrado, o Sankhya Om tenta usar o código de usuário enviado no próprio evento.
- Se nenhuma das duas formas identificar o usuário, o evento fica com ERRO e não é escriturado.
|
⚠️ Atenção Preencha o CPF no Cadastro de Usuários de todas as pessoas que vão operar o PDV. CPF ausente ou divergente faz os eventos desse operador falharem. |
Rotinas automáticas
A integração depende de rotinas agendadas no Sankhya Om. Em uma instalação que funciona corretamente, todas estão ativas; se uma delas parar, a parte correspondente da integração deixa de funcionar.
| Rotina | O que faz |
|---|---|
| Exportação de cadastros | Envia para o Portal PDV os registros novos, alterados e excluídos de todas as entidades. |
| Leitura da fila de eventos | Consome as mensagens publicadas pelo Portal PDV e as grava na tabela de entrada. |
| Carga da fila para processamento | Transfere os registros da tabela de entrada para a tabela de processamento. |
| Processamento de vendas, trocas, cancelamentos, inutilizações e movimentações de caixa | Uma rotina para cada tipo de operação, responsável pela escrituração no Sankhya Om. |
| Limpeza | Rotina diária, executada fora do horário comercial. Remove das tabelas de integração os registros antigos já processados e mantém o que ainda não foi concluído. |
Perguntas frequentes
Por que nenhum evento do PDV é consumido?
A credencial está recusada ou ausente. Confira a API Key e o API Secret do ambiente da base e salve a configuração. Acesse API Key e API Secret.
Por que os eventos de um operador ficam com ERRO?
O CPF do operador está ausente ou divergente no Cadastro de Usuários. Preencha ou corrija o CPF. Acesse Identificação do operador do caixa.
Por que uma entidade falha no ciclo de exportação?
Há um registro inválido ou View Adicional está marcada sem a VIEW _AD criada. Consulte Último Retorno na Grade de entidades e, se necessário, crie a VIEW _AD ou desmarque View Adicional.
O que significa um evento com status SEM_PROCESSADOR?
Há incompatibilidade de versão entre o Portal PDV e o módulo do Sankhya Om. Revise as versões dos dois. Acesse Situações de um evento.
Por que o CST ou a alíquota de ICMS saem divergentes no XML?
As prioridades tributárias estão ausentes ou incompletas para o par de UFs. Revise a ordem de prioridade antes da regra em si. Acesse Prioridades Tributárias.
Por que a SEFAZ rejeitou o documento por falta de tributação de ICMS?
Não há regra tributária para o par de UFs praticado. Cadastre a regra para o par de UF de origem e UF de destino. Acesse Regras Tributárias.
Por que o cupom saiu com um CFOP inesperado?
O perfil do parceiro (consumidor final ou revenda) está cadastrado incorretamente. Revise o perfil no cadastro do parceiro. Acesse Regras Tributárias.
Por que PIS e COFINS saem zerados no documento?
Nenhuma regra de imposto federal se aplica ao item. Cadastre a regra específica ou uma regra global. Acesse Impostos Federais.
Por que CBS e IBS não aparecem no XML?
A Nota Técnica 2025.002-RTC está inativa ou não há alíquota para a combinação de empresa, município, UF e NCM. Ative a Nota Técnica e confira as alíquotas e o NCM do produto. Acesse Impostos da Reforma Tributária: CBS e IBS.
Por que uma promoção cadastrada não é aplicada no caixa?
A promoção está fora da vigência, tem critérios de outro tipo preenchidos ou depende de cliente identificado (tipos 5 e 6). Revise a vigência e os critérios e identifique o cliente na venda. Acesse Promoções.
Por que uma alteração no Sankhya Om ainda não vale no caixa?
O ciclo de exportação ainda não enviou a alteração. Aguarde o ciclo e confira Último Retorno. Acesse Como o PDV usa as entidades tributárias.
Comentários
0 comentário
Escreva seu comentário aqui
Por favor, entre para comentar.