Integração de Envio de Vendas

Documentação Técnica — Integração de Envio de Vendas do PDV Avanço para ERP Parceiro

1. Visão Geral da Integração

O PDV Avanço é responsável por realizar o envio das vendas concluídas para o ERP Parceiro, por meio de um endpoint HTTP (POST) que será desenvolvido pelo ERP, com base na estrutura e regras de preenchimento do payload descritas neste documento.

Cada requisição conterá uma única venda, no formato JSON, contendo todas as informações fiscais no xml, itens, pagamentos, e dados complementares necessários para o controle contábil e gerencial. 

Os campos que estão como opcionais é que podem e não conter na venda.

Os campos que estão como obrigatórios é que sempre irão conter na venda.

Importante: Todos os dados fiscais devem ser buscados pelo ERP no XML que está sendo fornecido no JSON de venda. 

O ERP deverá receber, validar e armazenar essas informações, podendo processá-las de forma assíncrona ou síncrona, conforme sua arquitetura.

2. Estrutura geral do payload. 

2.1. Exemplo Simplificado de Estrutura

```json

"codigoFormaPagamento":0,        

```json

3. Estrutura Detalhada do Payload

Estrutura do Payload – Identificação da Venda

Campo	Tipo	Obrigatório	Descrição / Observações
softHouse	String	✅	Identificação da software house responsável pelo PDV. Valor fixo "AVANCO".
modeloDocumentoFiscal	String	✅	Código do modelo fiscal do documento. Exemplo: "65" (NFC-e).
chaveAcesso	String	✅	Chave de acesso da NFC-e (44 dígitos).
chaveBusca	String	✅	Chave utilizada internamente para rastreamento ou pesquisa da venda.
cnpjLoja	String	✅	CNPJ da loja emissora da venda.
numeroLoja	Integer	✅	Identificador numérico da loja no sistema ERP.
numeroSerie	String	✅	Número de série fiscal da nota.
numeroPdv	Integer	✅	Número do terminal de PDV que emitiu a venda.
numeroCupom	Integer	✅	Número sequencial do cupom no PDV.
numeroNota	Integer	✅	Número da nota fiscal (NFC-e).
dataHoraVenda	String (YYYY-MM-DD HH:MM:SS)	✅	Data e hora exatas da venda.
dataMovimento	String (YYYY-MM-DD)	✅	Data de movimento contábil da venda.
versaoPdv	String	✅	Versão do software PDV responsável pela emissão.
contingencia	String ("S" ou "N")	✅	Indica se a nota foi emitida em contingência.
cancelado	String ("S" ou "N")	✅	Indica se a venda foi cancelada.
dataCancelamento	String (YYYY-MM-DD HH:MM:SS)	❌	Data e hora de cancelamento da venda, quando aplicável.
chaveSubstituta	String	❌	Chave de acesso da nota fiscal substituta, quando houver.
protocoloCancelamento	String	❌	Protocolo de cancelamento retornado pela SEFAZ.
xmlCancelamento	String	❌	XML completo do evento de cancelamento da NFC-e.
xml	String	✅	XML completo da NFC-e emitida.

objeto cabecalho: 

