# APIS do Novo Avanço

# Fluxo de interação com API para Ecommerce

> Observação: os nomes exatos de alguns campos podem variar conforme a sua configuração. Use esta referência como guia prático e confira o esquema no Swagger quando precisar do detalhe de cada propriedade. ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

# 1) Leitura de cadastro de produtos

Rota: **Buscar produtos para PDV** (cadastro básico para e-commerce/PDV) ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

- **Método/URL**: `GET /v1/public/produto/pdv`
- **Autenticação**: `Authorization: Bearer <token>`
- **Uso**: obter produtos novos/alterados para sincronização.

**Parâmetros (query) comuns**

- `dataInclusaoInicio`, `dataInclusaoFim` — ISO 8601.
- `dataAlteracaoCadastroInicio`, `dataAlteracaoCadastroFim`.
- `dataAlteracaoPrecoInicio`, `dataAlteracaoPrecoFim`.
- (Opcional) filtros como `ean`, `departamentoId`, `ativo` (quando aplicável).
- **Paginação** (quando disponível no seu tenant): `page`, `pageSize` (ou equivalentes).

**Resposta (resumo)**

- Lista de produtos com campos como: `produtoId`, `descricao`, `eanPrincipal`, `ncm`, `unidade`, `ativo`, metadados de inclusão/alteração.

**Exemplo cURL**

```bash
curl -X GET \
  'https://api.novo.infovarejo.com.br/v1/public/produto/pdv?dataInclusaoInicio=2022-04-02T07:00:00.000&dataInclusaoFim=2022-08-24T23:59:00.000&dataAlteracaoCadastroInicio=2022-04-02T07:00:00.000&dataAlteracaoCadastroFim=2022-08-24T23:59:00.000&dataAlteracaoPrecoInicio=2022-04-02T07:00:00.000&dataAlteracaoPrecoFim=2022-08-24T23:59:00.000&page=1&pageSize=100' \
  -H 'Authorization: Bearer <SEU_TOKEN>'

```

---

# 2) Leitura de Estoque e Preço

Rota: **Retorna fichas financeiras do produto** (preço/estoque para vitrine) ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

- **Método/URL**: `GET /v1/public/produto/fichaFinanceira`
- **Autenticação**: `Authorization: Bearer <token>`
- **Uso**: consultar preço, promoções e, em alguns ambientes, saldo/estoque por filial.

**Parâmetros (query) comuns**

- Identificador do produto (um ou mais): `ean`, `produtoId` (ou `sku`), etc.
- (Opcional) `filialId` para preço/estoque específico por loja.
- **Paginação** quando retornar múltiplos itens.

**Resposta (resumo)**

- Campos típicos: `produtoId`, `ean`, `precoVenda`, `precoPromocional` (se houver), `dataVigencia`, e possivelmente `estoqueAtual`/`saldo` por filial.

**Exemplo cURL**

```bash
curl -X GET \
  'https://api.novo.infovarejo.com.br/v1/public/produto/fichaFinanceira?ean=79075&filialId=123' \
  -H 'Authorization: Bearer <SEU_TOKEN>'

```

---

# 3) Consulta de clientes

Rota: **Retornar lista de clientes por empresa** ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

- **Método/URL**: `GET /v1/public/pessoa/clientes` (nome do path pode variar no Swagger sob Pessoa → Clientes)
- **Autenticação**: `Authorization: Bearer <token>`
- **Uso**: listar clientes para cadastro/checkout e-commerce.

**Parâmetros (query) comuns**

- `empresaId` (obrigatório na maioria dos cenários).
- Filtros: `cpfCnpj`, `nome`, `email`.
- Janelas de atualização: `dataAlteracaoInicio`, `dataAlteracaoFim`.
- **Paginação**: `page`, `pageSize`.

**Resposta (resumo)**

- Lista com `clienteId`, `nome`, `cpfCnpj`, `email`, `telefone`, endereços, flags (ativo), datas de alteração.

**Exemplo cURL**

```bash
curl -X GET \
  'https://api.novo.infovarejo.com.br/v1/public/pessoa/clientes?empresaId=1023&page=1&pageSize=100' \
  -H 'Authorization: Bearer <SEU_TOKEN>'

```

---

# 4) Gravação (upsert) de clientes

Rota: **Cadastra ou atualiza cliente** ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

- **Método/URL**: `POST /v1/public/pessoa/cliente`
- **Autenticação**: `Authorization: Bearer <token>`
- **Uso**: criar/atualizar cliente (CPF/CNPJ único).

**Body (JSON) — exemplo mínimo**

