SaphetyToDDL.Lib 1.0.10

SaphetyToDDL

A .NET Standard 2.0 library that parses Saphety electronic documents (Invoices, Orders, Credit Notes) from XML and maps them to a common accounting domain-driven model (DDL), with round-trip JSON/XML serialization.

🎯 Purpose

Saphety is a Portuguese EDI platform. Systems integrating with it (e.g. ERP extensions) receive documents as provider-specific XML that needs to be turned into a neutral transaction shape before it can be imported, and turned back into Saphety XML when exporting. SaphetyToDDL owns that mapping so consuming applications never touch the Saphety schema directly.

✨ Features

• 📄 XML → DDL parsing — deserializes Saphety Invoice/Order/CreditNote XML (docTypeId 1/2/4) into an ItemTransaction object graph (header, party, lines, taxes, payment).
• 🔁 DDL → XML serialization — maps an ItemTransaction back to Saphety Invoice XML for export flows.
• 🧾 Flexible item identification — resolves the line item id from tradeItemIdentification, falling back to sellerAssignedTradeItemIdentification when the source system omits it (common on real-world Order documents).
• 🚚 Flexible ship-to/unload data — resolves the unload address and unload date from the document header (shipTo / documentDates.deliveryDate), falling back to the first line item's deliveryLocation / documentLineDates.deliveryDate when the header doesn't carry them.
• 🔄 JSON serialization — the mapped ItemTransaction serializes cleanly to/from JSON via Newtonsoft.Json for storage or transport.

🏗️ Architecture

Key types (SaphetyToDDL.Lib):

🛠️ Tech Stack

• .NET Standard 2.0
• AutoMapper 10.1.1 — object-to-object mapping between Saphety XML models and DDL models
• Newtonsoft.Json 13.0.3 — JSON serialization of the DDL model
• System.Xml.Serialization — XML (de)serialization of Saphety documents

🚀 Quick Start

Prerequisites

• .NET Standard 2.0–compatible SDK / Visual Studio 2022

Setup

nuget restore SaphetyToDDL.sln
msbuild SaphetyToDDL.sln /p:Configuration=Release /p:Platform=AnyCPU

Usage

using Newtonsoft.Json;

var parser = new SaphetyToDDL.Lib.SaphetyToDDL();

// Parse a Saphety XML file (Invoice, Order or CreditNote) into the DDL model
var itemTransaction = parser.ParseFromFile(@"C:\path\to\document.xml");

var serializeOptions = new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore,
};

var json = JsonConvert.SerializeObject(itemTransaction, Formatting.Indented, serializeOptions);
Console.WriteLine(json);

// Reverse mapping: DDL -> Saphety Invoice XML
var invoiceXml = SaphetyToDDL.Lib.SaphetyToDDL.SerializeInvoiceToXml(
    SaphetyToDDL.Lib.SaphetyToDDL.MapFromDdl(itemTransaction));

📋 Configuration

There is no runtime configuration — behavior is controlled entirely by the input XML's docTypeId attribute (1 = Invoice, 2 = Order, 4 = CreditNote) and by which elements are present in the source document (see the fallback behavior under Features).

🧪 Testing

Run SaphetyToDDL.Console and use its interactive menu against the embedded sample resources (SaphetyToDDL.Console/Properties/Resources.resx) to exercise:

1. Saphety XML → DDL JSON
2. DDL JSON (file) → Saphety Invoice XML
3. DDL JSON (inline sample string) → Saphety Invoice XML

📦 Distribution

Packaged and published as the SaphetyToDDL.Lib NuGet package via SaphetyToDDL.Lib/nugetPackagePush.cmd, which bumps the version in the .csproj/.nuspec, builds Release, commits/tags (vX.Y.Z), pushes to main, and publishes to nuget.org using SaphetyToDDL.Lib.nuspec.

📚 Documentation

See inline XML doc comments on SaphetyToDDL.Lib.SaphetyToDDL for method-level details on parsing and mapping.

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.

Issues and suggestions: GitHub repository.