LojaVenda

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX (Venda PDV)
Biblioteca	wosk_loja_venda
Data	27/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
26/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo Loja Venda (LINX).

Descrição

Este serviço de venda do PDV é exposto como endpoint e recebe, por requisição HTTP, estruturas aninhadas (venda, pagamentos, produtos, troca, vitrine, vendedores, cancelamentos, cancelamento fora do prazo e fechamento de caixa, entre outros blocos opcionais). O processamento valida o corpo, aplica regras de negócio e persiste no banco LINX em tabelas como LOJA_VENDA, LOJA_VENDA_PGTO, LOJA_CAIXA_LANCAMENTOS, ILLIMITAR_PDV_CONTROLE_VENDA e demais entidades tratadas pelos métodos internos.

Endpoint (API)

O método principal valida o payload raiz e processa blocos opcionais: VENDAS (com validação de produtos quando informados, comissão de vendedor, lançamento de caixa, controle de ticket, pagamentos e parcelas, venda, vendedores e produtos da venda), VENDEDORES, CANCELAMENTOS, CANCELAMENTO_PRAZO e FECHAMENTO_CAIXA, cada um com try/catch próprio e retorno de Mensagem/Mensagem Detalhada no sub-objeto.

Chamada: Requisição HTTP

Recurso: /bibliotecas/2cd82f28-3bbf-4f82-bbd8-383f7a912b4f/wosk_loja_venda

Método HTTP: POST

Estruturação de Dados

A tabela a seguir descreve o objeto raiz do corpo JSON enviado ao endpoint. Os blocos opcionais VENDEDORES, CANCELAMENTOS, CANCELAMENTO_PRAZO e FECHAMENTO_CAIXA são processados quando o primeiro elemento do array estiver presente, cada um com tratamento de retorno próprio no fluxo de processamento do serviço.

Parâmetros de entrada do endpoint (objeto raiz)
Campo	Tipo
`key`	string
`VENDAS`	array
`VENDEDORES`	array
`CANCELAMENTOS`	array
`CANCELAMENTO_PRAZO`	array
`FECHAMENTO_CAIXA`	array
`eventId`	string

Cada elemento de `VENDAS[]`
Campo	Tipo
`OBS`	string
`CO`	string
`XML`	string
`DATA`	string
`MOBILE`	string
`TICKET`	string
`DESCONTO`	string
`NF_CHAVE`	string
`NF_SERIE`	number
`PRODUTOS`	array
`TERMINAL`	number
`VENDEDOR`	string
`NF_MODELO`	number
`NF_NUMERO`	number
`UF_FILIAL`	string
`XML_TROCA`	string
`COD_FILIAL`	string
`DATA_TROCA`	string
`PAGAMENTOS`	array
`QTDE_TOTAL`	number
`UF_CLIENTE`	string
`VALOR_PAGO`	number
`VALOR_FRETE`	number
`VALOR_TROCA`	number
`DATA_VITRINE`	string
`VALOR_VITRINE`	number
`CODIGO_CLIENTE`	string
`NF_CHAVE_TROCA`	string
`NF_SERIE_TROCA`	string
`OPERACAO_VENDA`	string
`PRODUTOS_TROCA`	array
`NF_MODELO_TROCA`	string
`NF_NUMERO_TROCA`	string
`UF_FILIAL_TROCA`	string
`CODIGO_TAB_PRECO`	string
`LANCAMENTO_CAIXA`	string
`PRODUTOS_VITRINE`	array
`QTDE_TROCA_TOTAL`	number
`UF_CLIENTE_TROCA`	string
`ID_PEDIDO_VITRINE`	string
`VALOR_VENDA_BRUTA`	string
`ID_EXCECAO_IMPOSTO`	string
`QTDE_VITRINE_TOTAL`	number
`CODIGO_CLIENTE_TROCA`	string
`NUMERO_TITULO_VITRINE`	string
`CODIGO_TAB_PRECO_TROCA`	string
`VALOR_DESCONTO_VITRINE`	number
`CODIGO_TAB_PRECO_VITRINE`	string
`ID_EXCECAO_IMPOSTO_TROCA`	string
`NATUREZA_OPERACAO_CODIGO`	string
`NATUREZA_OPERACAO_CODIGO_TROCA`	string

