Skip to main content

Fluxo de interação para envio de vendas via Json

Módulo PV – Integração de Envio de Vendas

1. Objetivo / Descrição

Este módulo documenta como parceiros devem enviar os dados de venda via JSON para o sistema Novo Avanço, permitindo a integração de vendas realizadas no PDV (loja física) ao sistema central da Avanço.

2. Fluxo Geral

  1. PDV gera um JSON com os dados da venda conforme o padrão definido.

  2. JSON é enviado para o endpoint do módulo PV (rota exata definida na API da Avanço).

  3. O sistema Novo Avanço processa e registra a venda.

  • Destino da chamada: não informado na página — verifique junto ao time técnico da Avanço ou API correspondente.

3. Estrutura do JSON de Requisição

3.1 Cabeçalho (cabeçalho)

Campo Descrição Tamanho máx. Exemplo
cnpj CNPJ/CPF do cliente 14 "10542390612"
vendedor Código do vendedor 3 "000"
desconto Desconto aplicado no subtotal 9 0
total Valor total da venda 12 35.10
itens Número de itens vendidos 3 2
descontoItens Valor de desconto nos itens 9 0
troco Valor de troco 9 4.90
dataEmissao Data de emissão (ISO 8601) 24 "2024-02-21T14:11:00.000Z"
numEcf Número do CUPOM 2 13
acrescimo Acréscimo no subtotal 9 0
versao Versão do PDV 6 62
cartao Número do cartão 19 0
numeroParcelas Número de parcelas 2 0
contraVale Se foi emitido contra-vale com o troco (S/N) 1 N
origem Código da integração (definir com Avanço) — —
operador Código do Operador 15 13
numeroDAV Número do DAV 13 0
marcaEcf Marca da impressora no PDV 15 "NFCE"
modeloEcf Modelo da impressora no PDV 20 "NFCE"
valorSaque Valor de saque nas transações TEF 9 0
versaoPdv Versão do ponto de venda 6 "7.4.66"
nomeOperador Nome do operador 15 "Carlos"
dataVenda Data da venda (ISO 8601) 24 "2024-02-21T14:11:00.000Z"
numeroControle Número de controle da pré-venda 10 "0000000000"
valorAproximadoTributos Estimativa do valor dos tributos 10 0
pontosDotz Pontos Dotz (venda + itens) 12 "000000000000"
trocoSolidario Valor do troco solidário 9 0
descontoScannplus Se o desconto foi via ScannPlus (S/N) 1 N
ccf Número do CCF do Cupom Fiscal 6 34
horaCriacaoArquivo Hora de criação do arquivo (HHMMSS) 6 90903
cnpjLoja CNPJ da loja 14 71294573000113
cpfSocioTorcedor CPF do Sócio Torcedor (se aplicável) 11 0
cpfBeBlue CPF do cliente BeBlue (0 se não informar) 11 0
trocoSimples Valor do troco simples 9 0
cpfDotz CPF do cliente Dotz pontuado 11 0
cpfTrocoSolidario CPF/CNPJ de quem deixou troco solidário 14 0
cpfPromocional CPF para promoções de parceiros 11 0
cpfCnpjMercafacil CPF/CNPJ para Clube Mercafácil 14 ""
valorDescontoRateadoSubtotal Valor total do desconto rateado 10 0
idDescontoSubtotal ID da transação Mercafácil 50 42d522f4-6b0a-43f9-bd82-721c58609658
cupomVerde Se foi cupom verde (S/N) 1 N
cpfCupomVerde Se informou CPF para cupom verde (S/N) 1 N
cpfOperador CPF do operador 11 "00000000000"

3.2 Itens (itens)

Para cada item vendido:

Campo Descrição Exemplo
numeroSerieEcf Número do PDV (formatação Avanço) "AV071294573000113025"
coo Número do cupom (mesmo sem cupom, usar número da nota) 13
sequencialItem Sequência do item na venda 1
codigoVendido Código EAN/barras do item "07896227620014"
quantidade Quantidade (últimas 3 posições decimais) 5
preço Preço unitário 3.90
total Valor total do item (qtde × preço) 19.50
tributacao Situação tributária (N, F, T, I) "N"
dataVenda Data da venda (ISO 8601) "2024-02-21T03:00:00.000Z"
numEcf Número do PDV 1
tipoItem P = Produto ou S = Serviço "P"
aliquotaProduto Alíquota real (ex: N=0, T=1800, T=2500) 0
aliquotaSaida Alíquota efetiva de saída 0
numProduto Código interno / reduzido do produto "000857"
codigoAlternativo Código alternativo do cadastro "857"
precoVendaAtual Preço real de venda 3.90
valorDesconto Desconto aplicado no item 0
Venda no preço promocional (S/N) Se foi vendido com preço promocional N
registradorAliquota Registrador da alíquota no ECF (SPED) Ex: 01T0700

4. Exemplo de JSON completo (simplificado)

{
  "auth": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
  },
  "cabecalho": {
    "cnpj": "71294573000113",
    "cnpjLoja": "71294573000113",
    "operador": "33",
    "nomeOperador": "MARIA OLIVEIRA",
    "cpfOperador": "00000000000",
    "vendedor": "007",
    "numEcf": 12,
    "ccf": 150,
    "dataVenda": "2025-09-10T20:10:00.000Z",
    "dataEmissao": "2025-09-10T20:11:00.000Z",
    "total": 250.00,
    "itens": 1,
    "troco": 0,
    "desconto": 10.00,
    "acrescimo": 0,
    "versaoPdv": "7.5.10",
    "versao": 63,
    "origem": 2
  },
  "id": 908200,
  "itens": [
    {
      "numeroSerieEcf": "AV071294573000113012",
      "coo": 150,
      "sequencialItem": 1,
      "numEcf": 12,
      "numProduto": "002222",
      "codigoVendido": "7892223334445",
      "descricao": "TV LED 50 POL UHD",
      "unidade": "UN",
      "quantidade": 1,
      "preco": 260.00,
      "valorDesconto": 10.00,
      "total": 250.00,
      "ncm": "85287200",
      "cfop": "5102",
      "tributacao": "T",
      "cstPis": "01",
      "cstCofins": "01",
      "aliquotaProduto": 1800,
      "aliquotaSaida": 1800,
      "precoVendaAtual": 260.00,
      "vendaPromocional": "N"
    }
  ],
  "nfce": {
    "chave": "31250971294573000113501250000001501234567890",
    "nfce": "NFCE",
    "serie": "012",
    "underline": "_"
  },
  "pagamentos": [
    {
      "cdFormaPagto": 3,
      "descForma": "CARTAO CREDITO",
      "nuParcelas": 3,
      "valorTotal": 250.00,
      "valorParcela": 83.33,
      "autorizacaoCreditoCompleto": "A1B2C3D4E5"
    }
  ],
  "registro": "51",
  "serie": "12",
  "uid": "f27f1d22-95bb-41af-8c8f-62dfcb7f12c2",
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc versao=\"4.00\" ...>",
  "xmlCancelado": ""
}

5. Boas Práticas / Observações

  • Validação: Certifique-se que campos obrigatórios estejam preenchidos, sobretudo datas no formato ISO 8601 e campos numéricos no formato correto.

  • Campos condicionais: Muitos campos (ex: promocional, descontoItens, trocoSolidario) são aplicáveis somente em cenários específicos.

  • Conversão de dados: Quantidades e valores devem ser transmitidos numéricos, não strings.

  • Versão do PDV: Importante para controle de compatibilidade de payloads.

  • Origem: Buscar definição do código de integração junto ao time da Avanço.

  • Número do DAV / Controle: Relevante para rastrear pré-vendas e cancelamentos no futuro.

 

 

No Comments
Back to top