Ir para o conteúdo principal

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

{{VENDAS}}

{{VENDEDORES}}

{{CANCELAMENTOS}}

{{CANCELAMENTO_PRAZO}}

{{FECHAMENTO_CAIXA}}

    {{TRATAMENTO_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

    Diagrama 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.
    Nenhum comentário
    Voltar ao topo