O valor de VENDAS[].XML é uma única string com o XML integral. Na NFC-e em layout 4.00, a hierarquia típica inclui os blocos abaixo (nomes de elemento conforme schema da NF-e; quantidade de det e autXML varia por nota).

Cada elemento de `VENDAS[].PRODUTOS[]`
Campo	Tipo
`ITEM`	number
`QTDE`	number
`CUSTO`	number
`VENDA`	number
`CODIGO_EAN`	string
`QTDE_BRINDE`	number
`VALOR_TOTAL`	number
`CODIGO_BARRA`	string
`DESCONTO_ITEM`	number
`PRECO_LIQUIDO`	number
`ID_EXCECAO_IMPOSTO`	string
`RATEIO_DESCONTO_VENDA`	number
`INSUMO`	string

Cada elemento de `VENDAS[].PAGAMENTOS[]`
Campo	Tipo
`ITEM`	number
`TXID`	string
`TROCO`	number
`VALOR`	number
`PARCELAS`	number
`TIPO_PGTO`	string
`ENDTOENDID`	string
`VENCIMENTO`	string
`DATA_HORA_TEF`	string
`NUMERO_TITULO`	string
`COD_FORMA_PGTO`	string
`REDE_CONTROLADORA`	string
`CODIGO_ADMINISTRADORA`	string
`NUMERO_APROVACAO_CARTAO`	string

Cada elemento de `VENDEDORES[]` (alteração de vendedor)
Campo	Tipo
`CO`	string
`COD_FILIAL`	string
`TERMINAL`	number
`DATA`	string
`VENDEDOR`	string
`CODIGO_CLIENTE`	string
`ACESSO_GERENCIAL`	number

Cada elemento de `CANCELAMENTOS[]`
Campo	Tipo
`CO`	string
`COD_FILIAL`	string
`TERMINAL`	number
`DATA`	string
`DATA_CANCELAMENTO`	string

Cada elemento de `CANCELAMENTO_PRAZO[]`
Campo	Tipo
`CO`	string
`COD_FILIAL`	string
`TERMINAL`	number
`DATA`	string
`NF_NUMERO`	number
`NF_SERIE`	number
`TICKET`	string
`LANCAMENTO_CAIXA`	string
`DATA_DEVOLUCAO`	string
`CODIGO_CLIENTE`	string
`CODIGO_TAB_PRECO`	string
`VENDEDOR`	string
`NF_MODELO`	number
`NF_CHAVE`	string
`XML`	string
`NATUREZA_OPERACAO_CODIGO`	string
`ID_EXCECAO_IMPOSTO`	string
`UF_FILIAL`	string
`UF_CLIENTE`	string
`PRODUTOS`	array

Cada elemento de `FECHAMENTO_CAIXA[]`
Campo	Tipo
`DATA`	string
`TERMINAL`	number
`LANCAMENTO_CAIXA`	string
`COD_FILIAL`	string

Exemplo de payload enviado para o endpoint (JSON):

Exemplo alinhado a um envio real de venda com NFC-e: o objeto em VENDAS[0] segue a ordem típica da integração. O campo XML contém o documento completo em produção; abaixo o trecho foi resumido para leitura. Na mesma requisição podem ser enviados também VENDEDORES, CANCELAMENTOS, CANCELAMENTO_PRAZO e FECHAMENTO_CAIXA conforme tabelas desta seção.