Campo	Tipo	Obrigatório	Descrição / Observações
doctoCliente	String	❌	Documento do cliente vinculado à venda (CPF/CNPJ), quando informado.
numeroVendedor	Integer	❌	Código do vendedor responsável pela venda.
tokenScanntech	String	❌	Token de identificação do PDV na plataforma Scanntech (quando aplicável).
numeroDeItens	Integer	✅	Quantidade total de itens registrados na venda.
totalDaVenda	Decimal	✅	Valor total bruto da venda (soma de todos os itens antes de descontos gerais).
descontoSubtotal	Decimal	❌	Valor total de descontos aplicados sobre o subtotal da venda.
acrescimoSubtotal	Decimal	❌	Valor total de acréscimos aplicados sobre o subtotal.
troco	Decimal	❌	Valor de troco devolvido ao cliente.
descontoItens	Decimal	❌	Total de descontos concedidos diretamente nos itens.
acrescimoItens	Decimal	❌	Total de acréscimos aplicados diretamente nos itens.
descontosFormas	Decimal	❌	Valor de desconto originado em uma forma de pagamento (ex: convênio, vale).
acrescimosFormas	Decimal	❌	Valor de acréscimo originado em uma forma de pagamento (ex: juros).
contraVale	String ("S" ou "N")	✅	Indica se há contravale relacionado à venda.
codigoOperador	String	✅	Código do operador que efetuou a venda.
nomeOperador	String	✅	Nome do operador do PDV.
cpfOperador	String	❌	CPF do operador (quando informado).
numeroDav	String	❌	Número do Documento Auxiliar de Venda, quando aplicável.
valorSaqueTef	Decimal	❌	Valor de saque realizado através do TEF (Transação Eletrônica Financeira).
numeroPrevenda	String	❌	Número da pré-venda associada.
numeroControlePrevenda	String	❌	Número de controle da pré-venda.
numeroControleconta	String	❌	Número de controle da conta vinculada à operação (utilizado em restaurantes, comandas, etc).
cartaoInforCard	String	❌	Número do cartão InforCard, se utilizado.
totalPontosDotz	Integer	❌	Quantidade total de pontos Dotz acumulados na venda.
trocoSolidario	Decimal	❌	Valor do troco destinado ao troco solidário (doação).
cnpjTrocoSolidario	String	❌	CNPJ da instituição beneficiária do troco solidário.
codigoOperadorLiberacaoDescontoAcrescimoSubtotal	String	❌	Código do operador que autorizou desconto/acréscimo no subtotal.
nomeOperadorLiberacaoDescontoAcrescimoSubtotal	String	❌	Nome do operador que liberou desconto/acréscimo no subtotal.
cpfSocioTorcedor	String	❌	CPF do cliente vinculado ao programa Sócio Torcedor.
codigoMotivoAcrescimoDescontoSubtotal	String	❌	Código do motivo de acréscimo/desconto aplicado no subtotal.
codigoTipoMotivoAcrescimoDescontoSubtotal	String	❌	Tipo do motivo (classificação interna de desconto/acréscimo).
descricaoMotivoAcrescimoDescontoSubtotal	String	❌	Descrição textual do motivo de acréscimo/desconto no subtotal.
cpfBeblue	String	❌	CPF do cliente associado ao programa Beblue (cashback).
valorTrocoSimples	Decimal	❌	Valor de troco simples devolvido (sem troco solidário).
cpfDotz	String	❌	CPF do cliente cadastrado no programa Dotz.
cpfPromocoesParceiros	String	❌	CPF informado em promoções de parceiros.
cpfCnpjClienteMercafacil	String	❌	CPF ou CNPJ do cliente no programa Mercafacil.
valorDescontoMercafacilRateado	Decimal	❌	Valor do desconto Mercafacil rateado entre os itens.
idMercafacil	String	❌	Identificador interno do cliente no Mercafacil.
cupomVerde	String ("S" ou "N")	✅	Indica se a venda participa do programa Cupom Verde.
informouCpfCupomVerde	String ("S" ou "N")	❌	Indica se o CPF foi informado especificamente para o Cupom Verde.

objeto pagamento: 

