> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Varejo Online as a data source

> Bring data from Varejo Online to Nekt.

Varejo Online is a comprehensive retail management platform designed for Brazilian businesses. It provides tools for sales management, inventory control, order processing, and point-of-sale operations, helping retailers streamline their operations across physical stores and digital channels.

<img width="200" src="https://mintcdn.com/nekt/E6P5MfhHEqSluGws/assets/logo/logo-varejo-online.png?fit=max&auto=format&n=E6P5MfhHEqSluGws&q=85&s=2a221f68d7efd1d5ec244e3e69d5770e" data-path="assets/logo/logo-varejo-online.png" />

## Configuring Varejo Online as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Varejo Online option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

You'll need your Varejo Online API Token for this connection. This token authenticates your requests to the Varejo Online API.

* **Token**: The authentication token for the Varejo Online API. Required. Contact your Varejo Online account manager or support team to obtain your API token.
* **Start Date**: (Optional) The earliest date from which records will be synced for incremental streams. Used for **orders**, **products**, **stock**, **net\_stock**, and **price\_table\_products** based on the `dataAlteracao` or `alteradoApos` (last modified date) field. You can use common date formats (e.g. `2024-01-01`).

<Warning>Store your token securely. Treat it like a password and do not share it publicly.</Warning>

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. Varejo Online provides access to orders, products, stock (inventory), net stock, price tables, products per price table, and digital channels.

> Tip: The stream can be found more easily by typing its name.

**Note:** The **price\_table\_products** stream is a child of **price\_tables**: it fetches products and prices for each price table. Selecting **price\_table\_products** will sync data for every price table.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
  * **Incremental**: every time the extraction happens, we'll get only records created or modified since the last sync. Supported for **orders**, **products**, **stock**, **net\_stock**, **price\_table\_products**, and **digital\_channels**.
  * **Full table**: every time the extraction happens, we'll get the current state of the data. Use for **price\_tables** or when you prefer a full refresh.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

## Stream to Endpoint Mapping

| Stream                 | API Endpoint                                            | Sync Type   | Replication Key |
| ---------------------- | ------------------------------------------------------- | ----------- | --------------- |
| orders                 | `/pedidos`                                              | Incremental | `dataAlteracao` |
| products               | `/produtos`                                             | Incremental | `dataAlteracao` |
| stock                  | `/saldos-mercadorias`                                   | Incremental | `dataAlteracao` |
| net\_stock             | `/saldos-mercadorias/liquido`                           | Incremental | `alteradoApos`  |
| price\_tables          | `/tabelas-preco`                                        | Full table  | —               |
| price\_table\_products | `/tabelas-preco/{id}/produtos` (child of price\_tables) | Incremental | `dataAlteracao` |
| digital\_channels      | `/canais-digitais`                                      | Incremental | `dataAlteracao` |

# Streams and Fields

Below you'll find all available data streams from Varejo Online and their corresponding fields:

<AccordionGroup>
  <Accordion title="Orders (orders)">
    Stream containing all sales orders from your Varejo Online account (GET `/pedidos`). Supports **incremental sync** based on the `dataAlteracao` (last modification date) field. Primary key: `id`.

    **Identifiers**

    | Field                 | Type    | Description                          |
    | --------------------- | ------- | ------------------------------------ |
    | `id`                  | Integer | Order ID                             |
    | `idSaida`             | Integer | Linked output ID                     |
    | `numero`              | String  | Order number generated by the system |
    | `numeroPedidoCliente` | String  | Customer's reference order number    |
    | `idEntidade`          | Integer | Entity ID of the order               |
    | `idTerceiroCliente`   | Integer | Third-party customer ID              |
    | `idRepresentante`     | Integer | Representative/salesperson ID        |
    | `idProvisao`          | Integer | Provision ID generated by the order  |
    | `idCanalDigital`      | Integer | Digital channel ID                   |

    **Dates & Times**

    | Field           | Type   | Description                                                                |
    | --------------- | ------ | -------------------------------------------------------------------------- |
    | `data`          | String | Order issue date                                                           |
    | `horario`       | String | Order creation time (format: hh:mm:ss)                                     |
    | `dataAlteracao` | String | Last modification date (format: dd-mm-yyyy hh:mi:ss) - **Replication Key** |

    **Order Status**

    | Field                             | Type    | Description                    |
    | --------------------------------- | ------- | ------------------------------ |
    | `cancelado`                       | Boolean | Whether the order is cancelled |
    | `statusConferencia`               | String  | Conference status of the order |
    | `statusVenda`                     | String  | Sales status                   |
    | `statusPedidoVenda.id`            | Integer | Status ID                      |
    | `statusPedidoVenda.nome`          | String  | Status name                    |
    | `statusPedidoVenda.descricao`     | String  | Status description             |
    | `statusPedidoVenda.dataAlteracao` | String  | Status modification date       |
    | `statusPedidoVenda.dataCriacao`   | String  | Status creation date           |
    | `statusPedidoVenda.ativo`         | Boolean | Whether status is active       |
    | `statusPedidoVenda.deletado`      | Boolean | Whether status is deleted      |

    **Financial Values**

    | Field             | Type   | Description                      |
    | ----------------- | ------ | -------------------------------- |
    | `valorFrete`      | Number | Shipping value                   |
    | `valorSeguro`     | Number | Insurance value                  |
    | `valorOutros`     | Number | Other costs                      |
    | `valorTotal`      | Number | Total order value                |
    | `valorLiquido`    | Number | Net order value                  |
    | `valorDesconto`   | Number | Discount value                   |
    | `valorAcrescimo`  | Number | Addition/surcharge value         |
    | `valeTrocaGerado` | Number | Generated exchange voucher value |

    **Entity Information**

    | Field                | Type    | Description            |
    | -------------------- | ------- | ---------------------- |
    | `entidade.id`        | Integer | Entity ID              |
    | `entidade.nome`      | String  | Entity name            |
    | `entidade.documento` | String  | Store's formatted CNPJ |

    **Customer Information**

    | Field               | Type    | Description                   |
    | ------------------- | ------- | ----------------------------- |
    | `cliente.id`        | Integer | Customer ID                   |
    | `cliente.nome`      | String  | Customer name                 |
    | `cliente.documento` | String  | Customer's formatted CNPJ/CPF |
    | `documentoTerceiro` | String  | Third-party document          |

    **Salesperson Information**

    | Field                     | Type    | Description                 |
    | ------------------------- | ------- | --------------------------- |
    | `representante.id`        | Integer | Salesperson ID              |
    | `representante.nome`      | String  | Salesperson name            |
    | `representante.documento` | String  | Salesperson's formatted CPF |

    **Order Details**

    | Field                  | Type    | Description                                            |
    | ---------------------- | ------- | ------------------------------------------------------ |
    | `origem`               | String  | Order origin (e.g., MARKETPLACE)                       |
    | `tipo`                 | String  | Order type (NORMAL, SHIP\_FROM\_STORE, CLICK\_COLLECT) |
    | `sistemaOrigem`        | String  | Source system                                          |
    | `nomeTerminal`         | String  | Terminal name where order was placed                   |
    | `planoPagamento`       | String  | Payment plan                                           |
    | `vendaConsumidorFinal` | Boolean | Whether it's a sale to final consumer                  |
    | `descontoDetalhes`     | String  | Discount details                                       |
    | `observacao`           | String  | Order observation/notes                                |

    **Order Items (`itens[]`)**

    | Field                             | Type    | Description                          |
    | --------------------------------- | ------- | ------------------------------------ |
    | `itens[].id`                      | Integer | Item ID                              |
    | `itens[].idProduto`               | Integer | Product ID                           |
    | `itens[].idRepresentante`         | Integer | Representative ID for this item      |
    | `itens[].quantidade`              | Number  | Quantity                             |
    | `itens[].operacao`                | String  | Item operation                       |
    | `itens[].descricao`               | String  | Item description                     |
    | `itens[].unidade`                 | String  | Measurement unit                     |
    | `itens[].valorTotal`              | Number  | Total item value                     |
    | `itens[].valorDesconto`           | Number  | Item discount                        |
    | `itens[].valorAcrescimo`          | Number  | Item surcharge                       |
    | `itens[].valorDescontoRateado`    | Number  | Prorated discount value              |
    | `itens[].valorDescontoItem`       | Number  | Specific item discount               |
    | `itens[].valorFreteRateado`       | Number  | Prorated shipping value              |
    | `itens[].valorCusto`              | Number  | Cost value                           |
    | `itens[].descontoDetalhes`        | String  | Discount details                     |
    | `itens[].dataEntrega`             | String  | Delivery date                        |
    | `itens[].reservarEstoque`         | Boolean | Whether to reserve stock             |
    | `itens[].tabelaPrecoId`           | Integer | Price table ID                       |
    | `itens[].valorICMS`               | Number  | ICMS tax value                       |
    | `itens[].valorICMSItem`           | Number  | ICMS tax value for item              |
    | `itens[].valorICMSFrete`          | Number  | ICMS tax value for shipping          |
    | `itens[].valorICMSST`             | Number  | ICMS-ST tax value                    |
    | `itens[].valorIPI`                | Number  | IPI tax value                        |
    | `itens[].valorPIS`                | Number  | PIS tax value                        |
    | `itens[].valorCOFINS`             | Number  | COFINS tax value                     |
    | `itens[].valorFCPST`              | Number  | FCP-ST tax value                     |
    | `itens[].produto.id`              | Integer | Product ID                           |
    | `itens[].produto.descricao`       | String  | Product description                  |
    | `itens[].produto.codigoBarras`    | String  | Product barcode                      |
    | `itens[].produto.codigoInterno`   | String  | Internal product code                |
    | `itens[].produto.codigoSistema`   | String  | System product code                  |
    | `itens[].representante.id`        | Integer | Item salesperson ID                  |
    | `itens[].representante.nome`      | String  | Item salesperson name                |
    | `itens[].representante.documento` | String  | Item salesperson CPF                 |
    | `itens[].epcs[]`                  | Array   | Electronic Product Codes (RFID tags) |
    | `itens[].lotes[]`                 | Array   | Product lots                         |
    | `itens[].numerosValesPresentes[]` | Array   | Gift voucher numbers used            |

    **Payment Composition (`composicaoPagamento`)**

    | Field                                   | Type    | Description                  |
    | --------------------------------------- | ------- | ---------------------------- |
    | `composicaoPagamento.saidaId`           | Integer | Output ID related to payment |
    | `composicaoPagamento.valorDinheiro`     | Number  | Cash payment value           |
    | `composicaoPagamento.valorChequeVista`  | Number  | Check payment (cash)         |
    | `composicaoPagamento.valorChequePrazo`  | Number  | Check payment (term)         |
    | `composicaoPagamento.valorCrediario`    | Number  | Credit plan value            |
    | `composicaoPagamento.valorVoucher`      | Number  | Voucher payment value        |
    | `composicaoPagamento.valorValePresente` | Number  | Gift voucher value           |
    | `composicaoPagamento.valorTroca`        | Number  | Exchange value               |
    | `composicaoPagamento.valorAdiantamento` | Number  | Advance payment value        |
    | `composicaoPagamento.idPlanoCrediario`  | Integer | Credit plan ID               |
    | `composicaoPagamento.plano.id`          | Integer | Payment plan ID              |
    | `composicaoPagamento.plano.descricao`   | String  | Payment plan description     |

    **Card Payments (`composicaoPagamento.valoresCartao[]`)**

    | Field                            | Type    | Description                         |
    | -------------------------------- | ------- | ----------------------------------- |
    | `valoresCartao[].valor`          | Number  | Card payment value                  |
    | `valoresCartao[].nsu`            | String  | NSU (Número Sequencial Único)       |
    | `valoresCartao[].bandeira`       | String  | Card brand (VISA, MASTERCARD, etc.) |
    | `valoresCartao[].tipoCartao`     | String  | Card type (DEBITO, CREDITO)         |
    | `valoresCartao[].operadora`      | String  | Card operator (GETNET, CIELO, etc.) |
    | `valoresCartao[].numeroParcelas` | Integer | Number of installments              |
    | `valoresCartao[].autorizacao`    | String  | Authorization code                  |

    **PIX Payments (`composicaoPagamento.valoresPix[]`)**

    | Field                      | Type   | Description                   |
    | -------------------------- | ------ | ----------------------------- |
    | `valoresPix[].valor`       | Number | PIX payment value             |
    | `valoresPix[].nsu`         | String | NSU (Número Sequencial Único) |
    | `valoresPix[].autorizacao` | String | Authorization code            |

    **Payment Plan (`plano`)**

    | Field             | Type    | Description      |
    | ----------------- | ------- | ---------------- |
    | `plano.id`        | Integer | Plan ID          |
    | `plano.descricao` | String  | Plan description |

    **Installments (`parcelas[]`)**

    | Field                       | Type    | Description       |
    | --------------------------- | ------- | ----------------- |
    | `parcelas[].id`             | Integer | Installment ID    |
    | `parcelas[].valor`          | Number  | Installment value |
    | `parcelas[].dataVencimento` | String  | Due date          |

    **Invoices (`notasFiscais[]`)**

    | Field                           | Type    | Description                     |
    | ------------------------------- | ------- | ------------------------------- |
    | `notasFiscais[].status`         | String  | Invoice status                  |
    | `notasFiscais[].idNotaFiscal`   | Integer | Invoice ID                      |
    | `notasFiscais[].tipoNotaFiscal` | String  | Invoice type (e.g., MERCADORIA) |

    **Delivery Address (`enderecoEntrega`)**

    | Field                                      | Type   | Description                   |
    | ------------------------------------------ | ------ | ----------------------------- |
    | `enderecoEntrega.logradouro`               | String | Street name                   |
    | `enderecoEntrega.numero`                   | String | Street number                 |
    | `enderecoEntrega.complemento`              | String | Address complement            |
    | `enderecoEntrega.bairro`                   | String | Neighborhood                  |
    | `enderecoEntrega.cep`                      | String | Postal code (CEP)             |
    | `enderecoEntrega.cidade`                   | String | City                          |
    | `enderecoEntrega.uf`                       | String | State (UF)                    |
    | `enderecoEntrega.receptorEntrega`          | String | Recipient name                |
    | `enderecoEntrega.receptorEntregaDocumento` | String | Recipient document (CPF/CNPJ) |

    **Transport (`transporte`)**

    | Field                                | Type    | Description                         |
    | ------------------------------------ | ------- | ----------------------------------- |
    | `transporte.modalidade`              | String  | Transport modality (e.g., EMITENTE) |
    | `transporte.transportador.id`        | Integer | Carrier ID                          |
    | `transporte.transportador.documento` | String  | Carrier document (CNPJ)             |
    | `transporte.codigoANTT`              | String  | ANTT code                           |
    | `transporte.placaVeiculo`            | String  | Vehicle plate                       |
    | `transporte.estadoVeiculo`           | String  | Vehicle registration state          |
    | `transporte.quantidade`              | String  | Number of volumes                   |
    | `transporte.especie`                 | String  | Volume type (e.g., CAIXA)           |
    | `transporte.marca`                   | String  | Volume brand                        |
    | `transporte.numero`                  | String  | Volume number                       |
    | `transporte.pesoBruto`               | Number  | Gross weight (kg)                   |
    | `transporte.pesoLiquido`             | Number  | Net weight (kg)                     |

    **Intermediary (`intermediador`)**

    | Field                     | Type    | Description         |
    | ------------------------- | ------- | ------------------- |
    | `intermediador.id`        | Integer | Intermediary ID     |
    | `intermediador.documento` | String  | Intermediary's CNPJ |

    **Additional Fields**

    | Field                                   | Type   | Description                        |
    | --------------------------------------- | ------ | ---------------------------------- |
    | `idsOrcamentos[]`                       | Array  | Related quote IDs                  |
    | `servicos[]`                            | Array  | Services associated with the order |
    | `valeTrocasUtilizados[].valorUtilizado` | Number | Exchange voucher value used        |
  </Accordion>

  <Accordion title="Stock (stock)">
    Stream containing inventory/stock balances for products across entities (GET `/saldos-mercadorias`). Supports **incremental sync** based on the `dataAlteracao` (last modified date) field.

    **Primary Keys:** `idProduto`, `idEntidade` (composite)

    **Core Fields**

    | Field           | Type     | Description                                  |
    | --------------- | -------- | -------------------------------------------- |
    | `idProduto`     | Integer  | Product ID (primary key)                     |
    | `idEntidade`    | Integer  | Entity ID (primary key)                      |
    | `quantidade`    | Number   | Stock quantity                               |
    | `data`          | Date     | Stock information date                       |
    | `dataAlteracao` | DateTime | Last modification date - **Replication Key** |

    **Entity Information (`entidade`)**

    | Field                | Type    | Description            |
    | -------------------- | ------- | ---------------------- |
    | `entidade.id`        | Integer | Entity ID              |
    | `entidade.nome`      | String  | Entity name            |
    | `entidade.documento` | String  | Entity document (CNPJ) |

    **Product Information (`produto`)**

    | Field                   | Type    | Description           |
    | ----------------------- | ------- | --------------------- |
    | `produto.id`            | Integer | Product ID            |
    | `produto.codigoBarras`  | String  | Product barcode       |
    | `produto.descricao`     | String  | Product description   |
    | `produto.codigoInterno` | String  | Internal product code |
    | `produto.codigoSistema` | String  | System product code   |
  </Accordion>

  <Accordion title="Net Stock (net_stock)">
    Stream containing net stock balances for merchandise from Varejo Online (GET `/saldos-mercadorias/liquido`). Supports **incremental sync** based on the `alteradoApos` field.

    **Primary Keys:** `idProduto`, `idEntidade` (composite)

    **Core Fields**

    | Field                       | Type     | Description                                                             |
    | --------------------------- | -------- | ----------------------------------------------------------------------- |
    | `idProduto`                 | Integer  | Product ID (primary key)                                                |
    | `idEntidade`                | Integer  | Entity ID (primary key)                                                 |
    | `estoqueMinimo`             | Number   | Minimum stock                                                           |
    | `estoqueMaximo`             | Number   | Maximum stock                                                           |
    | `saldoAtual`                | Number   | Current available balance                                               |
    | `quantidadeEstoqueTransito` | Number   | Quantity in transit from unfinished transfers and purchase orders       |
    | `quantidadeReservada`       | Number   | Reserved quantity                                                       |
    | `quantidadeEpcsAtivo`       | Number   | Quantity of active EPCs                                                 |
    | `alteradoApos`              | DateTime | Modification date used to extract the information - **Replication Key** |

    **Entity Information (`entidade`)**

    | Field                | Type    | Description            |
    | -------------------- | ------- | ---------------------- |
    | `entidade.id`        | Integer | Entity ID              |
    | `entidade.nome`      | String  | Entity name            |
    | `entidade.documento` | String  | Entity document (CNPJ) |

    **Product Information (`produto`)**

    | Field                   | Type    | Description           |
    | ----------------------- | ------- | --------------------- |
    | `produto.id`            | Integer | Product ID            |
    | `produto.codigoBarras`  | String  | Product barcode       |
    | `produto.descricao`     | String  | Product description   |
    | `produto.codigoInterno` | String  | Internal product code |
    | `produto.codigoSistema` | String  | System product code   |

    **Nested / Arrays**

    | Field        | Type  | Description              |
    | ------------ | ----- | ------------------------ |
    | `epcsAtivos` | Array | List of active EPC codes |
  </Accordion>

  <Accordion title="Products (products)">
    Stream containing product catalog from your Varejo Online account (GET `/produtos`). Supports **incremental sync** based on the `dataAlteracao` (last modified date) field. Primary key: `id`.

    **Core Fields**

    | Field                   | Type    | Description                                  |
    | ----------------------- | ------- | -------------------------------------------- |
    | `id`                    | Integer | Product ID                                   |
    | `descricao`             | String  | Product description                          |
    | `codigoInterno`         | String  | Internal product code                        |
    | `codigoBarras`          | String  | Product barcode                              |
    | `codigoSistema`         | String  | System product code                          |
    | `codigoNcm`             | String  | NCM code                                     |
    | `codigoSKU`             | String  | SKU                                          |
    | `dataCriacao`           | String  | Creation date (dd-mm-aaaa hh:mi:ss)          |
    | `dataAlteracao`         | String  | Last modification date - **Replication Key** |
    | `unidade`               | String  | Sales unit                                   |
    | `preco`                 | Number  | Product price                                |
    | `custoReferencial`      | Number  | Reference cost                               |
    | `descontoMaximo`        | Number  | Maximum discount allowed                     |
    | `ativo`                 | Boolean | Whether product is active                    |
    | `deletado`              | Boolean | Whether product is deleted                   |
    | `permiteVenda`          | Boolean | Whether product can be sold                  |
    | `controlaLote`          | Boolean | Whether product uses lot control             |
    | `controlaValidadeLote`  | Boolean | Whether lot expiry is controlled             |
    | `estoqueMinimo`         | Number  | Minimum stock                                |
    | `estoqueMaximo`         | Number  | Maximum stock                                |
    | `peso`                  | Number  | Product weight                               |
    | `comissao`              | Number  | Commission                                   |
    | `margemLucro`           | Number  | Profit margin                                |
    | `porcentagemRoyalties`  | Number  | Percentage of royalties for the product      |
    | `disponivelEcommerce`   | Boolean | Available for e-commerce                     |
    | `disponivelMarketplace` | Boolean | Available for marketplaces                   |

    **Nested / Arrays**

    | Field                  | Type   | Description                                                                  |
    | ---------------------- | ------ | ---------------------------------------------------------------------------- |
    | `produtoBase`          | Object | Base product (id, nome, codigoSistema)                                       |
    | `categorias`           | Array  | Categories (id, nivel, nome)                                                 |
    | `fornecedores`         | Array  | Suppliers (cnpj, codigo)                                                     |
    | `dadosPorEntidade`     | Array  | Per-entity data (entidade, codBeneficioFiscal, estoqueMinimo, estoqueMaximo) |
    | `descontoProgressivo`  | Array  | Progressive discounts (desconto, qtde, ativo, tipoDesconto)                  |
    | `valorAtributos`       | Array  | Attribute values (id, valor, nome, codigo)                                   |
    | `listCustoReferencial` | Array  | Reference costs per entity (precoCusto, entidade)                            |
  </Accordion>

  <Accordion title="Price Tables (price_tables)">
    Stream containing price tables (GET `/tabelas-preco`). Full table sync only (no replication key). Primary key: `id`. Table with ID 1 is always the system default. **price\_table\_products** is a child stream of this one.

    **Key Fields**

    | Field                       | Type    | Description                                                |
    | --------------------------- | ------- | ---------------------------------------------------------- |
    | `id`                        | Integer | Price table ID                                             |
    | `nome`                      | String  | Price table name                                           |
    | `idsEntidades`              | Array   | Entity IDs for which the table is valid (empty = all)      |
    | `idsClassificacoesClientes` | Array   | Customer classification IDs (empty = all)                  |
    | `classificacoesCliente`     | Array   | Customer classifications (id, nome)                        |
    | `disponivel`                | Boolean | Whether table is available at query time (validity)        |
    | `ativo`                     | Boolean | Whether table can be applied                               |
    | `permanente`                | Boolean | Whether table is permanent                                 |
    | `promocao`                  | Boolean | Whether table is promotional                               |
    | `excluido`                  | Boolean | Whether table was deleted in the system                    |
    | `inicioVigencia`            | String  | Start date when table can be applied (dd-mm-aaaa hh:mi:ss) |
    | `fimVigencia`               | String  | End date when table can be applied (dd-mm-aaaa hh:mi:ss)   |
    | `peso`                      | Integer | Weight for table application (higher weight wins at sale)  |
    | `compra`                    | Boolean | Whether table applies to purchases                         |
    | `aplicaDesconto`            | Boolean | Whether table applies discount                             |
    | `tabelaReferenciaDesconto`  | Object  | Reference table for discount (id, nome)                    |
  </Accordion>

  <Accordion title="Price Table Products (price_table_products)">
    Stream containing products and prices per price table (GET `/tabelas-preco/{id}/produtos`). **Child stream of price\_tables** — one partition per price table. Supports **incremental sync** based on `dataAlteracao`. Primary keys: `idTabelaPreco`, `idProduto`.

    **Key Fields**

    | Field             | Type    | Description                                  |
    | ----------------- | ------- | -------------------------------------------- |
    | `idTabelaPreco`   | Integer | Price table ID                               |
    | `idProduto`       | Integer | Product ID                                   |
    | `id`              | Integer | Record ID in price table                     |
    | `preco`           | Number  | Product price in this table                  |
    | `dataAlteracao`   | String  | Last modification date - **Replication Key** |
    | `ativo`           | Boolean | Whether this price is active                 |
    | `nomeTabelaPreco` | String  | Price table name                             |
    | `isFromESB`       | Boolean | Whether record comes from ESB                |

    **Product (object)**

    | Field                   | Type    | Description         |
    | ----------------------- | ------- | ------------------- |
    | `produto.id`            | Integer | Product ID          |
    | `produto.descricao`     | String  | Product description |
    | `produto.codigoSistema` | String  | System code         |
    | `produto.codigoInterno` | String  | Internal code       |
    | `produto.codigoBarras`  | String  | Barcode             |

    **History (optional)**

    | Field       | Type  | Description                                                                          |
    | ----------- | ----- | ------------------------------------------------------------------------------------ |
    | `historico` | Array | Price change history (dataAlteracao, preco, ativo, terceiroAlteracao) when requested |
  </Accordion>

  <Accordion title="Digital Channels (digital_channels)">
    Stream containing digital channels from your Varejo Online account (GET `/canais-digitais`). Supports **incremental sync** based on the `dataAlteracao` (last modification date) field. Primary key: `id`.

    **Key Fields**

    | Field           | Type    | Description                                  |
    | --------------- | ------- | -------------------------------------------- |
    | `id`            | Integer | Digital channel ID                           |
    | `nome`          | String  | Channel name                                 |
    | `ativo`         | Boolean | Whether the channel is active                |
    | `excluido`      | Boolean | Whether the channel is deleted               |
    | `dataAlteracao` | String  | Last modification date - **Replication Key** |
  </Accordion>
