BrainEnterprise.Api.Ateco 2.0.0

ATECO Client for .NET

Complete C# client library for consuming both ATECO 2025 and ATECO 2007 APIs. Supports both API v1 and v2 with synchronous and asynchronous methods.

🚀 Quick Start

Installation

dotnet add package BrainEnterprise.Api.Ateco

Basic Usage - ATECO 2025

using BrainEnterprise.Api.Ateco;

// Create ATECO 2025 client
using var client = new Ateco2025ApiClient("http://your-api-url:5000", apiVersion: 1);

// Check availability
bool isAvailable = await client.IsApiAvailableAsync();

// Get all codes
var all = await client.GetAllAsync();
Console.WriteLine($"Total codes: {all.Count}");

// Get specific code
var code = await client.GetByCodeAsync("01.11.00");
Console.WriteLine($"{code?.Code}: {code?.ItalianTitle}");

// Search
var results = await client.SearchAsync("agriculture");

// Get children
var children = await client.GetChildrenAsync("01");

Basic Usage - ATECO 2007

using BrainEnterprise.Api.Ateco;

// Create ATECO 2007 client
using var client = new Ateco2007ApiClient("http://your-api-url:5000", apiVersion: 1);

// Get all codes
var all = await client.GetAllAsync();
Console.WriteLine($"Total ATECO 2007 codes: {all.Count}");

// Get specific code
var code = await client.GetByCodeAsync("A");
Console.WriteLine($"{code?.Code}: {code?.Title}");

// Search
var results = await client.SearchAsync("agricoltura");

// Get children
var children = await client.GetChildrenAsync("01");

🌟 Features

• ✅ Dual API Support - Both ATECO 2025 and ATECO 2007
• ✅ Complete API coverage - All endpoints for v1 and v2
• ✅ Async & Sync methods - Choose what fits your needs
• ✅ Strongly typed - Full IntelliSense support
• ✅ Error handling - Custom exceptions with details
• ✅ Dependency Injection ready - Perfect for ASP.NET Core
• ✅ .NET Standard 2.0 - Maximum compatibility (.NET Framework 4.6.2+, .NET Core 2.0+, .NET 5+)

📖 API Reference

ATECO 2025 Client

Common Methods (v1 and v2)

using var client = new Ateco2025ApiClient("http://api:5000", apiVersion: 1);

// Get all ATECO codes
var all = await client.GetAllAsync();

// Get specific code
var code = await client.GetByCodeAsync("A");

// Get children
var children = await client.GetChildrenAsync("01");

// Get complete hierarchy
var hierarchy = await client.GetCompleteHierarchyAsync("01");

// Search by text
var results = await client.SearchAsync("agriculture");

// Get by level (1-6)
var sections = await client.GetByLevelAsync(1);

V2 Specific Methods

// Create v2 client
using var client = new Ateco2025ApiClient("http://api-url:5000", apiVersion: 2);

// Pagination
var paginated = await client.GetAllPaginatedAsync(page: 1, pageSize: 50);

// Code with children info
var codeInfo = await client.GetByCodeWithInfoAsync("A");

// Children with grandchildren
var childrenWithGrand = await client.GetChildrenWithGrandchildrenAsync("01", true);

// Hierarchy with statistics
var hierarchyStats = await client.GetHierarchyWithStatsAsync("01");

// Advanced search
var filtered = await client.SearchWithFiltersAsync("agriculture", level: 1, limit: 10);

ATECO 2007 Client

Common Methods (v1 and v2)

using var client = new Ateco2007ApiClient("http://api:5000", apiVersion: 1);

// Get all ATECO 2007 codes
var all = await client.GetAllAsync();

// Get specific code
var code = await client.GetByCodeAsync("A");

// Get children
var children = await client.GetChildrenAsync("01");

// Get complete hierarchy
var hierarchy = await client.GetCompleteHierarchyAsync("01");

// Search by text
var results = await client.SearchAsync("agricoltura");

// Get by level (1-6)
var sections = await client.GetByLevelAsync(1);

V2 Specific Methods

// Create v2 client
using var client = new Ateco2007ApiClient("http://api-url:5000", apiVersion: 2);

// Pagination
var paginated = await client.GetAllPaginatedAsync(page: 1, pageSize: 50);

// Code with children info
var codeInfo = await client.GetByCodeWithInfoAsync("A");

// Children with grandchildren
var childrenWithGrand = await client.GetChildrenWithGrandchildrenAsync("01", true);

// Hierarchy with statistics
var hierarchyStats = await client.GetHierarchyWithStatsAsync("01");

// Advanced search
var filtered = await client.SearchWithFiltersAsync("agricoltura", level: 1, limit: 10);

Synchronous Methods

All async methods have synchronous versions:

// ATECO 2025
var client2025 = new Ateco2025ApiClient("http://api:5000");
var all2025 = client2025.GetAll();
var code2025 = client2025.GetByCode("A");
var children2025 = client2025.GetChildren("01");

