Pular para o conteúdo principal

Exportação de Notas de Crédito Processadas — Devolução ao SAP B1

📌 Descrição do Processo​

A exportação de notas de crédito processadas representa o fluxo de devolução de mercadorias do WMS para o SAP B1. O WMS identifica pedidos de devolução já movimentados e ainda não retornados ao ERP, enquanto o SAP B1 recebe as notas de crédito (CreditNotes) correspondentes, concretizando a devolução no módulo fiscal/financeiro.

A integração garante que as devoluções processadas no WMS sejam automaticamente registradas como notas de crédito no SAP B1, incluindo produtos, quantidades, lotes e dados fiscais, com conclusão automática do pedido e rastreabilidade completa via IntegrationTracking.

Importante

Este processo utiliza o padrão pooling — busca periodicamente pedidos de devolução já movimentados. A integração opera sobre rascunhos (Drafts) do tipo oCreditNotes previamente importados do SAP B1 para o WMS. A prevenção de duplicidade é feita via verificação de IntegrationTracking: apenas pedidos com tracking de importação (OrderReturnRequestImport) bem-sucedido e sem tracking de retorno (OrderReturnRequestReturn) são processados.

🔄 Fluxo de Exportação​

  1. Identificação de Devoluções Processadas no WMS

    • O WMS consulta pedidos com status Movimentado, operação Entrada e sub-operação DevolucaoEntrada, agrupados por integração ERP B1 ativa.
    • Apenas pedidos que possuem tracking de importação (OrderReturnRequestImport) bem-sucedido e que não possuem tracking de retorno (OrderReturnRequestReturn) são selecionados.
    • Para cada pedido, o rascunho original (Draft do tipo oCreditNotes) é recuperado do SAP B1 via CodPedidoPolo (que corresponde ao DocEntry do rascunho).
    • Os movimentos de inventário confirmados são carregados, junto com o mapeamento de códigos de produto WMS → SAP B1.

  2. Montagem das Requisições de Nota de Crédito (Parse)

    • Os movimentos confirmados do tipo ColocarQuantidadeLogicamente são agrupados por produto e endereço de armazenagem.
    • Para cada grupo, uma linha de documento (DocumentLine) é criada com ItemCode, InventoryQuantity, UnitPrice, WarehouseCode, TaxCode, CFOPCode, BaseEntry e BaseLine — obtidos do rascunho original no SAP B1.
    • Lotes (BatchNumbers) são mapeados a partir dos movimentos, incluindo BatchNumber, quantidade, datas de admissão e validade.
    • O request final (B1CreditNoteCreateRequest) é montado via AutoMapper a partir do rascunho, com DocDueDate definido como hoje + 15 dias e Comments indicando o pedido WMS de origem.

  3. Envio das Notas de Crédito ao SAP B1

    • Cada nota de crédito é enviada individualmente via POST /CreditNotes ao SAP B1.
    • Para cada nota criada com sucesso, o pedido correspondente é concluído no WMS e o rascunho original é marcado como processado no SAP B1.

  4. Registro de Auditoria

    • Cada operação (sucesso ou falha) é registrada na tabela IntegrationTracking com tipo OrderReturnRequestReturn, armazenando request, response, ExternalId (DocEntry da nota de crédito no B1) e RelatedId (código do pedido no WMS).

🖥️ APIs Envolvidas​

  • WMS → SAP B1 (GET)

    • /Drafts({docEntry}) → recupera o rascunho original da nota de crédito (oCreditNotes) com DocumentLines, BatchNumbers, dados fiscais e referências de documento.

  • WMS → SAP B1 (POST)

    • /CreditNotes → cria nota de crédito definitiva no SAP B1, com linhas vinculadas ao documento base via BaseEntry/BaseLine. Retorna DocEntry e DocNum.

  • WMS → SAP B1 (PATCH)

    • /Drafts({docEntry}) → marca o rascunho como processado após criação bem-sucedida da nota de crédito.

📦 Exemplo de Exportação (Objeto Fictício)​

