Ir para o conteúdo principal

CallbackProtheus (STATUS: VARIFICANDO)

Documentação Técnica

Nome do cliente OSKLEN
Nome do projeto Integração LINX → Protheus
Biblioteca wosk_callback_protheus
Data 03/03/2026


Histórico de Versões

Data Versão Modificado por Descrição da Mudança
03/03/2026 1.0 Maykon/Gustavo Criação da documentação técnica do processo CallbackProtheus.

Descrição

Esta biblioteca é utilizada como callback (webhook) para receber as respostas do processamento assíncrono realizado pelo Protheus, tratando o retorno, atualizando o status correspondente e acionando rotinas inteligentes quando aplicável.

Fila de Processamento

Descrição Conceitual

Realiza a realiza a notificão por email de itens que estão a mais de 30 minutos aguardando processamento no Protheus (situação = 'Aguardando Processamento no Protheus'). 

Notificação

A notificação consulta itens com situação 5 (aguardando) na tabela wosk_queue cujo data_adicionado seja anterior a 30 minutos, ordena por data e envia e-mail aos destinatários configurados, com colunas CAPTURADO EM, CHAVE, MENSAGEM e AGUARDANDO DESDE.
SELECT
    `token`,
    `acao`,
    `chave`,
    `data_adicionado`,
    `data`,
    `mensagem`
FROM
    `{BASE_INTEGRADOR}`.`wosk_queue`
WHERE
    `situacao` = 5
    AND `data_adicionado` <= '{DATA_LIMITE}'
ORDER BY
    `data` ASC

Endpoint (API)

O endpoint é utilizado como callback pelo Protheus com o resultado do processamento de itens enviados pelo LINX. Valida os parâmetros obrigatórios, resolve o token via respostaRecebidaCallback (chave FILIAL-ID), localiza o item na wosk_queue, atualiza a situação e aciona rotinas inteligentes.

Estruturação de Dados

Parâmetros de entrada (obrigatórios)

Campo Tipo Descrição
INTEGRADOR string Nome do endpoint responsável pelo registro a ser processado.
FILIAL string Código da Filial no Protheus.
ID string ID de controle de execução gerado pelo Protheus.
DATA_RETORNO datetime Data do processamento do registro no Protheus.
SITUACAO numeric 0=erro, 1=sucesso, 2=aguardar finalização.
MENSAGEM string Observações sobre o processamento.

Parâmetro opcional

DETALHE (array): complemento das informações processadas; quando presente, é gravado em retorno do item na fila.

Valores de saída

O endpoint retorna o mesmo objeto de entrada, acrescido de Mensagem ("OK" ou "ERRO") e Mensagem Detalhada com o resultado ou a mensagem de erro.




Tratamento de Dados

Mapeamento de INTEGRADOR: quando o valor for "cupom", é convertido para ProtheusCupom para resolução do token. Atualização de situacao conforme SITUACAO: 0→4 (erro), 1→2 (sucesso), 2→5 (aguardando). Tratamento especial: quando situacao for 4 e a mensagem contiver "já cadastrado", o item é reclassificado para situação 2 (sucesso).

Tratamento de retorno

Em sucesso, retorna Mensagem = "OK" e Mensagem Detalhada = "Registrado com sucesso.". Em erro, retorna Mensagem = "ERRO" e Mensagem Detalhada com a exceção.

Rotinas Inteligentes

Cupom Ecommerce Integrado: chamada quando o callback indica sucesso ou erro (situação diferente de 5) e o serviço é ProtheusCupomFiscal, ProtheusCupomFiscalEcommerce, ProtheusCupomFiscalOmni ou ProtheusCupomFiscalPontual. Aciona a rotina de cupom ecommerce integrado para a chave do item.
link: Cupom Ecommerce Integrado

Cupom Fiscal Integrado: chamada nas mesmas condições acima. Aciona a rotina de cupom fiscal integrado para a chave do item.
link: Cupom Fiscal Integrado

Documento de Cancelamento de Cupom Fiscal: chamada nas mesmas condições acima. Aciona a rotina de cancelamento de cupom fiscal para a chave do item.
link: Documento de Cancelamento de Cupom Fiscal

Documento de Saida Integrado: chamada quando o serviço é ProtheusCupomFiscalFull e a situação final não é 5. Aciona a rotina de documento de saída integrado, cupom ecommerce integrado, cupom fiscal integrado e documento de cancelamento de cupom fiscal para a chave do item, com parâmetros adicionais para processamento em lote.
link: Documento de Saida Integrado

Fluxo do Processo

Diagrama sem nome.jpg


Critérios de Aceitação

Processo Subprocesso Descrição Situação esperada
Endpoint Recebimento e validação do callback Ao receber um callback com INTEGRADOR, FILIAL, ID, DATA_RETORNO, SITUACAO e MENSAGEM válidos, deve localizar o item na wosk_queue via respostaRecebidaCallback e validar que a situação atual permita atualização (2 ou 4 ou 5). Item localizado e validado; fluxo prossegue para atualização.
Endpoint Atualização de situação Ao processar SITUACAO 0, 1 ou 2, deve mapear para situação 4 (erro), 2 (sucesso) ou 5 (aguardando) respectivamente, aplicar o tratamento especial "já cadastrado" quando aplicável, e persistir na wosk_queue via operação set da fila. Item atualizado com situação final correta e retorno persistido.
Fila de Processamento Notificação de itens aguardando Ao executar notificar(), deve consultar itens com situação 5 e data_adicionado anterior a 30 minutos, ordenar por data e enviar e-mail aos destinatários configurados. E-mail enviado com os itens aguardando há mais de 30 minutos.
Voltar ao topo