Skip to main content

Importação de Devolução de Pedido de Saída

📌 Descrição do Processo​

A importação de devolução de pedido de saída representa o fluxo de recebimento de devoluções do SAP B1 para o WMS. O SAP B1 atua como origem dos rascunhos de notas de crédito (Drafts do tipo oCreditNotes), enquanto o WMS consome esses documentos para criar pedidos de entrada do tipo devolução.

A integração garante que as notas de crédito geradas no SAP B1 sejam automaticamente registradas no WMS como pedidos de entrada com sub-operação "Devolução", incluindo produtos, quantidades e lotes.

Importante

Este processo utiliza cursor temporal para busca incremental — apenas rascunhos criados ou alterados desde a última sincronização são processados. A integração realiza verificação de duplicidade via IntegrationTracking (campo ExternalId = DocEntry), evitando reprocessamento de documentos já integrados. Além disso, apenas produtos com prefixos válidos configurados nos parâmetros B1 são incluídos.

🔄 Fluxo de Importação​

  1. Consulta de Rascunhos de Notas de Crédito no SAP B1

    • O WMS busca rascunhos (Drafts) do tipo oCreditNotes com status bost_Open no SAP B1, filtrando por DocDate a partir do cursor temporal.
    • Para cada rascunho encontrado, os detalhes completos do documento são recuperados via /Drafts({docEntry}).
    • Documentos cujas linhas não contêm nenhum produto com prefixo válido são descartados.
    • Documentos já presentes no IntegrationTracking são filtrados para evitar duplicidade.

  2. Transformação dos Dados (Parse)

    • Os dados brutos do SAP B1 (B1CreditNoteResponse) são convertidos para o modelo interno OrderImport via AutoMapper.
    • Cada nota de crédito gera um pedido de entrada com Operation = Entrada e SubOperation = "Devolução".
    • Lotes (BatchNumbers) são mapeados para OrderItemVolumeLots; linhas sem lote recebem um lote padrão vazio.

  3. Salvamento no WMS

    • Os pedidos de devolução são persistidos no WMS via RecordOrderService.
    • Registros de IntegrationTracking são salvos para cada pedido (sucesso ou falha), usando EIntegrationOperationType.OrderReturnRequestImport.
    • O cursor de sincronização é atualizado com a data e o DocEntry do último documento processado.

🖥️ APIs Envolvidas​

  • SAP B1 → WMS (GET)
    • /Drafts → busca rascunhos de notas de crédito (DocObjectCode = "oCreditNotes", DocumentStatus = "bost_Open"), filtrados por DocDate >= cursor.LastTimestamp, ordenados por DocDate descendente, com paginação via OData NextLink.
    • /Drafts({docEntry}) → recupera os detalhes completos de cada rascunho, incluindo DocumentLines e BatchNumbers.

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

Cenário:​

  • Fornecedor: AutoPeças Brasil Ltda. (C00150)
  • Rascunho no SAP B1: DocEntry 60300, DocNum 70400
  • Produto devolvido: PA-789 – Bateria 60Ah (20 unidades, 1 lote)
  • Valor total: R$ 3.000,00

1. Nota de Crédito no SAP B1​

{
  "DocEntry": 60300,
  "DocNum": 70400,
  "DocDate": "2026-03-25",
  "DocTime": "14:30:00",
  "CardCode": "C00150",
  "CardName": "AutoPeças Brasil Ltda.",
  "DocTotal": 3000.00,
  "DocumentStatus": "bost_Open",
  "SequenceSerial": 42,
  "DocumentLines": [
    {
      "LineNum": 0,
      "ItemCode": "PA-789",
      "ItemDescription": "Bateria 60Ah",
      "Quantity": 20,
      "UnitPrice": 150.00,
      "WarehouseCode": "WH01",
      "BatchNumbers": [
        {
          "BatchNumber": "LOTE-2026-003",
          "Quantity": 20,
          "ManufacturingDate": "2026-01-15",
          "ExpiryDate": "2028-01-15"
        }
      ]
    }
  ]
}