Cenário:​

  • Fornecedor: AutoPeças Brasil Ltda. (C00150)
  • Pedido de devolução WMS: #92010, referência no SAP B1 (Draft): DocEntry 60300
  • Produto devolvido: PA-789 – Bateria 60Ah (15 unidades, lote LT-2026-050)
  • Valor unitário: R$ 150,00

1. Rascunho (Draft) no SAP B1​

{
  "DocEntry": 60300,
  "DocNum": 70400,
  "DocDate": "2026-03-20",
  "CardCode": "C00150",
  "CardName": "AutoPeças Brasil Ltda.",
  "DocumentStatus": "bost_Open",
  "SequenceSerial": 42,
  "SequenceCode": 3,
  "DocumentLines": [
    {
      "LineNum": 0,
      "ItemCode": "PA-789",
      "ItemDescription": "Bateria 60Ah",
      "Quantity": 20,
      "UnitPrice": 150.00,
      "TaxCode": "ICMS-001",
      "CFOPCode": "1202",
      "WarehouseCode": "WH01",
      "BaseType": 234,
      "BaseEntry": 60250,
      "BaseLine": 0,
      "UoMEntry": 1
    }
  ]
}

2. Nota de Crédito Enviada ao SAP B1​

{
  "CardCode": "C00150",
  "DocDate": "2026-03-20",
  "TaxDate": "2026-03-20",
  "DocDueDate": "2026-04-10",
  "Comments": "WMS: Devolução processada - Pedido 92010",
  "SequenceSerial": 42,
  "SequenceCode": 3,
  "BPL_IDAssignedToInvoice": 1,
  "DocumentLines": [
    {
      "ItemCode": "PA-789",
      "InventoryQuantity": 15,
      "UnitPrice": 150.00,
      "TaxCode": "ICMS-001",
      "CFOPCode": "1202",
      "WarehouseCode": "WH01",
      "BaseType": 234,
      "BaseEntry": 60250,
      "BaseLine": 0,
      "UoMEntry": 1,
      "BatchNumbers": [
        {
          "BatchNumber": "LT-2026-050",
          "Quantity": 15,
          "AddmisionDate": "2026-03-25",
          "ExpiryDate": "2027-03-25",
          "BaseLineNumber": 0,
          "ItemCode": "PA-789"
        }
      ]
    }
  ]
}

3. Resultado​

  • SAP B1 retorna: DocEntry 71200, DocNum 71200.
  • Pedido #92010 foi concluído no WMS.
  • Rascunho DocEntry 60300 foi marcado como processado no SAP B1.
  • IntegrationTracking registrado com ExternalId = "71200", RelatedId = 92010, tipo OrderReturnRequestReturn.

✅ Regras de Negócio​

  • Apenas pedidos com status Movimentado, operação Entrada e sub-operação DevolucaoEntrada são elegíveis.
  • O pedido deve possuir CodPedidoPolo válido (correspondente ao DocEntry do rascunho no SAP B1).
  • O pedido deve ter um tracking de importação (OrderReturnRequestImport) bem-sucedido — indicando que a solicitação de devolução foi previamente importada do SAP B1.
  • O pedido não deve ter tracking de retorno (OrderReturnRequestReturn) — evitando reprocessamento de devoluções já enviadas.
  • Apenas movimentos do tipo ColocarQuantidadeLogicamente com status confirmado são considerados para montar as linhas da nota de crédito.
  • Todos os produtos do pedido devem possuir mapeamento de código WMS → SAP B1 (ProdutoRelacionado); caso contrário, o pedido é descartado no parse.
  • Os movimentos são agrupados por produto e endereço, consolidando quantidades na mesma linha de documento.
  • O WarehouseCode da linha é obtido da classificação do endereço do movimento; caso não disponível, utiliza o valor do rascunho original.
  • Informações de lote (BatchNumber, quantidade, datas de admissão e validade) são extraídas dos movimentos de inventário.
  • DocDueDate é calculado como data atual + 15 dias.
  • BPL_IDAssignedToInvoice utiliza o DefaultBranchId dos parâmetros B1 da integração.
  • Após criação bem-sucedida da nota de crédito, o pedido é concluído no WMS e o rascunho é marcado como processado no SAP B1.
  • Falhas individuais não bloqueiam o processamento dos demais pedidos do mesmo lote.
  • Cada operação (sucesso ou falha) gera um registro de IntegrationTracking com tipo OrderReturnRequestReturn.
