Albatrosmedia.Softim.HeliosServiceGateAdapter 1.1.0

Helios ServiceGate Adapter

Moderní .NET 8.0 adapter pro komunikaci s Helios ServiceGate API. Poskytuje jednoduchý interface pro vkládání, aktualizaci, mazání záznamů a spouštění funkcí v systému Helios Green.

Instalace

dotnet add package Albatrosmedia.Softim.HeliosServiceGateAdapter

Rychlý start

1. Inicializace služby

using Albatrosmedia_Softim_ServiceGateAdapterAPI.Services;
using Albatrosmedia_Softim_ServiceGateAdapterAPI.Models;

// Produkční použití - název aplikace se automaticky zjistí z assembly
var service = new ServiceGateAdapterService("https://your-servicegate-api-url/");
// V logu sga.ApiLogs bude ve sloupci Source např. "MojeAplikace" (název vašeho projektu)

// Nebo explicitní zadání názvu aplikace
var service2 = new ServiceGateAdapterService("https://your-servicegate-api-url/", "MujVlastniNazev");

// POUZE pro development/testing s self-signed certifikáty
// var service = new ServiceGateAdapterService("https://your-servicegate-api-url/", ignoreSslErrors: true);

⚠️ Bezpečnostní upozornění: Nikdy nepoužívejte ignoreSslErrors: true v produkčním prostředí! Vypnutí SSL validace otevírá dveře man-in-the-middle útokům.

Identifikace zdrojové aplikace (Source)

Od verze 1.1.0 je v logu API (sga.ApiLogs sloupec Source) automaticky zaznamenán název volající aplikace. Toto je velmi užitečné pro sledování, která aplikace volala jaké operace.

Automatická detekce názvu:

• Název aplikace se automaticky zjistí z Assembly.GetEntryAssembly() (název vašeho hlavního projektu)
• Pokud se zjistit nepodaří, použije se název z AppDomain.CurrentDomain.FriendlyName
• Volání ze Swaggeru (detekováno na straně API) bude mít Source = "Swagger"

// Automatická detekce - název aplikace se zjistí automaticky
var service = new ServiceGateAdapterService("https://api.example.com/");

// Explicitní zadání - pokud chcete použít vlastní název
var pointaService = new ServiceGateAdapterService("https://api.example.com/", "Pointa");
var eshopService = new ServiceGateAdapterService("https://api.example.com/", "Eshop");

// V sga.ApiLogs pak uvidíte ve sloupci Source: "Pointa", "Eshop" nebo název vašeho assembly

2. Vložení/Aktualizace záznamu

var record = new ServiceGateRecord
{
    FolderId = 1,
    ClassId = 100
};

// Přidání atributů
record.AddAttribute("nazev", "Nový subjekt");
record.AddAttribute("ico", "12345678");
record.AddAttribute("datum_zalozeni", DateTime.Now);

// Přidání vztahu
var relation = new Relation
{
    RelationNumber = 1,
    RelatedRecordClassId = 200,
    RelatedRecordFolderId = 2,
    PrimaryKey = "cislo_subjektu",
    ForeignKey = "dodavatel_id",
    RelatedRecordRecordNumber = "12345",
    IsDynamic = false,
    RelationSide = RelationSide.Left
};
record.AddRelation(relation);

// Volání API
var response = await service.InsertUpdateAsync(record);

if (response.Success)
{
    Console.WriteLine($"Úspěch! RecordNumber: {response.Data?.RecordNumber}");
}

3. Mazání záznamu

var record = new ServiceGateRecord
{
    FolderId = 1,
    ClassId = 100,
    RecordNumber = 12345
};

var response = await service.DeleteAsync(record);

4. Spuštění funkce

var function = new ServiceGateFunction();
function.FunctionId = 100;

// Přidání parametrů
function.AddParameter("datum_potvrzeni_platby", DateTime.Now);
function.AddParameter("cislo_objednavky", "ORD-12345");

// Přidání záznamu
function.AddRecord(classId: 1323, folderId: 1, recordNumber: 22);

// Volání funkce
var response = await service.RunFunctionAsync(function);

if (response.Success)
{
    Console.WriteLine("Funkce úspěšně dokončena!");
    if (response.FunctionResult?.Messages != null)
    {
        Console.WriteLine($"Zprávy: {response.FunctionResult.Messages}");
    }
}

Klíčové vlastnosti

Řízené pořadí atributů a vztahů

Adapter podporuje řízené pořadí mezi atributy a vztahy pomocí OrderedItemsAndRelations. Toto umožňuje flexibilní řazení ve formátu: atribut1, vztah1, atribut2, vztah2, atd.

record.AddAttribute("atribut1", "hodnota1");
record.AddRelation(relation1);
record.AddAttribute("atribut2", "hodnota2");

Automatická konverze typů

Adapter automaticky převádí různé datové typy:

• DateTime → formát pro Helios (MM/dd/yyyy hh:mm:ss tt)
• double, decimal → s použitím InvariantCulture (tečka jako oddělovač)
• int, long → řetězcová reprezentace

Kontrola spouštění aplikační logiky

Můžete vypnout spouštění aplikační logiky v Heliosu pro konkrétní atribut:

record.AddAttribute("atribut", "hodnota", skipNullValues: false, triggerEvents: false);

Přidání položek k záznamu

var item = new ServiceGateRecordItem();
item.AddAttribute("nazev_polozky", "Produkt A");
item.AddAttribute("mnozstvi", 10);
item.AddAttribute("cena", 199.99);

record.Items.Add(item);

Podporované operace

• InsertUpdateAsync - Vložení nového nebo aktualizace existujícího záznamu
• DeleteAsync - Smazání záznamu
• RunFunctionAsync - Spuštění funkce v Heliosu

Struktura odpovědi

Všechny operace vrací objekt ResponseData:

public class ResponseData
{
    public bool Success { get; set; }
    public int StatusCode { get; set; }
    public string Message { get; set; }
    public ServiceGateRecord Data { get; set; }
    public FunctionResult FunctionResult { get; set; }
}

Požadavky

• .NET 8.0 nebo novější
• Helios ServiceGate API
• Platný SSL certifikát na ServiceGate API serveru (pro produkční použití)

Bezpečnostní doporučení

⚠️ Důležité:

1. SSL Certifikáty: V produkci vždy používejte platné SSL certifikáty. Parametr ignoreSslErrors je určen pouze pro development/testing.
2. Autentizace: Doporučujeme zabezpečit ServiceGate API pomocí autentizace (API Key, JWT, OAuth).
3. HTTPS: Vždy používejte HTTPS pro komunikaci s API.
4. Credentials: Nikdy neukládejte přihlašovací údaje přímo v kódu - používejte User Secrets, Azure Key Vault nebo jiné bezpečné úložiště.

Licence

MIT License - viz LICENSE

Podpora

Pro více informací a kompletní dokumentaci navštivte GitHub repository.