PRINCIPAL

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. 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.

Objeto raiz do payload
Campo	Tipo
`key`	string
`VENDAS`	array
`VENDEDORES`	array
`CANCELAMENTOS`	array
`CANCELAMENTO_PRAZO`	array
`FECHAMENTO_CAIXA`	array
`eventId`	string

Cada elemento de `VENDAS[]`
Campo	Tipo
`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: todos os campos do objeto em VENDAS[0] aparecem na mesma ordem típica da integração. O campo XML contém, em produção, o documento XML completo (estrutura na tabela de blocos acima). Valores pessoais, fiscais e de transação foram substituídos por dados fictícios ou mascarados. Na mesma requisição podem ser enviados também VENDEDORES, CANCELAMENTOS, CANCELAMENTO_PRAZO e FECHAMENTO_CAIXA conforme tabelas desta seção.

{
  "key": "00000000-0000-4000-8000-000000000001",
  "VENDAS": [
    {
      "CO": "352-00000000000-00",
      "XML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc versao=\"4.00\" xmlns=\"http://www.portalfiscal.inf.br/nfe\"><!-- XML completo da NFC-e autorizada: NFe, infNFe (ide, emit, dest, det, total, transp, pag, infAdic), infNFeSupl, Signature, protNFe --></nfeProc>",
      "DATA": "2025-10-04 16:14:24",
      "MOBILE": "0",
      "TICKET": "",
      "DESCONTO": "0",
      "NF_CHAVE": "29251000000000000000000000000000000000",
      "NF_SERIE": 65,
      "PRODUTOS": [
        {
          "ITEM": 1,
          "QTDE": 1,
          "CUSTO": 41.18,
          "VENDA": 247,
          "CODIGO_EAN": "",
          "QTDE_BRINDE": 0,
          "VALOR_TOTAL": 247,
          "CODIGO_BARRA": "0000000000X",
          "DESCONTO_ITEM": 0,
          "PRECO_LIQUIDO": 247,
          "ID_EXCECAO_IMPOSTO": "11422",
          "RATEIO_DESCONTO_VENDA": 0
        }
      ],
      "TERMINAL": 1,
      "VENDEDOR": "B000",
      "NF_MODELO": 65,
      "NF_NUMERO": 66664,
      "UF_FILIAL": "BA",
      "XML_TROCA": "",
      "COD_FILIAL": "000000",
      "DATA_TROCA": "",
      "PAGAMENTOS": [
        {
          "ITEM": 1,
          "TXID": "",
          "TROCO": 0,
          "VALOR": 247,
          "PARCELAS": 1,
          "TIPO_PGTO": "I",
          "ENDTOENDID": "",
          "VENCIMENTO": "2025-11-03 16:14:24",
          "DATA_HORA_TEF": "2025-10-04 16:13:49",
          "NUMERO_TITULO": "000000000",
          "COD_FORMA_PGTO": "##",
          "REDE_CONTROLADORA": "REDC",
          "CODIGO_ADMINISTRADORA": "25",
          "NUMERO_APROVACAO_CARTAO": "000000000"
        }
      ],
      "QTDE_TOTAL": 1,
      "UF_CLIENTE": "BA",
      "VALOR_PAGO": 247,
      "VALOR_FRETE": 0,
      "VALOR_TROCA": 0,
      "DATA_VITRINE": "",
      "VALOR_VITRINE": 0,
      "CODIGO_CLIENTE": "***000000**",
      "NF_CHAVE_TROCA": "",
      "NF_SERIE_TROCA": "000",
      "OPERACAO_VENDA": "01",
      "PRODUTOS_TROCA": [],
      "NF_MODELO_TROCA": "",
      "NF_NUMERO_TROCA": "",
      "UF_FILIAL_TROCA": "BA",
      "CODIGO_TAB_PRECO": "00",
      "LANCAMENTO_CAIXA": "",
      "PRODUTOS_VITRINE": [],
      "QTDE_TROCA_TOTAL": 0,
      "UF_CLIENTE_TROCA": "BA",
      "ID_PEDIDO_VITRINE": "",
      "VALOR_VENDA_BRUTA": "247",
      "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": "00000000-0000-4000-8000-000000000002"
}

Processamento de Dados

Fonte

Todas as operações usam conexão SQL Server via PDO. Inserções e atualizações são montadas por sqlPrepareInsert e sqlPrepareUpdate 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.fn_GetNextPaymentSequence('<codigoFilial>', '<terminal>', '<data>') AS LANCAMENTO_CAIXA

Origem consultada: função dbo.fn_GetNextPaymentSequence. Uso no código: sqlGetLancamentoCaixa.

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: getCestNCM.

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: getCaixaLancamento.

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: sqlGetNsuVitrine.

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: sqlGetTicket.

Consultas de leitura montadas dinamicamente por sqlSimpleQuery (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

Operações com Dados

Leitura: consultas às tabelas e à view listadas na secção Fonte para validar 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 fn_GetNextPaymentSequence 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.