{
  "key": "df9b5d7f-da04-42f1-80b2-6b6bbbc39152",
  "VENDAS": [
    {
      "CO": "047-26089089577-04",
      "OBS": "osklenbroscarfreire: SLR-1621301265515-01",
      "XML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc versao=\"4.00\" xmlns=\"http://www.portalfiscal.inf.br/nfe\"><NFe>...</NFe><protNFe>...</protNFe></nfeProc>",
      "DATA": "2026-03-30 15:45:13",
      "MOBILE": "0",
      "TICKET": "",
      "DESCONTO": "0",
      "NF_CHAVE": "33260335943604005387650650000551231518627671",
      "NF_SERIE": 65,
      "PRODUTOS": [
        {
          "ITEM": 1,
          "QTDE": 1,
          "CUSTO": 58.37,
          "VENDA": 447,
          "CODIGO_EAN": "7909801470247",
          "QTDE_BRINDE": 0,
          "VALOR_TOTAL": 447,
          "CODIGO_BARRA": "7627910P",
          "DESCONTO_ITEM": 0,
          "PRECO_LIQUIDO": 447,
          "ID_EXCECAO_IMPOSTO": "16296",
          "RATEIO_DESCONTO_VENDA": 0
        }
      ],
      "TERMINAL": 3,
      "VENDEDOR": "P081",
      "NF_MODELO": 65,
      "NF_NUMERO": 55123,
      "UF_FILIAL": "RJ",
      "XML_TROCA": "",
      "COD_FILIAL": "000299",
      "DATA_TROCA": "",
      "PAGAMENTOS": [
        {
          "ITEM": 1,
          "TXID": "",
          "TROCO": 0,
          "VALOR": 447,
          "PARCELAS": 1,
          "TIPO_PGTO": "I",
          "ENDTOENDID": "",
          "VENCIMENTO": "2026-04-29 15:45:13",
          "DATA_HORA_TEF": "2026-03-30 15:45:10",
          "NUMERO_TITULO": "508673340",
          "COD_FORMA_PGTO": "##",
          "REDE_CONTROLADORA": "REDC",
          "CODIGO_ADMINISTRADORA": "24",
          "NUMERO_APROVACAO_CARTAO": "508673340"
        }
      ],
      "QTDE_TOTAL": 1,
      "UF_CLIENTE": "RJ",
      "VALOR_PAGO": 447,
      "VALOR_FRETE": 0,
      "VALOR_TROCA": 0,
      "DATA_VITRINE": "",
      "VALOR_VITRINE": 0,
      "CODIGO_CLIENTE": "",
      "NF_CHAVE_TROCA": "",
      "NF_SERIE_TROCA": "",
      "OPERACAO_VENDA": "01",
      "PRODUTOS_TROCA": [],
      "NF_MODELO_TROCA": "",
      "NF_NUMERO_TROCA": "",
      "UF_FILIAL_TROCA": "RJ",
      "CODIGO_TAB_PRECO": "00",
      "LANCAMENTO_CAIXA": "",
      "PRODUTOS_VITRINE": [],
      "QTDE_TROCA_TOTAL": 0,
      "UF_CLIENTE_TROCA": "RJ",
      "ID_PEDIDO_VITRINE": "",
      "VALOR_VENDA_BRUTA": "447",
      "ID_EXCECAO_IMPOSTO": "",
      "QTDE_VITRINE_TOTAL": 0,
      "CODIGO_CLIENTE_TROCA": "",
      "NUMERO_TITULO_VITRINE": "",
      "CODIGO_TAB_PRECO_TROCA": "00",
      "VALOR_DESCONTO_VITRINE": 0,
      "CODIGO_TAB_PRECO_VITRINE": "00",
      "ID_EXCECAO_IMPOSTO_TROCA": "",
      "NATUREZA_OPERACAO_CODIGO": "5102.",
      "NATUREZA_OPERACAO_CODIGO_TROCA": ""
    }
  ],
  "eventId": "f243a126-27e2-437b-87c0-b239c35ff892"
}

Operações com Dados (endpoint)

Fluxo principal quando VENDAS[0] está presente:

Validação: valida os dados do payload raiz; quando há PRODUTOS, PRODUTOS_TROCA ou PRODUTOS_VITRINE, chama-se valida os produtos (resolução em PRODUTOS_BARRA e preços).

Vendedor: consulta LOJA_VENDEDORES para obter comissão e valida os dados situação do vendedor.

Caixa e terminal: registra lançamento no caixa (sequência de lançamento, contexto em LOJA_CAIXA_LANCAMENTOS).

Datas de venda: a partir de DATA preenchem-se DATA_DIGITACAO e DATA_VENDA usadas nas gravações.

Controle Illimitar: atualiza controle de venda no PDV Illimitar (ticket e vínculo com terminal/filial).

Pagamentos: registra pagamentos da venda; para cada linha de PAGAMENTOS, registra parcelas da venda (parcelas e administradora).

Cabeçalho e vendedores da venda: registra venda da loja e registra vendedores da venda.

Itens: para cada produto validado, registra itens da venda; para troca e vitrine, registra troca da venda, registra origem da troca da venda, registra pedido do Vitrine Unico e registra itens do pedido do Vitrine Unico quando aplicável.

Demais blocos opcionais do corpo, quando o primeiro elemento do array existir, seguem fluxo próprio com try/catch: VENDEDORES (atualização de vendedor na venda), CANCELAMENTOS, CANCELAMENTO_PRAZO e FECHAMENTO_CAIXA, cada qual persistindo conforme métodos internos do serviço.