Resumo

Esse fluxo garante que as devoluções processadas no WMS sejam automaticamente registradas como notas de crédito no SAP B1, mantendo a consistência fiscal e de estoque entre ambos os sistemas, com rastreabilidade completa e prevenção de duplicidade.

⚙️ Especificações Técnicas​

Fluxo de execução​

  • Query: Consulta pedidos de devolução movimentados e não retornados no WMS, recupera os rascunhos correspondentes no SAP B1, carrega movimentos de inventário confirmados e mapeamento de produtos.
  • Parse: Agrupa movimentos por produto/endereço, monta as linhas da nota de crédito com lotes, e converte o rascunho do SAP B1 para B1CreditNoteCreateRequest via AutoMapper.
  • Send: Envia notas de crédito ao SAP B1, conclui pedidos no WMS, marca rascunhos como processados e registra auditoria no IntegrationTracking.

Detalhamento das Etapas​

Query​

B1ProcessedCreditNotesIntegrator.Query()
└── B1ProcessedCreditNotesService.GetProcessedCreditNotesAsync()
    ├── ErpIntegrationsService.GetErpToIntegrateAsync(EDefIntegration.B1)
    ├── PedidoRepository.GetProcessedCreditNotesAsync(erpIntegrationId)
    │   └── Filtros: Movimentado + Entrada + DevolucaoEntrada
    │       + tem OrderReturnRequestImport (sucesso)
    │       + não tem OrderReturnRequestReturn
    ├── B1DraftsConnector.GetDraftByKeyAsync<B1CreditNoteResponse>(docEntry)
    ├── InventarioRepository.GetConfirmedMovementsByPedidosAsync(codPedidos)
    └── ProdutoRelacionadoRepository.GetAll() → mapeamento CodProduto → CodProdutoRel
  • B1ProcessedCreditNotesIntegrator.Query(): Ponto de entrada — delega ao serviço de notas de crédito processadas.
  • B1ProcessedCreditNotesService.GetProcessedCreditNotesAsync(): Para cada integração ERP B1 ativa, busca pedidos de devolução elegíveis, recupera os rascunhos do SAP B1, carrega os movimentos confirmados e o mapeamento de produtos. Retorna List<ProcessedCreditNotesByIntegration>.
  • PedidoRepository.GetProcessedCreditNotesAsync(): Consulta EF Core com filtros de status, operação, sub-operação e validação de trackings existentes.
  • B1DraftsConnector.GetDraftByKeyAsync(): GET /Drafts({docEntry}) — recupera o rascunho completo com linhas, lotes e referências.
  • InventarioRepository.GetConfirmedMovementsByPedidosAsync(): Busca movimentos confirmados (tipo ColocarQuantidadeLogicamente, status 3) agrupados por pedido.

Parse​

B1ProcessedCreditNotesIntegrator.Parse()
└── B1ProcessedCreditNotesService.ParseToB1Async()
    ├── Filtra movimentos: apenas ColocarQuantidadeLogicamente
    ├── Valida mapeamento de produtos (WMS → B1)
    ├── Agrupa movimentos por (Produto + Endereço)
    ├── Monta DocumentLines com BatchNumbers
    ├── AutoMapper: B1CreditNoteResponse → B1CreditNoteCreateRequest
    └── Define Comments, DocDueDate, BPL_IDAssignedToInvoice
  • B1ProcessedCreditNotesIntegrator.Parse(): Delega toda a transformação ao serviço.
  • B1ProcessedCreditNotesService.ParseToB1Async(): Para cada pedido de cada integração:
    1. Valida existência do rascunho e dos movimentos confirmados.
    2. Filtra movimentos do tipo ColocarQuantidadeLogicamente.
    3. Valida que todos os produtos possuem mapeamento B1 (descarta pedido se algum faltar).
    4. Agrupa movimentos por produto + endereço, consolidando quantidades.
    5. Cria B1CreditNoteDocumentLine com dados do rascunho (TaxCode, CFOPCode, BaseEntry, BaseLine, UoMEntry) e quantidades/lotes dos movimentos.
    6. Converte rascunho para B1CreditNoteCreateRequest via AutoMapper, adicionando Comments e DocDueDate.
    7. Mantém mapeamento CreditNoteToCodPedido para rastreabilidade nas fases seguintes.