Campo	Tipo	Obrigatório	Descrição / Observações
codigoFormaPagamento	Integer	✅	Código interno da forma de pagamento utilizada.
vendaPrazo	String ("S" ou "N")	✅	Indica se a venda foi a prazo.
descricaoFormaPagamento	String	✅	Descrição textual da forma de pagamento (ex: “DINHEIRO”, “CARTÃO CRÉDITO”).
dataVencimento	String (YYYY-MM-DD)	✅	Data de vencimento da parcela, usada para vendas a prazo.
valorPago	Decimal	✅	Valor pago pelo cliente nesta forma de pagamento.
acrescimo	Decimal	❌	Valor de acréscimo aplicado na forma de pagamento.
desconto	Decimal	❌	Valor de desconto aplicado na forma de pagamento.
documentoCliente	String	❌	Documento do cliente vinculado a esta forma de pagamento (CPF, CNPJ, etc).
numeroDoctoPagamento	String	❌	Número de controle do documento da forma de pagamento (ex: número do cheque, convênio etc).
numeroParcelas	Integer	✅	Número total de parcelas para esta forma de pagamento.
documentoIdentificacaoCliente	String	❌	Documento de identificação do cliente (ex: RG, CNH), quando coletado.
codigoInternoCliente	String	❌	Código interno do cliente vinculado à operação.
clienteDigitouSenha	String ("S" ou "N")	❌	Indica se o cliente digitou senha (transações TEF ou POS).
teveContraVale	String ("S" ou "N")	✅	Indica se houve contravale vinculado a esta forma de pagamento.
codigoConvenio	String	❌	Código do convênio utilizado (ex: plano de saúde, empresa conveniada).
tefTipoCartao	String	❌	Tipo de cartão utilizado no TEF (ex: crédito, débito, voucher).
textoModalidadePagamento	String	❌	Descrição da modalidade de pagamento (ex: “Crédito 2x”, “Pix QRCode”).
idCarteiraDigital	String	❌	Identificador interno da carteira digital utilizada.
nomeCarteiraDigital	String	❌	Nome da carteira digital (ex: PicPay, Ame, Mercado Pago).
nsuSitef	String	❌	Número sequencial único da transação retornado pelo SiTef.
codigoAutorizacao	String	❌	Código de autorização retornado pela operadora TEF.
tefBin	String	❌	BIN (primeiros dígitos do cartão) usado na transação TEF.
produtoSitef	String	❌	Produto de transação retornado pelo SiTef.
nsuHostCompleto	String	❌	Identificador completo da transação no host do adquirente.
descricaoBandeiraTef	String	❌	Nome da bandeira do cartão retornada pelo TEF (ex: Visa, Mastercard).
tefRede	String	❌	Nome da rede de processamento TEF (ex: Rede, GetNet, Cielo).
tefBandeira	String	❌	Código da bandeira do cartão (interno ou do adquirente).
embossoCartao	String	❌	Nome impresso no cartão (embossado).
nsuHost	String	❌	NSU simplificado retornado pelo host.
codigoFormaPagamentoScanntech	Integer	❌	Código da forma de pagamento conforme integração Scanntech.
valorParcela	Decimal	❌	Valor unitário da parcela, quando parcelado.
pontosDotzAdquiridos	Integer	❌	Quantidade de pontos Dotz adquiridos nesta transação.
codigoOperadorLiberacaoImpedimento	String	❌	Código do operador que liberou pagamento com impedimento.
nomeOperadorLiberacaoImpedimento	String	❌	Nome do operador que autorizou o pagamento impedido.
tipoImpedimento	Integer	❌	Tipo de impedimento aplicado à forma de pagamento.
valorLiberado	Decimal	❌	Valor liberado pelo operador após impedimento.
numeroParcelasPos	Integer	❌	Número de parcelas informado no POS.
codigoTipoTransacaoPos	Integer	❌	Código do tipo de transação no POS.
descricaoTipoTransacaoPos	String	❌	Descrição textual do tipo de transação (ex: “Crédito à vista”).
codigoBandeiraPos	Integer	❌	Código interno da bandeira utilizada no POS.
descricaoBandeiraPos	String	❌	Nome da bandeira informada pelo POS.
nsuTransacaoPos	String	❌	NSU da transação capturada no POS.
autorizacaoTransacaoPos	String	❌	Código de autorização da transação do POS.
codigoVoucher	String	❌	Código do voucher vinculado ao pagamento, quando aplicável.

objeto itensVendidos:

Campo	Tipo	Obrigatório	Descrição / Observações
itemCancelado	String ("S" ou "N")	✅	Indica se o item foi cancelado no cupom.
numeroItem	Integer	✅	Número sequencial do item no cupom.
codigoBarras	String	✅	Código de barras do produto.
codigoCategoria	String	❌	Código da categoria do produto no ERP.
codigoDepartamento	String	❌	Código do departamento vinculado ao produto.
codigoFamiliaPrecosIguais	String	❌	Código da família de produtos com preços iguais (quando aplicável).
codigoSegmento	String	❌	Código do segmento de produto.
codigoSubCategoria	String	❌	Código da subcategoria do produto.
codigoSubSegmento	String	❌	Código do subsegmento do produto.
quantidade	Decimal	✅	Quantidade vendida do produto.
precoUnitario	Decimal	✅	Valor unitário do produto.
valorTotalItem	Decimal	✅	Valor total do item (quantidade × preço unitário).
tipoItem	String	✅	Tipo do item — “P” para produto, “S” para serviço.
situacaoTributaria	String	✅	Situação tributária do item (ex: F = Tributado).
aliquotaReal	Decimal	❌	Alíquota nominal do imposto aplicado (ICMS, PIS, COFINS, etc).
aliquotaEfetiva	Decimal	❌	Alíquota efetiva resultante após reduções e isenções.
codigoInterno	Integer	✅	Código interno do produto no sistema.
codigoAlternativo	String	✅	Código alternativo ou PLU do produto.
precoReal	Decimal	✅	Preço real do item, antes de eventuais descontos promocionais.
descontoDireto	Decimal	❌	Valor de desconto concedido diretamente no item.
acrescimoDireto	Decimal	❌	Valor de acréscimo aplicado diretamente no item.
vendidoPrecoPromocional	String ("S" ou "N")	✅	Indica se o item foi vendido com preço promocional.
registradorAliquota	String	✅	Identificação da alíquota fiscal no registrador (ex: “F1”).
dadoComplementar	String	❌	Dados complementares sobre o item (observações fiscais ou gerenciais).
codigoOperadorCancelamento	String	❌	Código do operador responsável pelo cancelamento do item.
nomeOperadorCancelamento	String	❌	Nome do operador que cancelou o item.
aliquotaIbptFederal	Decimal	✅	Alíquota federal conforme tabela IBPT.
valorAproximadoFederal	Decimal	✅	Valor aproximado de tributos federais embutidos no item.
aliquotaIbptEstadual	Decimal	✅	Alíquota estadual conforme tabela IBPT.
valorAproximadoEstadual	Decimal	✅	Valor aproximado de tributos estaduais embutidos no item.
aliquotaIbptMunicipal	Decimal	✅	Alíquota municipal conforme tabela IBPT.
valorAproximadoMunicipal	Decimal	✅	Valor aproximado de tributos municipais embutidos no item.
descontoSocioTorcedor	String ("S" ou "N")	❌	Indica se houve desconto por programa Sócio Torcedor.
descontoPromocaoEspecial	String ("S" ou "N")	❌	Indica se houve desconto de promoção especial.
pontosDotz	Integer	❌	Pontos Dotz gerados pelo item, se aplicável.
idPromocao	String	❌	Identificador da promoção vinculada ao item.
tipoPromocao	String ("A","S","F","V","D","M","T" ou vazio)	✅	Tipo da promoção aplicada (A=acréscimo, S=desconto simples, etc).
unidadeMedida	String	✅	Unidade de medida do produto (ex: UN, KG, LT).
quantidadeUsadaPromocao	Integer	❌	Quantidade do item utilizada para compor a promoção.
codigoTabelaPrecosAtacado	String	❌	Código da tabela de preços de atacado aplicada, quando houver.
descricaoResumida	String	✅	Descrição resumida do produto.
fatorConversao	Decimal	✅	Fator de conversão de unidade (ex: 1 caixa = 12 unidades).
codigoOperadorLiberacaoDescontoAcrescimoItem	String	❌	Código do operador que autorizou desconto/acréscimo no item.
nomeOperadorLiberacaoDescontoAcrescimoItem	String	❌	Nome do operador que liberou o desconto/acréscimo no item.
descontoRateado	Decimal	❌	Valor de desconto rateado entre os itens (proveniente de totalização).
acrescimoRateado	Decimal	❌	Valor de acréscimo rateado entre os itens.
baseCalculo	Decimal	✅	Base de cálculo utilizada para apuração de impostos do item.
valorIcms	Decimal	✅	Valor de ICMS incidente sobre o item.
totalBruto	Decimal	✅	Valor bruto do item antes de descontos e tributos.
aliquotaPis	Decimal	❌	Alíquota de PIS aplicável ao item.
valorPis	Decimal	❌	Valor de PIS calculado para o item.
aliquotaCofins	Decimal	❌	Alíquota de COFINS aplicável ao item.
valorCofins	Decimal	❌	Valor de COFINS calculado para o item.
cfop	String	✅	CFOP (Código Fiscal de Operações e Prestações) do item.
cstPis	String	✅	Código de Situação Tributária de PIS.
cstCofins	String	✅	Código de Situação Tributária de COFINS.
ncm	String	✅	NCM (Nomenclatura Comum do Mercosul) do produto.
cest	String	✅	CEST (Código Especificador da Substituição Tributária) do produto.
grupoTributacao	String	✅	Grupo de tributação (ex: 00, 20, 40, 60).
codigoMotivoAcrescimoDescontoCancelamento	String	❌	Código do motivo vinculado a acréscimo/desconto/cancelamento do item.
codigoTipoMotivoAcrescimoDescontoCancelamento	String	❌	Tipo do motivo (classificação do acréscimo/desconto/cancelamento).
descricaoMotivoAcrescimoDescontoCancelamento	String	❌	Descrição do motivo vinculado ao acréscimo/desconto/cancelamento.
cpfCnpjClienteMercafacil	String	❌	CPF ou CNPJ do cliente vinculado ao programa Mercafacil.
icmsRetiradoBasePisCofins	String ("S" ou "N")	❌	Indica se o ICMS foi retirado da base de cálculo de PIS/COFINS.
codigoQuemPesou	String	❌	Código do operador responsável pela pesagem (balança integrada).

