Fullstore

• Visão Geral
• Arquitetura e Tecnologias
• Fluxo Funcional
• Canal PDV — Vendas
• Canal Trocas e Devoluções
• Canal Omni
• Canal E-commerce
• API — Parâmetros e Resposta
• Configuração e Dependências
• Troubleshooting e Testes

Visão Geral

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.

PDV

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

Trocas

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

Omni

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

E-commerce

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

Sistemas envolvidos

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

Arquitetura e Tecnologias

Stack técnico, hierarquia de classes, dependências e conexões com bancos de dados.

Diagrama de componentes

Stack

Hierarquia de classes

Arquivos required

Em controle.php, carregamos três dependências via require_once(APPPATH . '...'):

Conexão MySQL

A classe utilOsk chama getConfiguracao('db_osk_prod') — credenciais armazenadas em Base64 na tabela de configuração do sistema. Em seguida, _setConexao() cria a conexão PDO:

// connection string:
"mysql:host={host};port={porta};dbname={banco}"
// PDO::ATTR_PERSISTENT  = true   (conexão persistente)
// PDO::ATTR_TIMEOUT     = 120    (timeout em segundos)
// charset               = UTF-8

Conexão SQL Server

$sqlserver = new \db_sqlserver(false, 'LX_ZERO_300', true);
// false  = produção (não homologação)
// 'LX_ZERO_300' = banco Linx
// true   = conecta imediatamente

Tabelas MySQL utilizadas

Objetos SQL Server utilizados

Fluxo Funcional

Passo a passo de uma requisição, validações e tratamento de erros.

Diagrama de sequência

Diagrama de fluxo (decisões)

Passo a passo detalhado

Tratamento de erros

Canal PDV — Vendas

Capturamos as vendas registradas no módulo PDV  — transações de saída com NF-e autorizada/cancelada quando existir vínculo em movimentacao_nfe. Cada venda pode ter um ou mais itens; nossa query retorna uma linha por item e o método agruparItensDasVendas() os agrupa em um array aninhado itens.

Métodos: consultarVendasPdv() → agruparItensDasVendas()

Relacionamento das tabelas

Filtros aplicados

Estrutura da query (2 CTEs)

O SELECT final une os dois CTEs retornando uma linha por item, depois agrupamos em PHP.

Retorno da API

// Um elemento do array "vendas"
{
  "codigo_cliente":  123,
  "cod_vendedor":    "V001",
  "cnpj_emp":        "12345678000190",
  "data_documento":  "2026-05-15T10:30:00-03:00",   // ISO 8601
  "identificador":   9001,
  "transacao":       9001,
  "usuario":         42,
  "documento":       "000001234",   // Número NF-e
  "serie":           "001",
  "operacao":        "S",
  "tipo_transacao":  "VENDA",       // Fixo neste canal
  "cancelado":       "N",           // Derivado de movimentacao.situacao; na query atual tende a "N"
  "delivery":        false,
  "itens": [
    {
      "cod_produto":        "PROD-001",
      "descricao_produto":  "Camiseta Branca M",
      "cod_barra":          "7891234567890",
      "quantidade":         2,
      "preco_unitario":     89.90,
      "valor_total":        179.80
    }
  ]
}

Dicionário de campos

Canal Trocas e Devoluções

Capturamos movimentações de entrada do tipo TROCA. Quando o cliente devolve ou troca uma peça, o sistema OSK registra uma nova movimentação de entrada e a vincula à venda original via tabela movimentacao_movimentacao.

Métodos: getTrocas() → agruparTrocasPorDocumento()

Vínculo troca ↔ venda original

Filtros aplicados

Estrutura da query (3 CTEs)

Agrupamento por documento

A mesma NF pode ter múltiplas trocas (cliente troca um item hoje e outro amanhã). Em agruparTrocasPorDocumento() consolidamos assim:

Retorno da API

// Um elemento do array "trocas"
{
  "motivo":         "Defeito no produto",
  "doc_venda":      "000001234",             // NF da venda original
  "serie_venda":    "001",
  "cod_cliente":    123,
  "cnpj_emp":       "12345678000190",
  "valor_vale":     89.90,                   // Crédito gerado para o cliente
  "valor_original": 89.90,                   // Mesmo valor agregado da troca na implementação atual
  "timestamp":      "2026-05-18T14:22:00-03:00",
  "cod_vendedor":   "V001",
  "quantidade":     1
}

Dicionário de campos

Canal Omni

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

Fluxo do pedido omni

O cliente vai fisicamente até a loja. O vendedor, usando o sistema, cria o pedido pelo site (plataforma de e-commerce VTEX). A partir daí, existem duas possibilidades de fulfillment:

Identificadores do canal omni

Identificamos os pedidos omni pela combinação de três campos em movimentacao:

Estrutura da query (4 CTEs)

Retorno da API

