Skip to main content

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




{


 
    "softHouse":"AVANCO",			// Obrigatório


 
    "modeloDocumentoFiscal":"65",	// Obrigatório


 
    "chaveAcesso":"",				// Obrigatório


 
    "chaveBusca":"",				// Obrigatório


 
    "cnpjLoja":"",					// Obrigatório


 
    "numeroLoja":0,					// Obrigatório


 
    "numeroSerie":"",				// Obrigatório


 
    "numeroPdv":0,					// Obrigatório


 
    "numeroCupom":233,				// Obrigatório


 
    "numeroNota":267,				// Obrigatório


 
    "dataHoraVenda":"2024-09-10 11:11:11",	// Obrigatório


 
    "dataMovimento":"2024-09-10",			// Obrigatório


 
    "versaoPdv":"",							// Obrigatório


 
    "contingencia":"N", -> S ou N			// Obrigatório


 
    "cancelado":"N",   -> S ou N				// Obrigatório


 
    "dataCancelamento":"2024-09-10 11:11:11",	// Opcional


 
    "chaveSubstituta":"",						// Opcional


 
    "protocoloCancelamento":"",					// Opcional


 
    "xmlCancelamento":"",						// Opcional


 
    "xml":"",									// Obrigatório


 
    "cabecalho":{


 
        "doctoCliente":"",				// Opcional


 
        "numeroVendedor":0,				// Opcional


 
        "tokenScanntech": "50d7f6db-2edd-415c-ac2d-87470a2db43d", //Opcional


 
        "numeroDeItens":0,				// Obrigatório


 
        "totalDaVenda":0.00,			// Obrigatório


 
        "descontoSubtotal":0.00,		// Opcional


 
        "acrescimoSubtotal":0.00,		// Opcional


 
        "troco":0.00,					// Opcional


 			
        "descontoItens":0.00,			// Opcional


 
        "acrescimoItens":0.00,			// Opcional


 
        "descontosFormas":0.00,			// Opcional


 
        "acrescimosFormas":0.00,		// Opcional


 
        "contraVale":"N", -> S ou N		// Obrigatório


 
        "codigoOperador":"",			// Obrigatório


 
        "nomeOperador":"",				// Obrigatório


 
        "cpfOperador":"",				// Opcional


 
        "numeroDav":"",					// Opcional


 
        "valorSaqueTef":0.00,			// Opcional


 
        "numeroPrevenda":"",			// Opcional


 
        "numeroControlePrevenda":"",	// Opcional


 
        "numeroControleconta":"",		// Opcional


 
        "cartaoInforCard":"",			// Opcional


 
        "totalPontosDotz":0,			// Opcional


 
        "trocoSolidario":0.00,			// Opcional


 
        "cnpjTrocoSolidario":"",		// Opcional


 
        "codigoOperadorLiberacaoDescontoAcrescimoSubtotal":"",	// Opcional


 
        "nomeOperadorLiberacaoDescontoAcrescimoSubtotal":"",	// Opcional


 
        "cpfSocioTorcedor":"",								// Opcional


 
        "codigoMotivoAcrescimoDescontoSubtotal":"",			// Opcional


 
        "codigoTipoMotivoAcrescimoDescontoSubtotal":"",		// Opcional


 
        "descricaoMotivoAcrescimoDescontoSubtotal":""		// Opcional


 
        "cpfBeblue":"",										// Opcional


 
        "valorTrocoSimples":0.00,							// Opcional


 
        "cpfDotz":"",										// Opcional


 
        "cpfPromocoesParceiros":"",							// Opcional


 
        "cpfCnpjClienteMercafacil":"",						// Opcional


 
        "valorDescontoMercafacilRateado":0.00,				// Opcional


 
        "idMercafacil":"",									// Opcional


 
        "cupomVerde":"N", -> S ou N							// Obrigatório


 
        "informouCpfCupomVerde":"N" -> S ou N				// Opcional


 
    },


 
    "pagamento":[{


 
        "codigoFormaPagamento":0,					// Obrigatório


 
        "vendaPrazo": "N", -> S ou N			    // Obrigatório


 
        "descricaoFormaPagamento":"",				// Obrigatório


 
        "dataVencimento":"2024-09-10",				// Obrigatório


 
        "valorPago":0.00,							// Obrigatório


 
        "acrescimo":0.00,							// Opcional


 
        "desconto":0.00,							// Opcional


 
        "documentoCliente":"",						// Opcional 


 
        "numeroDoctoPagamento":"",					// Opcional


 
        "numeroParcelas": 1,						// Obrigatório


 
        "documentoIdentificacaoCliente": "",		// Opcional


 
        "codigoInternoCliente": "0",				// Opcional


 
        "clienteDigitouSenha": "N", -> S ou N		// Opcional


 
        "teveContraVale": "N", -> S ou N			// Obrigatório


 
        "codigoConvenio": "",						// Opcional

		
"tefTipoCartao": "",						// Opcional

		
"textoModalidadePagamento": "",				// Opcional

		
"idCarteiraDigital": "",					// Opcional

		
"nomeCarteiraDigital": "",					// Opcional

		
"nsuSitef": "",								// Opcional

		
"codigoAutorizacao": "",					// Opcional

		
"tefBin": "",								// Opcional

		
"produtoSitef": "",							// Opcional

		
"nsuHostCompleto": "",                      // Opcional
		"descricaoBandeiraTef",                     // Opcional

		
"descricaoBandeiraTef",                     // Opcional


"tefRede": "",								// Opcional

		
"tefBandeira": "",							// Opcional

		
"embossoCartao": "",						// Opcional

		
"nsuHost": "",								// Opcional

		
"codigoFormaPagamentoScanntech": 9,			// Opcional

		
"valorParcela": 0.00,						// Opcional


 
        "pontosDotzAdquiridos":0,					// Opcional


 
        "codigoOperadorLiberacaoImpedimento":"",	// Opcional


 
        "nomeOperadorLiberacaoImpedimento":"",		// Opcional


 
        "tipoImpedimento":0,						// Opcional


 
        "valorLiberado":0.00,						// Opcional


 
        "clienteDigitouSenha":"N",					// Opcional


 
        "numeroParcelasPos":0,						// Opcional


 
        "codigoTipoTransacaoPos":0,					// Opcional


 
        "descricaoTipoTransacaoPos":"",				// Opcional


 
        "codigoBandeiraPos":0,						// Opcional


 
        "descricaoBandeiraPos":"",					// Opcional


 
        "nsuTransacaoPos":"",						// Opcional


 
        "autorizacaoTransacaoPos":"" 				// Opcional


 
        "codigoVoucher": ""                                                 // Opcional


 
    }],


 
    "itensVendidos":[{


 
        "itemCancelado": "S",					// Obrigatório


 
        "numeroItem": 1,						// Obrigatório


 
        "codigoBarras": "00000000000109",		// Obrigatório

		
"codigoCategoria": "000",                               // Opcional

		
"codigoDepartamento": "000",                         // Opcional

		
"codigoFamiliaPrecosIguais": "00000",         // Opcional

		
"codigoSegmento": "000",                                 // Opcional

		
"codigoSubCategoria": "000",                         // Opcional

		
"codigoSubSegmento": "000"                           // Opcional


 
        "quantidade": 1.0,						// Obrigatório


 
        "precoUnitario": 18.99,					// Obrigatório


 
        "valorTotalItem": 18.99,				// Obrigatório


 
        "tipoItem": "P",						// Obrigatório


 
        "situacaoTributaria": "F",				// Obrigatório


 
        "aliquotaReal":18,						// Opcional


 
        "aliquotaEfetiva":18,					// Opcional


 
        "codigoInterno": 109,					// Obrigatório


 
        "codigoAlternativo": "0000000000000",	// Obrigatório


 	
        "precoReal": 18.99,						// Obrigatório


 
        "descontoDireto": 0.0,					// Opcional


 
        "acrescimoDireto": 0.0,					// Opcional


 
        "vendidoPrecoPromocional": "N",			// Obrigatório


 
        "registradorAliquota": "F1",			// Obrigatório


 
        "dadoComplementar": "",					// Opcional


 
        "codigoOperadorCancelamento": "",		// Opcional


 
        "nomeOperadorCancelamento": "",			// Opcional


 
        "aliquotaIbptFederal": 13.45,			// Obrigatório


 
        "valorAproximadoFederal": 2.55,			// Obrigatório


 
        "aliquotaIbptEstadual": 18.0,			// Obrigatório


 
        "valorAproximadoEstadual": 3.42,		// Obrigatório


 
        "aliquotaIbptMunicipal": 0.0,			// Obrigatório


 
        "valorAproximadoMunicipal": 0.0,		// Obrigatório


 
        "descontoSocioTorcedor": "N",			// Opcional


 
        "descontoPromocaoEspecial": "N",		// Opcional


 
        "pontosDotz": 0,						// Opcional


 
        "idPromocao": "",						// Opcional


 
        "tipoPromocao": "S", -> A,S,F,V,D,M,T ou vazio	// Obrigatório


 
        "unidadeMedida": "",							// Obrigatório


 
        "quantidadeUsadaPromocao": 0,					// Opcional

		
"codigoTabelaPrecosAtacado": "",				// Opcional


 
        "descricaoResumida": "",						// Obrigatório


 
        "fatorConversao": 1,							// Obrigatório


 
        "codigoOperadorLiberacaoDescontoAcrescimoItem":"",	// Opcional


 
        "nomeOperadorLiberacaoDescontoAcrescimoItem":"",	// Opcional


 
        "descontoRateado":0.00,							// Opcional


 
        "acrescimoRateado":0.00,						// Opcional


 
        "baseCalculo":0.00,								// Obrigatório


 
        "valorIcms":0.00,								// Obrigatório


 
        "totalBruto":0.00,								// Obrigatório


 
        "aliquotaPis":0.00,								// Opcional


 
        "valorPis":0.00,								// Opcional


 
        "aliquotaCofins":0.00,							// Opcional


 
        "valorCofins":0.00,								// Opcional


 
        "cfop":"",										// Obrigatório


 
        "cstPis":"",									// Obrigatório


 
        "cstCofins":"",									// Obrigatório


 
        "ncm":"",										// Obrigatório


 
        "cest":"",										// Obrigatório


 
        "grupoTributacao":"",							// Obrigatório (00,60,20,40, etc)


 
        "codigoMotivoAcrescimoDescontoCancelamento":"",			// Opcional


 
        "codigoTipoMotivoAcrescimoDescontoCancelamento":"",		// Opcional


 
        "descricaoMotivoAcrescimoDescontoCancelamento":"",		// Opcional


 
        "cpfCnpjClienteMercafacil":"",					// Opcional


 
        "icmsRetiradoBasePisCofins":"N",				// Opcional


 
        "codigoQuemPesou":""							// Opcional


 
    }],


 
    "cashback":{	//Opcional  Essa propriedade só é preenchida quando houver


        "codigoFormaPagamento":0,


        "descricaoFormaPagamento":"",


        "cpfCliente":"",


        "valorTransacao":0,


        "nsuTransacao":"",


        "idTransacao":"",


        "idPagamento":""


    },


    "entrega":{ //Opcional   Essa propriedade só é preenchida quando houver		
        
"codigoFormaPagamento":0,
        
"descricaoFormaPagamento":"",
        "cpfCliente":"",
        "valorTransacao":0,
        "nsuTransacao":"",
        "idTransacao":"",
        "idPagamento":""
    },
    "entrega":{		//Opcional  Essa propriedade só é preenchida quando houver 
        "documentoCliente":"",


 
        "nomeCliente":"",


 
        "tipoLogradouro":"",


 
        "logradouro":"",


 
        "numeroLogradouro":"",


 
        "complemento":"",


 
        "telefone":"",


 
        "bairro":"",


 
        "cidade":"",


 
        "uf":"",


 
        "cep":"",


 
        "referencia":"",


 
        "dataentrega":"20250910",


 
        "horaInicial":"10:00:00",


 
        "horaFinal":"13:00:00",


 
        "qtdeCaixas":0,


 
        "observacoesCaixas":"",


 
        "qtdeEngradados":0,


 
        "observacoesEngradados":"",


 
        "qtdevasilhames":0,


 
        "observacoesVasilhames":"",


 
        "qtdeFrios":0,


 
        "observacoesFrios":"",


 
        "qtdeCongelados":0,


 
        "observacoesCongelados":"",


 
        "buscarDeposito":"N",


 
        "observacoesDeposito":""


 
    },


```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.
Back to top