</AccordionGroup>

# Data Model

The following diagram illustrates the main relationships. **price\_table\_products** is a child of **price\_tables** (one partition per price table). **orders** reference **products**, entities, and digital channels; **stock** and **net\_stock** are per product and entity.

```mermaid theme={null}
graph TD;
    subgraph "Catalog & Pricing"
        Products("products");
        PriceTables("price_tables");
        PriceTableProducts("price_table_products");
        DigitalChannels("digital_channels");
    end

    subgraph "Transactions & Inventory"
        Orders("orders");
        Stock("stock");
        NetStock("net_stock");
    end

    PriceTableProducts -- "idTabelaPreco" --> PriceTables;
    PriceTableProducts -- "idProduto" --> Products;
    Stock -- "idProduto" --> Products;
    NetStock -- "idProduto" --> Products;
    Orders -- "itens[].idProduto" --> Products;
    Orders -- "idCanalDigital" --> DigitalChannels;
```

## Implementation Notes

### Data Sync Considerations

* **Incremental Sync**: The **orders**, **products**, **stock**, **net\_stock**, **price\_table\_products**, and **digital\_channels** streams support incremental sync using the `dataAlteracao` or `alteradoApos` (last modification date) field. Only records created or modified since the last sync (or since **Start Date** on first run) are extracted.