// Um elemento do array "omni"
{
  "id_cliente":      456,
  "cod_vendedor":    "V007",
  "cnpj_emp":        "12345678000190",
  "data_documento":  "2026-05-20 16:45:00",        // Data da venda vinculada, sem conversão ISO no método atual
  "id_pessoa":       88,                             // ID do vendedor em pessoa
  "identificador":   3001,                           // ID da movimentação de venda vinculada
  "transacao":       3001,
  "usuario":         42,
  "documento":       "ORÇ-00321",
  "vendedor":        "João Silva",                   // Nome completo do vendedor
  "cancelado":       "N",
  "itens": [
    {
      "cod_produto":        "PROD-099",
      "descricao_produto":  "Tênis Running 42",
      "cod_barra":          "7896543219870",
      "quantidade":         1,
      "preco_unitario":     349.90,
      "valor_total":        349.90
    }
  ]
}

Canal E-commerce

Consulta ao SQL Server (Linx) e mapeamento de colunas para o padrão FullStore.

Coletamos pedidos do e-commerce processados pelo sistema Linx. Esses dados ficam em um SQL Server separado (LX_ZERO_300), em uma view que já consolida faturamento por vendedor. Nosso processo ocorre em dois passos.

Métodos: buscarDadosEcommercePorLoja() → getVendasEcommerce()

Diagrama de sequência — dois passos

Mapeamento de colunas SQL Server → JSON

Retorno da API

// Um elemento do array "vendas_ecommerce"
{
  "documento_cliente": "123.456.789-00",
  "cod_vendedor":      "EC001",
  "cupom_vendedor":    "VEND10OFF",         // Pode ser string vazia
  "codigo_filial":     "000001",
  "data_documento":    "2026-05-22 09:15:00",
  "pedido_site":       "PS-98765",
  "pedido_wms":        "WMS-54321",
  "ticket":            "TKT-11111",
  "documento":         "000005678",
  "serie":             "001",
  "valor":             "259.90",
  "qtde":              "2"
}

Segurança — placeholders dinâmicos

O número de filiais varia por CNPJ. Em vez de concatenar valores na query, geramos placeholders e usamos bindValue() para cada um:

// Geração dos placeholders (PHP 7.3)
$placeholders = [];
foreach ($filiais as $i => $codigo) {
    $key = ':filial' . $i;
    $placeholders[] = $key;
    $stmt->bindValue($key, $codigo);
}
// Resultado na query: IN (:filial0, :filial1, :filial2)
// Nenhum valor externo é interpolado na string SQL.

API — Parâmetros e Resposta

Especificação completa de getVendas: entrada, saída, erros e exemplos JSON.

Identificação do serviço

Token: <TOKEN_FULLSTORE>
Método HTTP: POST | Formato: JSON

BaseUrl: HTTPS://SEUSISTEMA.PDV.MODA/bibliotecas/ba4e7bb5-4770-4780-beaa-b28980153cc7/wosk/webservice/fullStoreService

Payload de entrada

{
    "acao": "getVendas",
    "key":" CHAVE API FORNECIDA",
    "parametros": {
        "dataInicio": "2026-03-10",
        "dataFim": "2026-03-10",
        "cnpjLoja": ""
    }
}

Resposta de sucesso (com dados)

{
  "success": true,
  "message": "Vendas retornadas com sucesso!",
  "data": {
    "vendas": [
      {
        "codigo_cliente": 123, "cod_vendedor": "V001",
        "cnpj_emp": "12345678000190",
        "data_documento": "2026-05-15T10:30:00-03:00",
        "identificador": 9001, "transacao": 9001, "usuario": 42,
        "documento": "000001234", "serie": "001",
        "operacao": "S", "tipo_transacao": "VENDA",
        "cancelado": "N", "delivery": false,
        "itens": [
          { "cod_produto": "PROD-001", "descricao_produto": "Camiseta Branca M",
            "cod_barra": "7891234567890", "quantidade": 2,
            "preco_unitario": 89.90, "valor_total": 179.80 }
        ]
      }
    ],
    "trocas": [
      {
        "motivo": "Defeito", "doc_venda": "000001234", "serie_venda": "001",
        "cod_cliente": 123, "cnpj_emp": "12345678000190",
        "valor_vale": 89.90, "valor_original": 179.80,
        "timestamp": "2026-05-18T14:22:00-03:00",
        "cod_vendedor": "V001", "quantidade": 1
      }
    ],
    "omni": [
      {
        "id_cliente": 456, "cod_vendedor": "V007",
        "cnpj_emp": "12345678000190",
        "data_documento": "2026-05-20 16:45:00",
        "id_pessoa": 88, "identificador": 3001, "transacao": 3001, "usuario": 42,
        "documento": "ORÇ-00321", "vendedor": "João Silva", "cancelado": "N",
        "itens": [
          { "cod_produto": "PROD-099", "descricao_produto": "Tênis Running 42",
            "cod_barra": "7896543219870", "quantidade": 1,
            "preco_unitario": 349.90, "valor_total": 349.90 }
        ]
      }
    ],
    "vendas_ecommerce": [
      {
        "documento_cliente": "123.456.789-00", "cod_vendedor": "EC001",
        "cupom_vendedor": "VEND10OFF", "codigo_filial": "000001",
        "data_documento": "2026-05-22 09:15:00",
        "pedido_site": "PS-98765", "pedido_wms": "WMS-54321",
        "ticket": "TKT-11111", "documento": "000005678",
        "serie": "001", "valor": "259.90", "qtde": "2"
      }
    ],
    "fallback": null
  }
}