2. Resultado no WMS​

  • Pedido de entrada criado com RelatedOrderCode = "60300", Operation = Entrada, SubOperation = "Devolução".
  • Produto PA-789 – Bateria 60Ah associado ao pedido com 20 unidades.
  • Lote LOTE-2026-003 registrado com data de fabricação 2026-01-15 e validade 2028-01-15.
  • Registro de IntegrationTracking criado com ExternalId = "60300" e Type = "OrderReturnRequestImport".
  • Cursor atualizado para LastTimestamp = 2026-03-25T14:30:00, LastId = "60300".

✅ Regras de Negócio​

  • Apenas rascunhos do tipo oCreditNotes com status bost_Open são consultados.
  • A importação é incremental — utiliza cursor temporal baseado no DocDate do último documento processado.
  • Produtos são filtrados por prefixo válido configurado nos parâmetros de integração B1 (ValidProductPrefixes: MA, MP, PA, PI, UC, RV). Documentos sem nenhum produto com prefixo válido são descartados integralmente.
  • Documentos cujo DocEntry já exista no IntegrationTracking (tipo OrderReturnRequestImport) são ignorados, evitando duplicidade.
  • Todas as notas de crédito são mapeadas como pedidos de entrada (EDefOperacaoPedido.Entrada) com sub-operação "Devolução".
  • O campo SequenceSerial do SAP B1 é mapeado como InvoiceNumber no WMS.
  • Linhas de documento com BatchNumbers são mapeadas individualmente para OrderItemVolumeLots. Linhas sem lote recebem um lote padrão vazio (LoteConstants.DefaultEmptyLote).
  • Se a busca de rascunhos falhar para uma ErpIntegration, o erro é logado e a integração continua para as demais configurações.
  • Se a recuperação de detalhes de um rascunho individual falhar, o documento é ignorado com log de aviso.
  • O cursor é atualizado ao final da execução: em caso de falha parcial, o cursor aponta para o último pedido com erro; em caso de sucesso total, para o último pedido processado.
  • O processamento é feito por ErpIntegration — cada configuração de ERP é processada independentemente, permitindo múltiplas conexões B1.
Resumo

Esse fluxo garante que as notas de crédito (devoluções) do SAP B1 sejam automaticamente importadas e registradas no WMS como pedidos de entrada do tipo devolução, de forma incremental, com controle de duplicidade e rastreamento completo de lotes.

⚙️ Especificações Técnicas​

Fluxo de execução​

  • Query: Consulta os rascunhos de oCreditNotes no SAP B1, recupera detalhes completos dos documentos, filtra por prefixo de produto válido e elimina duplicados já registrados no IntegrationTracking.
  • Parse: Converte os dados retornados do SAP B1 (B1CreditNoteResponse) para o modelo interno OrderImport via AutoMapper, incluindo mapeamento de lotes e parâmetros de integração B1.
  • Send: Persiste os pedidos de devolução no WMS, salva registros de IntegrationTracking e atualiza o cursor de sincronização.

Detalhamento das Etapas​

Query​

B1CreditNotesIntegrator.Query()
└── B1CreditNotesImportService.GetIntegratedCreditNotesAsync()
    ├── ErpIntegrationsService.GetErpToIntegrateAsync(B1)
    └── [Para cada ErpIntegration]
        ├── ErpIntegrationsService.GetErpIntegrationCursorAsync(OrderReturnRequestImport)
        ├── DraftsConnector.GetDraftsAsync("oCreditNotes", cursor.LastTimestamp)
        ├── [Para cada Draft] → DraftsConnector.GetDraftByKeyAsync<B1CreditNoteResponse>()
        ├── Filtro por prefixos válidos de produto (ValidProductPrefixes)
        └── OrderIntegrationService.VerifyOrderIntegrationTrackingAsync() (deduplicação)
  • B1CreditNotesIntegrator.Query(): ponto de entrada da etapa de consulta. Loga o início e delega ao serviço.
  • B1CreditNotesImportService.GetIntegratedCreditNotesAsync(): orquestra a busca para todas as ErpIntegrations configuradas. Para cada uma, obtém o cursor, busca rascunhos via OData com filtro por tipo e status, recupera detalhes de cada documento, filtra por prefixo de produto e elimina duplicados via IntegrationTracking. Retorna lista vazia com log de aviso se nenhuma integração B1 estiver configurada.
  • DraftsConnector.GetDraftsAsync(): consulta a API /Drafts do SAP B1 filtrando por DocObjectCode = "oCreditNotes", DocumentStatus = "bost_Open" e DocDate >= cursor. Suporta paginação via OData NextLink.
  • DraftsConnector.GetDraftByKeyAsync(): consulta /Drafts({docEntry}) para obter o documento completo. Falhas individuais são logadas e o documento é ignorado.