// ATECO 2007
var client2007 = new Ateco2007ApiClient("http://api:5000");
var all2007 = client2007.GetAll();
var code2007 = client2007.GetByCode("A");
var children2007 = client2007.GetChildren("01");

🏗️ Dependency Injection (ASP.NET Core)

Register Both Clients

// Program.cs
using BrainEnterprise.Api.Ateco;

// Register ATECO 2025 Client
builder.Services.AddHttpClient<Ateco2025ApiClient>();
builder.Services.AddScoped<Ateco2025ApiClient>(sp =>
{
    var httpClient = sp.GetRequiredService<HttpClient>();
    return new Ateco2025ApiClient(httpClient, "http://localhost:5000", apiVersion: 2);
});

// Register ATECO 2007 Client
builder.Services.AddHttpClient<Ateco2007ApiClient>();
builder.Services.AddScoped<Ateco2007ApiClient>(sp =>
{
    var httpClient = sp.GetRequiredService<HttpClient>();
    return new Ateco2007ApiClient(httpClient, "http://localhost:5000", apiVersion: 2);
});

Use in Controllers

public class AtecoController : ControllerBase
{
    private readonly Ateco2025ApiClient _client2025;
    private readonly Ateco2007ApiClient _client2007;

    public AtecoController(Ateco2025ApiClient client2025, Ateco2007ApiClient client2007)
    {
        _client2025 = client2025;
        _client2007 = client2007;
    }

    [HttpGet("2025/sections")]
    public async Task<IActionResult> Get2025Sections()
    {
        var sections = await _client2025.GetByLevelAsync(1);
        return Ok(sections.Results);
    }

    [HttpGet("2007/sections")]
    public async Task<IActionResult> Get2007Sections()
    {
        var sections = await _client2007.GetByLevelAsync(1);
        return Ok(sections.Results);
    }

    [HttpGet("2025/validate/{code}")]
    public async Task<IActionResult> Validate2025Code(string code)
    {
        var result = await _client2025.GetByCodeAsync(code);
        return Ok(new { valid = result != null, code = result });
    }

    [HttpGet("2007/validate/{code}")]
    public async Task<IActionResult> Validate2007Code(string code)
    {
        var result = await _client2007.GetByCodeAsync(code);
        return Ok(new { valid = result != null, code = result });
    }
}

🎯 Models

ATECO 2025 Models

Ateco2025Code

public class Ateco2025Code
{
    public int Order { get; set; }
    public string Code { get; set; }
    public string ItalianTitle { get; set; }
    public string EnglishTitle { get; set; }
    public int Hierarchy { get; set; }          // Level 1-6
    public string? ParentCode { get; set; }
    public int? ParentHierarchy { get; set; }
}

Ateco2025CodeHierarchy

public class Ateco2025CodeHierarchy
{
    public int Order { get; set; }
    public string Code { get; set; }
    public string ItalianTitle { get; set; }
    public string EnglishTitle { get; set; }
    public int Hierarchy { get; set; }
    public string? ParentCode { get; set; }
    public int? ParentHierarchy { get; set; }
    public List<Ateco2025CodeHierarchy> Children { get; set; }
}

ATECO 2007 Models

Ateco2007Code

public class Ateco2007Code
{
    public string Code { get; set; }
    public string Title { get; set; }
    public int Hierarchy { get; set; }          // Level 1-6
    public string? ParentCode { get; set; }
}

Ateco2007CodeHierarchy

public class Ateco2007CodeHierarchy
{
    public string Code { get; set; }
    public string Title { get; set; }
    public int Hierarchy { get; set; }
    public string? ParentCode { get; set; }
    public List<Ateco2007CodeHierarchy> Children { get; set; }
}

Hierarchical Levels

Both ATECO 2025 and 2007 share the same hierarchical structure:

1. Sections (level 1) - e.g., "A"
2. Divisions (level 2) - e.g., "01"
3. Groups (level 3) - e.g., "01.1"
4. Classes (level 4) - e.g., "01.11"
5. Categories (level 5) - e.g., "01.11.0"
6. Subcategories (level 6) - e.g., "01.11.00"

⚠️ Error Handling

try
{
    var client = new Ateco2025ApiClient("http://api:5000");
    var code = await client.GetByCodeAsync("INVALID");
}
catch (AtecoApiException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
    Console.WriteLine($"Status Code: {ex.StatusCode}");
    Console.WriteLine($"Response: {ex.ResponseContent}");
}
catch (ArgumentException ex)
{
    Console.WriteLine($"Invalid argument: {ex.Message}");
}
catch (NotSupportedException ex)
{
    Console.WriteLine($"Feature not supported: {ex.Message}");
}

🔧 Configuration

Timeout

var client = new Ateco2025ApiClient("http://localhost:5000");
client.Timeout = TimeSpan.FromMinutes(2);

Cancellation Token

var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(10));

var result = await client.GetAllAsync(cts.Token);

Custom HttpClient

var httpClient = new HttpClient
{
    Timeout = TimeSpan.FromSeconds(30),
    BaseAddress = new Uri("http://localhost:5000")
};

