ProtheusNotaFiscalMarketplace (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca integra as Notas Fiscais de Marketplace do LINX para o Protheus, garantindo captura por chave ou por data, montagem dos itens e registro do resultado da integração.

Capturador

Descrição Conceitual

Permite a captura manual de uma ou mais Notas Fiscais de Marketplace por chave no padrão F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA, com validação obrigatória do formato; quando a chave estiver fora do padrão, o processo é interrompido com erro de chave inválida para evitar registros inconsistentes.

A captura por data consulta a origem filtrando e ordenando por DATA_PARA_TRANSFERENCIA, com paginação por OFFSET/FETCH, caracterizando processamento cronológico (ordenação/paginação por data); link conceitual: Processamento cronológico. A execução periódica pode ser acionada por agendador de tarefas.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE e view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM.

Consulta utilizada na captura por data (WHERE e paginação construídos dinamicamente conforme posição e limite configurado):

SELECT
    TIPO,
    E1_XFILORI,
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_PEDIDO,
    F2_TIPO,
    F2_FORMUL,
    F2_EMISSAO,
    F2_CLIENTE,
    F2_LOJA,
    F2_ESPECIE,
    F2_COND,
    F2_XNATOPE,
    F2_CHVNFE,
    F2_HAUTNFE,
    F2_DAUTNFE,
    F2_PROTOCOLO,
    F2_FRETE,
    F2_SEGURO,
    F2_DESPESA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '<DATA_PARA_TRANSFERENCIA>'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    <OFFSET> ROWS FETCH NEXT <LIMITE> ROWS ONLY

Consulta utilizada na captura manual (chave informada e WHERE construído dinamicamente):

SELECT
    TIPO,
    E1_XFILORI,
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_PEDIDO,
    F2_TIPO,
    F2_FORMUL,
    F2_EMISSAO,
    F2_CLIENTE,
    F2_LOJA,
    F2_ESPECIE,
    F2_COND,
    F2_XNATOPE,
    F2_CHVNFE,
    F2_HAUTNFE,
    F2_DAUTNFE,
    F2_PROTOCOLO,
    F2_FRETE,
    F2_SEGURO,
    F2_DESPESA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE (NOLOCK)
WHERE
    F2_FILIAL = '<F2_FILIAL>'
    AND F2_DOC = '<F2_DOC>'
    AND F2_SERIE = '<F2_SERIE>'
    AND F2_CLIENTE = '<F2_CLIENTE>'
    AND F2_LOJA = '<F2_LOJA>'

Consulta utilizada para carregar itens da nota (WHERE construído dinamicamente a partir da chave):

SELECT
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_CLIENTE,
    F2_LOJA,
    D2_CCUSTO,
    D2_LOCAL,
    D2_ITEM,
    D2_COD,
    D2_QUANT,
    D2_PRCVEN,
    D2_TOTAL,
    D2_TES,
    D2_BASEICM,
    D2_PICM,
    D2_VALICM,
    D2_DESCON,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM (NOLOCK)
WHERE
    F2_FILIAL = '<F2_FILIAL>'
    AND F2_DOC = '<F2_DOC>'
    AND F2_SERIE = '<F2_SERIE>'
    AND F2_CLIENTE = '<F2_CLIENTE>'
    AND F2_LOJA = '<F2_LOJA>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE para obter o registro atual da Nota Fiscal de Marketplace e construir o identificador de processamento no padrão F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA.

- Carregamento de itens: para cada registro atual da nota, consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM e agrega os itens retornados no campo itens, formando o conjunto completo (cabeçalho + itens) para integração.

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusNotaFiscalMarketplace, aplicado na paginação da consulta (FETCH NEXT <LIMITE>).

- Registro para processamento: cada Nota Fiscal de Marketplace capturada é persistida como pendência na tabela wosk_queue (banco {$this->bancoIntegrador}) sob o serviço ProtheusNotaFiscalMarketplace, com o conteúdo vindo da origem (incluindo itens) para processamento assíncrono.

Fila de Processamento

Descrição Conceitual

A fila recupera um registro pendente e utiliza o conteúdo do registro como base do payload de integração. Em seguida, aplica transformações obrigatórias de padronização e realiza a chamada ao Protheus.

Estruturação de Dados

{
  "TIPO": "",
  "e1_xfilori": "",
  "f2_filial": "",
  "f2_doc": "",
  "f2_serie": "",
  "f2_pedido": "",
  "f2_tipo": "",
  "f2_formul": "",
  "f2_emissao": "",
  "f2_cliente": "",
  "f2_loja": "",
  "f2_especie": "",
  "f2_chvnfe": "",
  "f2_hautnfe": "",
  "f2_dautnfe": "",
  "f2_protocolo": "",
  "f2_cond": "",
  "f2_frete": 0,
  "f2_seguro": 0,
  "f2_despesa": 0,
  "f2_xnatope": "",
  "itens": [
    {
      "d2_item": "",
      "d2_cod": "",
      "d2_quant": 0,
      "d2_prcven": 0,
      "d2_total": 0,
      "d2_tes": "",
      "d2_baseicm": 0,
      "d2_picm": 0,
      "d2_valicm": 0,
      "D2_DESCON": 0
    }
  ]
}

Tratamento de Dados

- Pré-validação de dependência: antes de enviar a Nota Fiscal de Marketplace, valida se o cliente (f2_loja + f2_cliente) já foi integrado. Quando a dependência não estiver integrada, o item é finalizado como suspenso (situacao = 3) e registra suspensaoTipo e suspensaoChave para rastreio do bloqueio.

- Normalização numérica (cabeçalho): f2_frete, f2_seguro, f2_despesa.

- Normalização numérica (itens): d2_quant, d2_prcven, d2_total, d2_baseicm, d2_picm, d2_valicm, D2_DESCON.

- Cabeçalho de integração: o header tenantId é gerado como <UF>,<F2_FILIAL>, em que <UF> é o prefixo de 2 caracteres de f2_filial.

- Consolidação de mensagem: a mensagem final é composta por message e, quando existir, complementada por detailedMessage.

- Resalva de duplicidade: quando a mensagem indicar numero de nota fiscal ja gravado, o retorno é ajustado para sucesso (define Mensagem como OK e code como 0), evitando falha por reenvio.

Rotinas Inteligentes

As rotinas abaixo são rotinas inteligentes identificadas no fluxo:

- Cliente Integrado: Impede o envio quando o cadastro do cliente ainda não está disponível no Protheus.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado

- Nota Fiscal Omni Integrado: Evita reprocessamentos indevidos.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/nota-fiscal-omni-integrado

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: linx/nota_fiscal
- Método HTTP: POST
- Cabeçalhos:
  - Accept: application/json
  - Content-Type: application/json
  - Connection: close
  - Authorization: Basic <credenciais>
  - tenantId: <UF>,<F2_FILIAL>

Tratamento de retorno

Ausência de resposta: registra falha com mensagem JSON: NÃO HOUVE RESPOSTA. e finaliza o item como erro.

Resposta inválida/inesperada: quando não for possível obter code, registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..

Indicadores de sucesso/erro: considera erro quando code for maior que 299. Caso a mensagem indique duplicidade, ajusta o retorno para sucesso.

Ao final do processamento, o item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem consolidada, a situação final (situacao = 2 em sucesso, situacao = 4 em erro, situacao = 3 quando suspenso por dependência) e o tempo de processamento.

Encaminhamento em cenário de erro

Quando houver falha por ausência de resposta, retorno inválido, code maior que 299 (sem resalva) ou erro não previsto, o item permanece registrado em wosk_queue com detalhes do retorno e mensagem para acompanhamento e eventual reprocessamento. Quando a falha estiver ligada à integração pendente de cliente, o item é suspenso com suspensaoTipo e suspensaoChave para indicar o bloqueio.

Notificação

Fluxo do Processo

Critérios de Aceitação