Parse​

B1CreditNotesIntegrator.Parse()
└── B1CreditNotesImportService.ParseReturnRequestsToOrdersAsync()
    └── [Para cada B1CreditNotesByIntegrator]
        ├── ParametersProvider.GetParametersOrDefault()
        └── Mapper.MapListWithB1Parameters<B1CreditNoteResponse, OrderImport>()
            ├── DocEntry → RelatedOrderCode
            ├── CardCode → RelationalEntityId
            ├── DocDate + DocTime → Typing
            ├── DocTotal → Amount
            ├── SequenceSerial → InvoiceNumber
            ├── (constante) Operation = Entrada, SubOperation = "Devolução"
            └── DocumentLines → OrderItems
                └── BatchNumbers → OrderItemVolumeLots (ou lote padrão vazio)
  • B1CreditNotesIntegrator.Parse(): loga a quantidade de grupos e delega ao serviço.
  • B1CreditNotesImportService.ParseReturnRequestsToOrdersAsync(): para cada grupo, obtém os parâmetros B1 e aplica AutoMapper com contexto de parâmetros. O DefaultLogisticOperationCode é mapeado para RelationalLogisticOperationId.
  • AutoMapper (B1CreditNoteProfile): converte B1CreditNoteResponse → OrderImport e B1CreditNoteLine → OrderItem. Lotes são mapeados individualmente com datas de fabricação e validade; linhas sem lote recebem LoteConstants.DefaultEmptyLote.

Send​

B1CreditNotesIntegrator.Send()
└── [Para cada ParsedReturnRequestsByIntegration]
    └── B1CreditNotesImportService.SaveCreditNotesToWmsAsync()
        ├── RecordOrderService.RecordOrder(orders)
        ├── SaveIntegrationTrackings()
        │   └── OrderIntegrationService.SaveOrderIntegrationTrackingsAsync()
        └── UpdateIntegrationCursor()
            └── ErpIntegrationsService.UpdateErpIntegrationCursorAsync()
  • B1CreditNotesIntegrator.Send(): itera sobre cada grupo, ignorando grupos sem pedidos (Orders.Count == 0) com log informativo.
  • B1CreditNotesImportService.SaveCreditNotesToWmsAsync(): persiste os pedidos no WMS via RecordOrderService, salva registros de rastreamento no IntegrationTracking (com ExternalId = DocEntry, Type = OrderReturnRequestImport, Failed = !success) e atualiza o cursor temporal.
  • UpdateIntegrationCursor(): em caso de falha parcial, o cursor aponta para o último pedido com erro (Success = false); em caso de sucesso total, para o último pedido processado (Success = true).

Resumo do Funcionamento​

  • Incrementalidade: a integração utiliza cursor temporal (LastTimestamp) para processar apenas rascunhos novos ou alterados desde a última execução bem-sucedida.
  • Deduplicação: documentos já integrados são filtrados via IntegrationTracking usando o DocEntry como ExternalId, evitando reprocessamento.
  • Filtro por prefixo: apenas documentos com ao menos um produto cujo código atende aos prefixos configurados (ValidProductPrefixes) são incluídos na importação.
  • Multi-ERP: o fluxo suporta múltiplas configurações de ErpIntegration, processando cada uma independentemente.
  • Mapeamento de lotes: lotes do SAP B1 são mapeados individualmente com quantidades, datas de fabricação e validade. Linhas sem lote recebem um lote padrão vazio.
  • Tratamento de erros: falhas na busca de rascunhos ou detalhes individuais são logadas sem interromper o processamento. Falhas no salvamento de pedidos são registradas no IntegrationTracking com Failed = true e o cursor é atualizado para o ponto de falha, permitindo retentativa na próxima execução.