objeto cashback:

Campo	Tipo	Obrigatório	Descrição / Observações
codigoFormaPagamento	Integer	❌	Código interno da forma de pagamento utilizada para o cashback.
descricaoFormaPagamento	String	❌	Descrição textual da forma de pagamento utilizada no cashback.
cpfCliente	String	❌	CPF do cliente participante do programa de cashback.
valorTransacao	Decimal	❌	Valor total da transação de cashback (valor retornado ou gerado).
nsuTransacao	String	❌	Número sequencial único da transação de cashback.
idTransacao	String	❌	Identificador único da transação dentro do sistema de cashback.
idPagamento	String	❌	Identificador do pagamento vinculado à operação de cashback.

objeto entrega:

Campo	Tipo	Obrigatório	Descrição / Observações
documentoCliente	String	❌	Documento do cliente destinatário da entrega (CPF ou CNPJ).
nomeCliente	String	❌	Nome completo do cliente destinatário.
tipoLogradouro	String	❌	Tipo de logradouro (ex: Rua, Avenida, Estrada).
logradouro	String	❌	Nome da rua ou avenida de entrega.
numeroLogradouro	String	❌	Número do endereço de entrega.
complemento	String	❌	Complemento do endereço (ex: apartamento, bloco, ponto de referência).
telefone	String	❌	Telefone de contato do cliente para entrega.
bairro	String	❌	Bairro do endereço de entrega.
cidade	String	❌	Nome da cidade do endereço de entrega.
uf	String	❌	Unidade Federativa (UF) do endereço de entrega (ex: “MG”).
cep	String	❌	Código de Endereçamento Postal (CEP) do endereço de entrega.
referencia	String	❌	Ponto de referência adicional para facilitar a entrega.
dataentrega	String (YYYYMMDD)	❌	Data prevista para entrega.
horaInicial	String (HH:MM:SS)	❌	Horário inicial previsto para entrega.
horaFinal	String (HH:MM:SS)	❌	Horário final previsto para entrega.
qtdeCaixas	Integer	❌	Quantidade de caixas envolvidas na entrega.
observacoesCaixas	String	❌	Observações adicionais sobre as caixas transportadas.
qtdeEngradados	Integer	❌	Quantidade de engradados incluídos na entrega.
observacoesEngradados	String	❌	Observações adicionais sobre os engradados transportados.
qtdevasilhames	Integer	❌	Quantidade de vasilhames entregues.
observacoesVasilhames	String	❌	Observações sobre os vasilhames.
qtdeFrios	Integer	❌	Quantidade de produtos frios incluídos na entrega.
observacoesFrios	String	❌	Observações relacionadas aos produtos frios.
qtdeCongelados	Integer	❌	Quantidade de produtos congelados incluídos na entrega.
observacoesCongelados	String	❌	Observações sobre os produtos congelados.
buscarDeposito	String ("S" ou "N")	❌	Indica se a mercadoria deve ser buscada no depósito antes da entrega.
observacoesDeposito	String	❌	Observações gerais sobre o depósito, retirada ou logística da entrega.