Nova Página

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 ~~Título~~PDV ~~Principal~~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 ~~Subtítulo~~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.

~~Texto~~O ~~comum~~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

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 **negrito**,contingência. ~~*itálico*~~ cancelado String ("S" ou "N") ✅ Indica se a venda foi cancelada. dataCancelamento String (YYYY-MM-DD HH:MM:SS) ❌ Data e ~~até~~hora ***negritode +cancelamento itálico***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).

~~###~~

~~Listanumerada~~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:
1.

~~Primeiro~~

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
2. ~~Segundo~~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:
3.

~~Terceiro~~

it 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.