# Visão Geral

<div class="pw" id="bkmrk-cap%C3%ADtulo-1"><div class="ph"></div></div>## O que consolidamos

Nossa integração coleta dados de vendas de **quatro canais distintos** e os entrega à FullStore em um único JSON estruturado, permitindo que a plataforma calcule comissões e analise o desempenho de cada vendedor sem precisar acessar diretamente os bancos de dados internos.

<div class="pw" id="bkmrk-%F0%9F%8F%AA"><div class="fg"><div class="fi"><div class="ic">🏪</div></div></div></div>#### PDV

Vendas realizadas no balcão da loja física, com itens e NF-e.

<div class="pw" id="bkmrk-%F0%9F%94%84"><div class="fg"><div class="fi"><div class="ic">🔄</div></div></div></div>#### Trocas

Devoluções e trocas vinculadas à NF da venda original.

<div class="pw" id="bkmrk-%F0%9F%9A%9A"><div class="fg"><div class="fi"><div class="ic">🚚</div></div></div></div>#### Omni

Pedido criado pelo vendedor na loja com entrega em domicílio ou retirada em outra unidade.

<div class="pw" id="bkmrk-%F0%9F%9B%92"><div class="fg"><div class="fi"><div class="ic">🛒</div></div></div></div>#### E-commerce

Pedidos do site processados pelo sistema Linx (SQL Server).

## Sistemas envolvidos

<div class="pw" id="bkmrk-sistema-papel-banco-"><div class="tw"><table><thead><tr><th>Sistema</th><th>Papel</th><th>Banco</th></tr></thead><tbody><tr><td>**ERP OSK (loja)**</td><td>Fonte de dados — PDV, Trocas, Omni</td><td>MySQL</td></tr><tr><td>**Linx**</td><td>Fonte de dados — E-commerce e BI</td><td>SQL Server `LX_ZERO_300`</td></tr><tr><td>**FullStore**</td><td>Consumidora da API</td><td>—</td></tr></tbody></table>

</div></div>## Ação disponível

Disponibilizamos uma única ação: `getVendas`. Ela recebe CNPJ da loja e intervalo de datas, consulta os quatro canais em sequência e retorna tudo consolidado.

## Estrutura da resposta

```
{
  "success": true,
  "message": "Vendas retornadas com sucesso!",
  "data": {
    "vendas":           [ /* PDV — vendas com itens agrupados       */ ],
    "trocas":           [ /* Trocas agrupadas por NF original        */ ],
    "omni":             [ /* Pedidos omni com entrega/retirada        */ ],
    "vendas_ecommerce": [ /* Pedidos e-commerce vindos do SQL Server  */ ],
    "fallback": null      /* Preenchido se o período exceder o limite */
  }
}
```

## Restrições de período

<div class="pw" id="bkmrk-limite-de-200-dias-n"><div class="wb">**Limite de 200 dias no passado** Consultamos no máximo **200 dias retroativos** (`LIMITE_DIAS_CONSULTA = 200`). Se `dataInicio` ou `dataFim` estiver além desse limite, retornamos `success: true` com todos os arrays vazios e o objeto `fallback` preenchido com os parâmetros recebidos — sem erro de sistema.</div><div class="wb">**CNPJ obrigatório** O `cnpjLoja` é obrigatório e filtra *todos* os canais. Sem ele, a requisição falha na validação antes de qualquer consulta ao banco.</div>  
</div>