Send​

B1ProcessedCreditNotesIntegrator.Send()
└── [Para cada integração com CreditNotes]
    ├── B1ProcessedCreditNotesService.SendCreditNotesToB1Async()
    │   ├── B1CreditNoteConnector.CreateCreditNoteAsync()  → POST /CreditNotes
    │   ├── ConcludeOrderService.ConcludeOrderAsync()      → Conclui pedido no WMS
    │   └── B1DraftsConnector.MarkDraftAsProcessedAsync()   → Marca rascunho como processado
    │
    └── B1ProcessedCreditNotesService.SaveIntegrationTrackingsAsync()
        └── OrderIntegrationService.SaveOrderIntegrationTrackingsAsync()
            └── IntegrationTrackingRepository.AddRangeAsync()
  • B1ProcessedCreditNotesIntegrator.Send(): Itera sobre cada grupo de integração, trata exceções individualmente e loga contadores de sucesso/falha.
  • B1ProcessedCreditNotesService.SendCreditNotesToB1Async(): Para cada nota de crédito, envia via POST /CreditNotes. Em caso de sucesso: conclui o pedido no WMS e marca o rascunho como processado no B1. Retorna Dictionary<int, Result<B1CreditNoteCreateResponse>>.
  • B1CreditNoteConnector.CreateCreditNoteAsync(): Envia a requisição HTTP POST /CreditNotes ao SAP B1 Service Layer e retorna Result<B1CreditNoteCreateResponse> com DocEntry e DocNum.
  • ConcludeOrderService.ConcludeOrderAsync(): Atualiza o status do pedido para concluído no banco do WMS.
  • B1DraftsConnector.MarkDraftAsProcessedAsync(): Marca o rascunho original no SAP B1 com o número do documento gerado.
  • B1ProcessedCreditNotesService.SaveIntegrationTrackingsAsync(): Monta IntegrationUpdateResult para cada operação e persiste via OrderIntegrationService, com ExternalId = DocEntry e RelatedId = CodPedido.

Resumo do Funcionamento​

  • Busca com prevenção de duplicidade: Apenas pedidos de devolução com tracking de importação e sem tracking de retorno são processados, garantindo que cada devolução seja enviada ao SAP B1 uma única vez.
  • Vinculação com rascunho original: Os dados fiscais e de linha (TaxCode, CFOPCode, BaseEntry, BaseLine) são herdados do rascunho original do SAP B1, mantendo consistência contábil.
  • Consolidação de movimentos: Movimentos de inventário são agrupados por produto e endereço, evitando linhas duplicadas na nota de crédito.
  • Rastreabilidade de lotes: Informações completas de lote (número, quantidade, datas) são preservadas do WMS para o SAP B1.
  • Conclusão automática: Pedidos faturados com sucesso são automaticamente concluídos no WMS e os rascunhos correspondentes são marcados como processados no SAP B1.
  • Resiliência a falhas: Erros em pedidos individuais são tratados isoladamente — falhas não interrompem o processamento dos demais pedidos do mesmo lote. Exceções são capturadas no nível da integração com log de erro.
  • Rastreabilidade completa: Cada operação gera um IntegrationTracking com tipo OrderReturnRequestReturn, armazenando request e response completos, vinculando RelatedId (CodPedido) ao ExternalId (DocEntry do B1).