Ir para o conteúdo principal

Nova Página // TESTE GUSTAVO

DOCUMENTAÇÃO TÉCNICA
Nome do cliente OSKLEN
Nome do projeto Integração LINX (Venda PDV)
Biblioteca / Método wosk_loja_venda — setLojaVendaParcelas
Data 27/03/2026


HISTÓRICO DE VERSÕES
Data Versão Modificado por Descrição da Mudança
27/03/2026 1.0 Maykon/Gustavo Criação da documentação do método setLojaVendaParcelas alinhada ao modelo de rotina inteligente.


DESCRIÇÃO

Esta função prepara os dados de uma parcela de pagamento, aplica regras de sobrescrita para identificadores de transação e persiste em LOJA_VENDA_PARCELAS quando a chave da parcela ainda não existe para o caixa da venda. O método não executa UPDATE; o fluxo é de criação condicional com validação pós-insert.

Assinatura do método:

public function setLojaVendaParcelas($params)

Retorno: o próprio array $params recebido, sem alteração de estrutura pelo retorno explícito.

Fluxo: transação de banco comentada no código-fonte (não ativa); try/catch envolve montagem de $_params, consulta prévia por chave, INSERT condicional via sqlPrepareInsert, nova leitura de confirmação ou exceção com prefixo LOJA_VENDA_PARCELAS:.


FONTES
  • Origem consultada: LOJA_VENDA_PARCELAS | Tipo: leitura | Uso: verificar existência por CODIGO_FILIAL, TERMINAL, LANCAMENTO_CAIXA e PARCELA.
  • Origem persistida: LOJA_VENDA_PARCELAS | Tipo: insert | Uso: inserir parcela quando não encontrada na consulta de pré-validação.
  • Origem de SQL dinâmico: helper sqlPrepareInsert (classe base) com hydrate hydrateLojaVendaParcelas, permitindo NULL para colunas não preenchidas e GETDATE() em DATA_PARA_TRANSFERENCIA. Opcionalmente inclui LX_METODO_PGTO no hydrate quando informado.

Leitura (sqlSimpleQuery) — template:

SELECT TOP 1
    *
FROM [dbo].[LOJA_VENDA_PARCELAS] (NOLOCK)
WHERE CODIGO_FILIAL = '{CODIGO_FILIAL}'
    AND TERMINAL = '{TERMINAL}'
    AND LANCAMENTO_CAIXA = '{LANCAMENTO_CAIXA}'
    AND PARCELA = '{PARCELA}'

Persistência (sqlPrepareInsert) — hydrate padrão (sem LX_METODO_PGTO dinâmico):

SET NOCOUNT ON;

INSERT INTO [dbo].[LOJA_VENDA_PARCELAS] (
    TERMINAL,
    LANCAMENTO_CAIXA,
    CODIGO_FILIAL,
    PARCELA,
    CODIGO_ADMINISTRADORA,
    TIPO_PGTO,
    VALOR,
    VENCIMENTO,
    NUMERO_TITULO,
    MOEDA,
    NUMERO_APROVACAO_CARTAO,
    PARCELAS_CARTAO,
    VALOR_CANCELADO,
    CHEQUE_CARTAO,
    DATA_PARA_TRANSFERENCIA,
    REDE_CONTROLADORA,
    TROCO,
    DATA_HORA_TEF,
    NSU_CANCELAMENTO
)
VALUES (
    :TERMINAL,
    :LANCAMENTO_CAIXA,
    :CODIGO_FILIAL,
    :PARCELA,
    :CODIGO_ADMINISTRADORA,
    :TIPO_PGTO,
    :VALOR,
    :VENCIMENTO,
    :NUMERO_TITULO,
    :MOEDA,
    :NUMERO_APROVACAO_CARTAO,
    :PARCELAS_CARTAO,
    :VALOR_CANCELADO,
    :CHEQUE_CARTAO,
    GETDATE(),
    :REDE_CONTROLADORA,
    :TROCO,
    :DATA_HORA_TEF,
    NULL
)

Persistência (sqlPrepareInsert) — hydrate com LX_METODO_PGTO (Omni3):

SET NOCOUNT ON;