* **Full Table**: The **price\_tables** stream has no replication key; use full table sync to refresh all price table definitions.

* **Date Formats**: Varejo Online uses Brazilian date formats. The `data` field uses `dd-mm-yyyy` format, and `dataAlteracao`/`alteradoApos` uses `dd-mm-yyyy hh:mi:ss` format. You can configure **Start Date** using common date formats; the tap sends it to the API as `alteradoApos` in this format.

* **Child Stream**: **price\_table\_products** is a child of **price\_tables**. The tap first syncs all price tables, then requests products and prices for each table. Selecting both streams will result in one price\_table\_products partition per price table.

* **Brazilian Tax Fields**: Order items include various Brazilian tax fields such as ICMS, ICMS-ST, IPI, PIS, COFINS, and FCP-ST. These are important for fiscal compliance and financial analysis.

### Payment Methods

Varejo Online supports multiple payment methods that are captured in the `composicaoPagamento` object:

* Cash (dinheiro)
* Check - cash and term (cheque)
* Credit cards with detailed transaction data (NSU, authorization, flag, operator)
* PIX payments with transaction identifiers
* Vouchers and gift cards
* Store credit (crediário)
* Exchange vouchers (vale troca)

### Order Types

Orders can be classified by type:

* **NORMAL**: Standard orders
* **SHIP\_FROM\_STORE**: Orders fulfilled from physical store inventory
* **CLICK\_COLLECT**: Buy online, pick up in store orders

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

<Card title="Download Varejo Online skills file" icon="wand-magic-sparkles" href="/sources/varejo-online.md">
  Varejo Online connector documentation as plain markdown, for use in AI agent contexts.
</Card>