var client = new Ateco2025ApiClient(httpClient, "http://localhost:5000", apiVersion: 2);

💡 Examples

Compare ATECO 2025 and 2007

public async Task CompareCodes(string code)
{
    using var client2025 = new Ateco2025ApiClient("http://api:5000");
    using var client2007 = new Ateco2007ApiClient("http://api:5000");

    var code2025 = await client2025.GetByCodeAsync(code);
    var code2007 = await client2007.GetByCodeAsync(code);

    Console.WriteLine($"ATECO 2025: {code2025?.ItalianTitle}");
    Console.WriteLine($"ATECO 2007: {code2007?.Title}");
}

Validate ATECO Code

public async Task<bool> Validate2025Code(string code)
{
    using var client = new Ateco2025ApiClient("http://api:5000");
    var result = await client.GetByCodeAsync(code);
    return result != null;
}

public async Task<bool> Validate2007Code(string code)
{
    using var client = new Ateco2007ApiClient("http://api:5000");
    var result = await client.GetByCodeAsync(code);
    return result != null;
}

Get All Sections

public async Task<List<Ateco2025Code>> Get2025Sections()
{
    using var client = new Ateco2025ApiClient("http://api:5000");
    var sections = await client.GetByLevelAsync(1);
    return sections.Results;
}

public async Task<List<Ateco2007Code>> Get2007Sections()
{
    using var client = new Ateco2007ApiClient("http://api:5000");
    var sections = await client.GetByLevelAsync(1);
    return sections.Results;
}

Search with Pagination (V2)

public async Task<PaginatedResponse> Search2025Paginated(string query, int page)
{
    using var client = new Ateco2025ApiClient("http://api:5000", apiVersion: 2);
    return await client.GetAllPaginatedAsync(page, 50);
}

public async Task<Ateco2007PaginatedResponse> Search2007Paginated(string query, int page)
{
    using var client = new Ateco2007ApiClient("http://api:5000", apiVersion: 2);
    return await client.GetAllPaginatedAsync(page, 50);
}

Batch Validation

public async Task<Dictionary<string, bool>> ValidateMultipleCodes(List<string> codes)
{
    using var client = new Ateco2025ApiClient("http://api:5000");
    var results = new Dictionary<string, bool>();

    var tasks = codes.Select(async code =>
    {
        try
        {
            var result = await client.GetByCodeAsync(code);
            return (code, isValid: result != null);
        }
        catch
        {
            return (code, isValid: false);
        }
    });

    var completed = await Task.WhenAll(tasks);

    foreach (var (code, isValid) in completed)
    {
        results[code] = isValid;
    }

    return results;
}

Get Complete Hierarchy Tree

public async Task<Ateco2025CodeHierarchy> GetCompleteTree(string rootCode)
{
    using var client = new Ateco2025ApiClient("http://api:5000", apiVersion: 2);

    var hierarchyResponse = await client.GetHierarchyWithStatsAsync(rootCode);

    Console.WriteLine($"Root: {hierarchyResponse.Parent?.Code}");
    Console.WriteLine($"Total descendants: {hierarchyResponse.Statistics?.TotalDescendants}");
    Console.WriteLine($"Max depth: {hierarchyResponse.Statistics?.MaxDepth}");

    return hierarchyResponse.Hierarchy;
}

📊 Response Types

ATECO 2025 Response Types

• GetAllResponse - Contains list of Ateco2025Code
• GetChildrenResponse - Parent code + children list
• GetHierarchyResponse - Hierarchical structure
• SearchResponse - Search results
• GetByLevelResponse - Codes by hierarchical level
• GetByCodeV2Response - V2 specific with children info
• PaginatedResponse - V2 paginated results
• SearchV2Response - V2 advanced search results
• GetHierarchyV2Response - V2 hierarchy with statistics

ATECO 2007 Response Types

• Ateco2007GetAllResponse - Contains list of Ateco2007Code
• Ateco2007GetChildrenResponse - Parent code + children list
• Ateco2007GetHierarchyResponse - Hierarchical structure
• Ateco2007SearchResponse - Search results
• Ateco2007GetByLevelResponse - Codes by hierarchical level
• Ateco2007GetByCodeV2Response - V2 specific with children info
• Ateco2007PaginatedResponse - V2 paginated results
• Ateco2007SearchV2Response - V2 advanced search results
• Ateco2007GetHierarchyV2Response - V2 hierarchy with statistics

✅ Compatibility

Compatible with:

• .NET Framework 4.6.2+
• .NET Core 2.0+
• .NET 5, 6, 7, 8, 9+
• Xamarin
• Unity 2021.1+

📚 Additional Resources

API Endpoints

ATECO 2025:

• Base URL: /api/v{version}/ateco2025
• V1: Basic CRUD operations
• V2: Enhanced with pagination, filters, and statistics

ATECO 2007:

• Base URL: /api/v{version}/ateco2007
• V1: Basic CRUD operations
• V2: Enhanced with pagination, filters, and statistics

Key Differences

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

For issues, questions, or contributions, please visit the GitHub repository.

Made with ❤️ for the Italian business community