```json
{
  "empresaId": 1023,
  "cpfCnpj": "12345678901",
  "nome": "Maria Compradora",
  "email": "maria@exemplo.com",
  "telefone": "31999990000",
  "enderecos": [
    {
      "tipo": "ENTREGA",
      "logradouro": "Rua A, 100",
      "bairro": "Centro",
      "cidade": "Belo Horizonte",
      "uf": "MG",
      "cep": "30130000"
    }
  ]
}

```

**Exemplo cURL**

```bash
curl -X POST 'https://api.novo.infovarejo.com.br/v1/public/pessoa/cliente' \
  -H 'Authorization: Bearer <SEU_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @cliente.json

```

---

# 5) Consulta de vendedores

Rota: **Retornar lista de vendedores por empresa** ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

- **Método/URL**: `GET /v1/public/pessoa/vendedores`
- **Autenticação**: `Authorization: Bearer <token)`
- **Uso**: obter IDs/códigos de vendedores para atrelar em pedidos.

**Parâmetros (query)**

- `empresaId` (geralmente obrigatório).
- (Opcional) filtros por `ativo`, `matricula`, etc.
- **Paginação**: `page`, `pageSize`.

**Resposta (resumo)**

- `vendedorId`/`codigo`, `nome`, `ativo`, dados de contato.

**Exemplo cURL**

```bash
curl -X GET \
  'https://api.novo.infovarejo.com.br/v1/public/pessoa/vendedores?empresaId=1023&page=1&pageSize=100' \
  -H 'Authorization: Bearer <SEU_TOKEN>'

```

---

# 6) Gravação (upsert) de vendedores

Rota: **Upsert dados de vendedores** ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

- **Método/URL**: `POST /v1/public/pessoa/vendedores`
- **Autenticação**: `Authorization: Bearer <token)`
- **Uso**: criar/atualizar cadastro de vendedores.

**Body (JSON) — exemplo**

```json
{
  "empresaId": 1023,
  "vendedores": [
    {
      "codigo": "VEN001",
      "nome": "João Vendas",
      "email": "joao@exemplo.com",
      "ativo": true
    }
  ]
}

```

**Exemplo cURL**

```bash
curl -X POST 'https://api.novo.infovarejo.com.br/v1/public/pessoa/vendedores' \
  -H 'Authorization: Bearer <SEU_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @vendedores.json

```

---

# 7) Gravação de Pedido de Vendas (CPF/CNPJ)

Rota: **Pedido de venda por CPF/CNPJ** ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

- **Método/URL**: `POST /v1/public/pedido/venda/cpfcnpj`
- **Autenticação**: `Authorization: Bearer <token)`
- **Uso**: criar pedido de venda para cliente identificado (e-commerce / força de vendas).

**Body (JSON) — exemplo prático**

```json
{
  "empresaId": 1023,
  "filialId": 1901,
  "cliente": { "cpfCnpj": "12345678901" },
  "vendedorCodigo": "VEN001",
  "itens": [
    { "produtoId": 55555, "quantidade": 2, "precoUnitario": 19.9, "ean": "7891234567890" }
  ],
  "pagamentos": [
    { "meio": "CARTAO", "valor": 39.8, "parcelas": 1 }
  ],
  "observacao": "Pedido originado no e-commerce",
  "origem": "ECOMMERCE"
}

```

**Exemplo cURL**

```bash
curl -X POST 'https://api.novo.infovarejo.com.br/v1/public/pedido/venda/cpfcnpj' \
  -H 'Authorization: Bearer <SEU_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @pedido.json

```

---

## Convenções gerais

**Autenticação**

- Header: `Authorization: Bearer <token>` para todas as rotas públicas autenticadas. ([api.novo.infovarejo.com.br](https://api.novo.infovarejo.com.br/docs/public/ "Swagger UI"))

**Paginação**

- Quando disponível, use `page` (1-based) e `pageSize` (ex.: 50/100). As respostas costumam trazer metadados de total/última página.

**Códigos de resposta (mais comuns)**

- `200/201`: sucesso (lista/criação).
- `400`: validação de campos.
- `401/403`: token inválido/sem permissão.
- `404`: recurso não encontrado.
- `409`: conflito (ex.: CPF/CNPJ duplicado em upsert).
- `422`: erro de domínio (quando aplicável).
- `500`: erro interno.

**Boas práticas**

- Filtrar por janelas de **data de inclusão/alteração** para cargas incrementais.
- Tratar **timeout** e **retries** para rotas que retornam grandes volumes.
- Registrar `empresaId` e `filialId` corretamente para operações sensíveis a contexto (preço, estoque, pedido).
- Logar `requestId`/`correlationId` (se fornecido) para rastreabilidade.

Acesso a documentação Swagger completa em: https://api.novo.infovarejo.com.br/docs/public/

# 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`)

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

---

#### 3.2 Itens (`itens`)

Para cada item vendido:

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

---

### 4. Exemplo de JSON completo (simplificado)

```json
{
  "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.

---