Tratamento de Dados

Modificações explícitas aplicadas aos dados de entrada no processamento de VENDAS[0] (entre outras):

TERMINAL: normalizado com preenchimento à esquerda até 3 posições antes das rotinas de caixa.

COMISSAO: inicializada em zero e, quando há vendedor encontrado, preenchida a partir do cadastro em LOJA_VENDEDORES com normalização numérica.

valida os produtos: CODIGO_TAB_PRECO (e tabelas de troca/vitrine quando existirem) com preenchimento à esquerda até 2 caracteres; itens mesclados com PRODUTO, COR_PRODUTO, GRADE, TAMANHO de PRODUTOS_BARRA e DEMARCADO via busca preço demarcado.

Forma de pagamento consolidada: COD_FORMA_PGTO passa a ser a do primeiro pagamento; se houver mais de um pagamento, fixa-se ##. Se não houver linhas em PAGAMENTOS, ajusta-se VALOR_PAGO em relação a VALOR_TROCA, define-se forma 01 e monta-se um array sintético de pagamento único.

Produtos da venda: em cada item, VENDEDOR do produto recebe o vendedor da venda ou, se vazio, GERENTE_LOJA; replicam-se TICKET, CODIGO_FILIAL e DATA_VENDA do cabeçalho.

Vitrine: quando há PRODUTOS_VITRINE, DATA_VENDA do item deriva de DATA_VITRINE e demais campos de pedido conforme registra pedido do Vitrine Unico.

Fonte

Todas as operações usam conexão SQL Server via PDO. Inserções e atualizações são montadas por prepara inserção de dados e prepara atualização de dados na cadeia de classes base (trait Common / util).

Consulta utilizada para obter o próximo lançamento de caixa (@data no formato AAAA-MM-DD 00:00:00):

SELECT dbo.busca a próxima sequência de pagamento('<codigoFilial>', '<terminal>', '<data>') AS LANCAMENTO_CAIXA

Origem consultada: função dbo.busca a próxima sequência de pagamento. Uso no código: consulta o lançamento de caixa.

Consulta utilizada para resolver o identificador da relação CEST/NCM (resultado pode ser cacheado em $_ENV['_CEST_NCM']):

SELECT
    A.ID AS IDA
FROM
    CEST_NCM A
    INNER JOIN TABELA_LX_NCM B ON (B.ID = A.ID_NCM)
    INNER JOIN TABELA_LX_CEST C ON (C.ID = A.ID_CEST)
WHERE
    C.CODIGO_CEST = '<CEST>'
    AND B.CODIGO_NCM = '<NCM>'

Origem consultada: tabelas CEST_NCM, TABELA_LX_NCM e TABELA_LX_CEST. Uso no código: busca CEST/NCM.

Consulta utilizada para obter os três últimos lançamentos de caixa do terminal e filial (WHERE com data completa e, quando aplicável, meia-noite do dia derivado de <DATA>):

SELECT TOP 3
    *
FROM
    LOJA_CAIXA_LANCAMENTOS
WHERE
    TERMINAL = '<TERMINAL>'
    AND CODIGO_FILIAL = '<CODIGO_FILIAL>'
    AND TIPO_LANCAMENTO_CAIXA IN ('00', 'RT')
    AND (
        DIGITACAO <= '<DATA>'
        OR DIGITACAO = '<DATA_MEIA_NOITE>'
    )
ORDER BY
    DIGITACAO DESC

Origem consultada: tabela LOJA_CAIXA_LANCAMENTOS. Uso no código: busca lançamento de caixa.

Consulta utilizada para montar parte do NSU do pedido vitrine (<codigo> é o identificador numérico do pedido; o valor final concatenado no PHP inclui a data em formato Ymd):

SELECT
    'I'
    + RIGHT('0' + RTRIM(CONVERT(CHAR(2), DATEPART(MONTH, '<data>'))), 2)
    + RIGHT('000000' + CONVERT(VARCHAR(8), <codigo>), 5) AS NSU

Origem consultada: expressão escalar em T-SQL, sem objeto de tabela no FROM. Uso no código: consulta o NSU da vitrine.

Consulta utilizada para calcular o próximo TICKET da filial; se não houver sequência e existir registro em ILLIMITAR_PDV_CONTROLE_VENDA para a filial, o fluxo lança exceção; caso contrário usa 00000001:

