KitFiscal.Client 1.0.0

KitFiscal.Client — SDK .NET pentru kitfiscal API

Client .NET oficial pentru API-ul HTTP kitfiscal (src/kitfiscal/api.py) — estimator fiscal PFA / SRL Microîntreprindere / SRL Impozit pe Profit (România, 2026).

Licență: acest SDK e MIT — liber de folosit, modificat, redistribuit. Motorul de calcul fiscal la care se conectează (server-side) rămâne sub licență proprietară — vezi Licențiere în README-ul principal.

Onestitate arhitecturală, pentru evitarea confuziei: acest SDK vorbește cu API-ul kitfiscal, care e un calculator de taxe, nu un client e-Factura/ANAF. Nu există (încă) metode de tipul EFactura.SendAsync() — dacă aveți nevoie de integrare e-Factura/SPV, aceea e o componentă separată (vezi mock-server/ din repository pentru un simulator ANAF de dezvoltare) și ar trebui construită/expusă ca atare, nu ascunsă în spatele unui SDK "fiscal" generic.

De ce există

Motorul de calcul (kitfiscal, Python) rămâne sursa unică de adevăr — acest SDK nu reimplementează nicio formulă fiscală. E strict un client HTTP tipat peste endpoint-urile expuse de kitfiscal.api, gândit pentru integrare în ERP-uri, sisteme de contabilitate și aplicații interne scrise în C#/.NET (WinForms, WPF, ASP.NET Core, servicii Azure Functions etc.).

Structură

sdks/dotnet/
├── KitFiscal.Client/                # biblioteca (pachet NuGet)
│   ├── KitFiscalClient.cs           # clientul HTTP propriu-zis
│   ├── KitFiscalClientOptions.cs    # configurare (adresă, timeout, retry, API key)
│   ├── Models/                      # DTO-uri — oglindă 1:1 a schemelor Pydantic din api.py
│   └── Exceptions/                  # KitFiscalApiException, ValidationException, TransportException
├── KitFiscal.Client.Tests/          # teste xUnit (fără dependență de rețea — HttpMessageHandler fals)
└── KitFiscal.Client.sln

Instalare

dotnet add package KitFiscal.Client

Utilizare

Pornește mai întâi serviciul API (vezi rădăcina repository-ului):

pip install -e ".[api]"
uvicorn kitfiscal.api:app --reload

Consumator simplu (script/console)

using KitFiscal.Client;
using KitFiscal.Client.Models;

using var client = KitFiscalClient.Create("http://localhost:8000/");

var rezultat = await client.CalculeazaPfaAsync(new VenitInput
{
    VenitBrutAnual = 250_000,
    CheltuieliAnuale = 60_000,
    SalariuAdministratorLunar = 4_325,
    NumarSalariati = 1,
});

Console.WriteLine($"{rezultat.FormaJuridica}: taxe={rezultat.TotalTaxe:N2} lei, " +
                   $"net={rezultat.VenitNetRamas:N2} lei, rată={rezultat.RataEfectivaTaxare:P2}");

Comparație PFA vs. SRL Micro vs. SRL Profit

var comparativ = await client.ComparaAsync(new VenitInput { VenitBrutAnual = 250_000, CheltuieliAnuale = 60_000 });
Console.WriteLine($"Cel mai favorabil (estimat): {comparativ.CelMaiFavorabil}");

Prag de decizie

var prag = await client.PragDecizieAsync(new PragRequest
{
    FormaA = FormaJuridica.Pfa,
    FormaB = FormaJuridica.SrlMicro,
    VenitMin = 0,
    VenitMax = 500_000,
    CheltuieliAnuale = 60_000,
});
Console.WriteLine(prag.Interpretare);

Integrare cu IHttpClientFactory (ASP.NET Core / servicii long-running)

// Program.cs
builder.Services.AddHttpClient<KitFiscalClient>(c =>
{
    c.BaseAddress = new Uri(builder.Configuration["KitFiscal:BaseUrl"]!);
});

// oriunde e injectat KitFiscalClient
public class RaportFiscalService(KitFiscalClient kitFiscal)
{
    public Task<RezultatFiscal> CalculeazaAsync(VenitInput input) =>
        kitFiscal.CalculeazaPfaAsync(input);
}

Gestionarea erorilor

try
{
    await client.CalculeazaPfaAsync(new VenitInput { VenitBrutAnual = -1000 });
}
catch (KitFiscalValidationException ex)
{
    // 422 — inputul nu a trecut validarea de pe server
    foreach (var eroare in ex.Erori) Console.WriteLine($"  - {eroare}");
}
catch (KitFiscalTransportException ex)
{
    // rețea/timeout, după epuizarea reîncercărilor configurate
}
catch (KitFiscalApiException ex)
{
    // orice alt răspuns non-2xx (ex: 500 de la server)
    Console.WriteLine($"HTTP {(int)ex.StatusCode}: {ex.ResponseBody}");
}

Build & testare locală

Necesită .NET SDK 8.0+.

cd sdks/dotnet
dotnet build
dotnet test                 # teste unitare, fără server pornit — folosesc un HttpMessageHandler fals

Notă despre acest sandbox: codul de mai sus a fost scris și revizuit manual pentru corectitudine C# 12 / .NET 8, dar în mediul în care a fost generat acest pachet nu există un SDK .NET instalat și nuget.org nu e pe lista de domenii permise pentru rețea — deci dotnet build/dotnet test NU au putut fi rulate efectiv aici. Rulați-le local înainte de a publica, ca prim pas de verificare.

Publicare pe NuGet

Automată, prin .github/workflows/publish-dotnet-sdk.yml — se declanșează la un tag Git de forma dotnet-v1.0.0. Folosește Trusted Publishing (OIDC) — nicio cheie API stocată în GitHub Secrets. Configurare, o singură dată, pe nuget.org (Account → Trusted Publishing):

• Repository Owner: Ciprian-LocalPulse
• Repository: kit-fiscal-digital-romania-2026
• Workflow File: publish-dotnet-sdk.yml

Plus o variabilă de repository (nu secret — username-ul NuGet nu e sensibil) în Settings → Secrets and variables → Actions → tab Variables: NUGET_USERNAME = numele de profil NuGet (nu emailul).

git tag dotnet-v1.0.0
git push origin dotnet-v1.0.0

Compatibilitate

• net8.0 (recomandat) și netstandard2.1 (pentru consumatori pe .NET Framework 4.8+ prin proiecte de tip shim, sau Unity/Xamarin) — vezi <TargetFrameworks> din .csproj. Dacă un ERP intern rulează strict pe .NET Framework 4.8 (WinForms/WPF legacy), confirmați compatibilitatea System.Text.Json pe acel target înainte de a-l considera acoperit — netstandard2.1 reduce, dar nu elimină, riscul de incompatibilitate.

Roadmap SDK (dependent de prioritizare)

• Java / Kotlin (Maven) — bănci, telecom, procesatori de plăți
• PHP (Composer/Laravel) — e-commerce (WooCommerce/PrestaShop/Magento)
• Go — microserviciu de validare de volum mare

Fiecare SDK viitor va urma același principiu: client subțire peste kitfiscal.api, fără nicio reimplementare a formulelor fiscale.