Resposta — período excede o limite

{
  "success": false,
  "message": "Nenhum registro encontrado no periodo 2025-01-01 - 2025-06-30 para o cnpj 12345678000190",
  "data": null
}

Respostas de erro

Parâmetro obrigatório ausente

{ "success": false, "message": "O parametro dataInicio é obrigatorio", "data": null }

Ação inválida

{ "success": false, "message": "Acao nao encontrada", "data": null }

Nenhum dado no período

{
  "success": false,
  "message": "Nenhum registro encontrado no periodo 2026-05-01 - 2026-05-31 para o cnpj 12345678000190",
  "data": null
}

Formato de datas

O formato de data varia por canal na implementação atual. PDV e Trocas convertem datas com date('c', strtotime($valor)). Omni e E-commerce retornam a data no formato vindo da consulta, sem conversão explícita para ISO 8601:

// PDV / Trocas
"data_documento": "2026-05-15T10:30:00-03:00"

// Omni / E-commerce
"data_documento": "2026-05-20 16:45:00"

Configuração e Dependências

Requires em controle.php

Carregamos três dependências via require_once(APPPATH . '...'):

require_once(APPPATH . 'controllers/bibliotecas/4cb18a6c-9c9a-4201-82e6-4f6cc3bea445/wosk_webservice.php');
require_once(APPPATH . 'controllers/bibliotecas/592ccfa0-2692-44e3-aaea-cc7c6c6cfcfa/utilOsk.php');
require_once(APPPATH . 'controllers/bibliotecas/0670acec-4aca-43a0-8943-659600407283/db_sqlserver.php');

Conexão MySQL

Em utilOsk, chamamos getConfiguracao('db_osk_prod') — as credenciais ficam em Base64 numa tabela de configuração do sistema. O método _setConexao() cria a conexão PDO:

// PHP 7.3 — connection string
"mysql:host={$host};port={$porta};dbname={$banco};charset=utf8"

PDO::ATTR_PERSISTENT     = true   // conexão persistente
PDO::ATTR_TIMEOUT        = 120    // timeout em segundos
PDO::ATTR_EMULATE_PREPARES = true

Conexão SQL Server

// PHP 7.3
$sqlserver = new \db_sqlserver(false, 'LX_ZERO_300', true);
// Parâmetros: ($homologacao = false, $banco, $conectar_agora = true)
// connection string: "sqlsrv:Server=<HOST_SQLSERVER>,<PORTA>;Database=LX_ZERO_300"

Variáveis de ambiente

Logs de requisição

O trait WOSK\Commons\WebService salva automaticamente toda chamada no banco integrador ({base_db}_integrador):

Troubleshooting e Testes

Problemas comuns, checklist de diagnóstico e como testar o endpoint manualmente.

Problemas comuns

1. vendas_ecommerce sempre retorna vazio

2. Erro de nenhum registro por período além do limite

O período informado ultrapassa 200 dias no passado. A implementação atual monta um fallback internamente, mas a resposta final retorna success:false com mensagem de nenhum registro encontrado. Com a data de hoje 2026-06-09, o limite de calendário recua até 2025-11-21; por causa da comparação com horário atual, use 2025-11-22 como primeira data segura para evitar a borda.

// dataInicio: "2025-01-01" → excede → retorna success:false
// dataInicio: "2025-11-22" → dentro do limite com margem de segurança

3. Erro success: false — campo faltante

Verificar se o payload contém os três campos dentro de parametros: dataInicio, dataFim e cnpjLoja. Valores null ou string vazia também disparam a validação.

4. Trocas não aparecem mesmo com devoluções registradas

Checklist de diagnóstico

Como testar o endpoint

Via cURL

curl -X POST https://SEU_SERVIDOR/bibliotecas/<TOKEN_FULLSTORE> \
  -H "Content-Type: application/json" \
  -d '{
    "acao": "getVendas",
    "parametros": {
      "dataInicio": "2026-05-01",
      "dataFim":    "2026-05-31",
      "cnpjLoja":   "12345678000190"
    }
  }'

Forçar erro (ambiente de testes)

{
  "acao":   "getVendas",
  "falha":  "teste",
  "parametros": {
    "dataInicio": "2026-05-01",
    "dataFim":    "2026-05-31",
    "cnpjLoja":   "12345678000190"
  }
}

Interpretando a resposta