INSERT INTO [dbo].[LOJA_VENDA_PARCELAS] (
    TERMINAL,
    LANCAMENTO_CAIXA,
    CODIGO_FILIAL,
    PARCELA,
    CODIGO_ADMINISTRADORA,
    TIPO_PGTO,
    VALOR,
    VENCIMENTO,
    NUMERO_TITULO,
    MOEDA,
    NUMERO_APROVACAO_CARTAO,
    PARCELAS_CARTAO,
    VALOR_CANCELADO,
    CHEQUE_CARTAO,
    DATA_PARA_TRANSFERENCIA,
    REDE_CONTROLADORA,
    TROCO,
    DATA_HORA_TEF,
    NSU_CANCELAMENTO,
    LX_METODO_PGTO
)
VALUES (
    :TERMINAL,
    :LANCAMENTO_CAIXA,
    :CODIGO_FILIAL,
    :PARCELA,
    :CODIGO_ADMINISTRADORA,
    :TIPO_PGTO,
    :VALOR,
    :VENCIMENTO,
    :NUMERO_TITULO,
    :MOEDA,
    :NUMERO_APROVACAO_CARTAO,
    :PARCELAS_CARTAO,
    :VALOR_CANCELADO,
    :CHEQUE_CARTAO,
    GETDATE(),
    :REDE_CONTROLADORA,
    :TROCO,
    :DATA_HORA_TEF,
    NULL,
    :LX_METODO_PGTO
)


PARÂMETROS

Parâmetros de entrada da função ($params):
TERMINAL, LANCAMENTO_CAIXA, CODIGO_FILIAL, PARCELA, CODIGO_ADMINISTRADORA, NUMERO_TITULO, TIPO_PGTO, VALOR, VENCIMENTO, NUMERO_APROVACAO_CARTAO, PARCELAS, CHEQUE_CARTAO, REDE_CONTROLADORA, TROCO, DATA_HORA_TEF, TXID, ENDTOENDID, LX_METODO_PGTO.

Campos montados em $_params para persistência:
TERMINAL, LANCAMENTO_CAIXA, CODIGO_FILIAL, PARCELA, CODIGO_ADMINISTRADORA, NUMERO_TITULO, TIPO_PGTO, VALOR, VENCIMENTO, MOEDA, NUMERO_APROVACAO_CARTAO, PARCELAS_CARTAO, VALOR_CANCELADO, CHEQUE_CARTAO, REDE_CONTROLADORA, TROCO, DATA_HORA_TEF, LX_METODO_PGTO (quando aplicável).

Campos usados nas condições de busca/validação:
CODIGO_FILIAL, TERMINAL, LANCAMENTO_CAIXA, PARCELA (valor normalizado em $_params['PARCELA'] na consulta).


TRATAMENTO DE DADOS
  • PARCELA: normalizada com str_pad($params['PARCELA'], 2, '0', STR_PAD_LEFT).
  • VALOR, TROCO: normalizados com getNumeric antes da persistência.
  • MOEDA: fixada em R$.
  • VALOR_CANCELADO: fixado em 0 no insert.
  • CHEQUE_CARTAO: gerado por composição {CODIGO_FILIAL}-{TERMINAL}-{LANCAMENTO_CAIXA}-{PARCELA}; se $params['CHEQUE_CARTAO'] vier preenchido, sobrescreve o valor composto.
  • NUMERO_TITULO, NUMERO_APROVACAO_CARTAO: podem ser sobrescritos por TXID quando informado.
  • NUMERO_APROVACAO_CARTAO: pode ser sobrescrito novamente por ENDTOENDID quando informado.
  • LX_METODO_PGTO: quando preenchido, adiciona dinamicamente a coluna no hydrate ($this->hydrateLojaVendaParcelas[] = 'LX_METODO_PGTO') e entra no insert.
  • Tratamento de criação vs atualização: este método possui apenas criação condicional (INSERT) e não possui bloco de UPDATE.


CONSULTAS SQL

Leituras feitas com sqlSimpleQuery (classe base): colunas ['*'], tabela LOJA_VENDA_PARCELAS, condições CODIGO_FILIAL, TERMINAL, LANCAMENTO_CAIXA e PARCELA (esta última com o valor já normalizado em $_params['PARCELA']), sem ordenação, limite TOP 1.

  • 1) Pré-validação (antes do insert): verifica se já existe linha para a chave. Se $_LOJA_VENDA_PARCELAS[0]['PARCELA'] estiver vazio, o fluxo segue para o sqlPrepareInsert.
  • 2) Confirmação pós-insert: mesma assinatura de chamada da consulta anterior; se após o insert ainda não houver PARCELA no retorno, o método lança exceção com a chave na mensagem.