SELECT
    RIGHT(REPLICATE('0', 8) + CONVERT(VARCHAR(8), CONVERT(INT, MAX(TICKET)) + 1), 8) AS SEQ
FROM
    ILLIMITAR_PDV_CONTROLE_VENDA
WHERE
    CODIGO_FILIAL = '<CODIGO_FILIAL>'

Origem consultada: tabela ILLIMITAR_PDV_CONTROLE_VENDA. Uso no código: consulta o ticket.

Consultas de leitura montadas dinamicamente por executa uma consulta simples (lista de colunas, tabela, WHERE a partir de pares campo/valor, ORDER BY e TOP opcionais):

SELECT TOP <n>
    <col1>,
    <col2>,
    ...
FROM
    [dbo].[NOME_TABELA] (NOLOCK)
WHERE
    <coluna> = '<valor>'
    AND ...
ORDER BY
    <coluna> ASC|DESC

Persistência e leituras auxiliares

Leitura: consultas às tabelas e à view listadas na secção Fonte para valida os dados produto e preço, resolver CEST/NCM e regras fiscais auxiliares, carregar filial, loja varejo e terminal, obter ou confirmar lançamento de caixa, controle Illimitar e cabeçalhos/itens de venda existentes antes de inserir ou atualizar.

Sequências e apoio de caixa: uso da função busca a próxima sequência de pagamento para LANCAMENTO_CAIXA, da consulta TOP 3 em LOJA_CAIXA_LANCAMENTOS para contexto de caixa, do cálculo de NSU para vitrine e da sequência de TICKET em ILLIMITAR_PDV_CONTROLE_VENDA.

Persistência: gravação e atualização nas tabelas LINX do PDV (entre outras LOJA_VENDA, LOJA_VENDA_PGTO, LOJA_VENDA_PARCELAS, LOJA_VENDA_VENDEDORES, LOJA_VENDA_PRODUTO, LOJA_VENDA_TROCA, LOJA_VENDA_TROCA_ORIGEM, LOJA_CAIXA_LANCAMENTOS, ILLIMITAR_PDV_CONTROLE_VENDA) conforme cada bloco do payload processado pelo serviço.

Tratamento de retorno

Cada bloco opcional, quando o primeiro elemento do respectivo array estiver presente, atualiza o elemento processado com Mensagem OK ou ERROR e Mensagem Detalhada; o objeto raiz recebe os campos Mensagem e Mensagem Detalhada do último bloco executado; o retorno é registrado em auditoria antes de devolver o array.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Endpoint (API)	Venda completa	Com `VENDAS[0]` válido, o fluxo monta lançamento de caixa, controle de ticket, pagamentos e parcelas, cabeçalho da venda, vendedores e itens (e troca/vitrine quando informados), interpreta sucesso ou falha com mensagem e retorna `Mensagem` e `Mensagem Detalhada` no objeto.	`Mensagem` `OK` ou `ERROR` com detalhe em `Mensagem Detalhada`.
Endpoint (API)	Alteração de vendedor	Com `VENDEDORES[0]` e `CO` informado, localiza a venda e aplica alteração de vendedor com comissão coerente.	`Mensagem` `OK` ou `ERROR` com detalhe em `Mensagem Detalhada`.
Endpoint (API)	Cancelamento	Com `CANCELAMENTOS[0]` e `CO` informado, executa cancelamento em cascata nas entidades de venda.	`Mensagem` `OK` ou `ERROR` com detalhe em `Mensagem Detalhada`.
Endpoint (API)	Cancelamento fora do prazo	Com `CANCELAMENTO_PRAZO[0]`, atualiza dados fiscais de cancelamento quando a venda for localizada; valida produtos quando o array `PRODUTOS` vier preenchido.	`Mensagem` `OK` ou `ERROR` com detalhe em `Mensagem Detalhada`.
Endpoint (API)	Fechamento de caixa	Com `FECHAMENTO_CAIXA[0]` contendo `DATA`, `TERMINAL`, `COD_FILIAL` e `LANCAMENTO_CAIXA` (conforme integração), registra fechamento quando a abertura do dia existir; caso contrário mensagem informa que o fechamento foi ignorado.	`Mensagem` `OK` com detalhe de sucesso ou de ignorado; ou `ERROR` com exceção.