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.

LojaVenda (Principal)

LojaVendaCabecalhoCupom (Subprocesso)

LojaVendaCancelamentoForaPrazo (Subprocesso)

LojaVendaCancelamentoVenda (Subprocesso)

LojaVendaCestNcm (Subprocesso)

LojaVendaConsultaLancamentoCaixa (Subprocesso)

LojaVendaControleTicketPdv (Subprocesso)

LojaVendaCtbIxImpostoTipo (Subprocesso)

LojaVendaExcecaoImpostoItem (Subprocesso)

LojaVendaIndicadorCfop (Subprocesso)

LojaVendaItemPedidoVitrine (Subprocesso)

LojaVendaItemProduto (Subprocesso)

LojaVendaItemTroca (Subprocesso)

LojaVendaOrigemTroca (Subprocesso)

LojaVendaPagamentoCupom (Subprocesso)

LojaVendaParcelasPagamento (Subprocesso)

LojaVendaPedidoVitrine (Subprocesso)

LojaVendaPrecoDemarcado (Subprocesso)

LojaVendaRegistroLancamentoCaixa (Subprocesso)

LojaVendaValidacaoProdutos (Subprocesso)

LojaVendaVendedoresComissao (Subprocesso)