Templates SQL indentados: o SELECT de leitura e os INSERT gerados pelo hydrate estão na secção FONTES (blocos <pre><code>, mesma formatação do restante do documento).

Observação: os valores de filtro são interpolados na montagem da string SQL conforme a implementação de sqlSimpleQuery na classe base; não são parâmetros nomeados de prepared statement nessa leitura.


DICIONÁRIO DE DADOS E QUERY GERADA
Campo Origem Tratamento aplicado Operação
TERMINAL $params['TERMINAL'] Sem alteração adicional INSERT
LANCAMENTO_CAIXA $params['LANCAMENTO_CAIXA'] Sem alteração adicional INSERT
CODIGO_FILIAL $params['CODIGO_FILIAL'] Sem alteração adicional INSERT
PARCELA $params['PARCELA'] Função str_pad do PHP: preenche à esquerda com '0' até o comprimento 2 (STR_PAD_LEFT), equivalente a str_pad($params['PARCELA'], 2, '0', STR_PAD_LEFT) — ex.: 1 → 01. INSERT
CODIGO_ADMINISTRADORA $params['CODIGO_ADMINISTRADORA'] Condicional por preenchimento INSERT
NUMERO_TITULO $params['NUMERO_TITULO'] / $params['TXID'] Sobrescrita por TXID quando informado INSERT
TIPO_PGTO $params['TIPO_PGTO'] Sem alteração adicional INSERT
VALOR $params['VALOR'] Método getNumeric da classe base: normaliza o valor recebido para formato numérico válido na persistência (tratamento de separadores, máscara monetária, etc., conforme a implementação da biblioteca), antes do bind no insert. INSERT
VENCIMENTO $params['VENCIMENTO'] Sem alteração adicional INSERT
MOEDA Valor fixo R$ INSERT
NUMERO_APROVACAO_CARTAO $params['NUMERO_APROVACAO_CARTAO'] / $params['TXID'] / $params['ENDTOENDID'] Sobrescritas em cascata (TXID e depois ENDTOENDID) INSERT
PARCELAS_CARTAO $params['PARCELAS'] Mapeamento direto INSERT
VALOR_CANCELADO Valor fixo 0 INSERT
CHEQUE_CARTAO Composição do método / $params['CHEQUE_CARTAO'] Composição padrão com sobrescrita opcional INSERT
REDE_CONTROLADORA $params['REDE_CONTROLADORA'] Condicional por preenchimento INSERT
TROCO $params['TROCO'] Mesmo critério de VALOR: getNumeric da classe base para normalizar o valor numérico antes do insert. INSERT
DATA_HORA_TEF $params['DATA_HORA_TEF'] Condicional por preenchimento INSERT
LX_METODO_PGTO $params['LX_METODO_PGTO'] Inclusão dinâmica no hydrate e no payload INSERT
DATA_PARA_TRANSFERENCIA Hydrate GETDATE() INSERT
NSU_CANCELAMENTO Não preenchido no fluxo NULL no insert INSERT

Queries INSERT indentadas: os dois templates (hydrate padrão e variante com LX_METODO_PGTO) estão na secção FONTES.

Critério de criação: o insert ocorre apenas quando a consulta por CODIGO_FILIAL, TERMINAL, LANCAMENTO_CAIXA e PARCELA não retorna registro.


SITUAÇÕES CONSIDERADAS
Valor Significado
Pré-consulta sem PARCELA no primeiro registro Dispara tentativa de INSERT com sqlPrepareInsert; se a linha já existir na prática, a segunda leitura deve encontrá-la e o fluxo não relança insert.
Pós-insert ainda sem PARCELA na leitura Exceção com mensagem contendo CODIGO_FILIAL, TERMINAL, LANCAMENTO_CAIXA e PARCELA e texto NA 'LOJA_VENDA_PARCELAS': NÃO ENCONTRADO.
TXID informado NUMERO_TITULO e NUMERO_APROVACAO_CARTAO recebem o valor de TXID.
ENDTOENDID informado (após eventual TXID) NUMERO_APROVACAO_CARTAO é definido com o valor de ENDTOENDID.
LX_METODO_PGTO informado Hydrate estendido e coluna incluída no INSERT (fluxo Omni3).
Nenhum comentário
Voltar ao topo