Falco.Api 1.0.4

📄 README.md — Falco.Api SDK for .NET

# Falco.Api (.NET SDK)

Falco.Api is the official .NET client library for interacting with the **Falco API**, allowing developers to import PDF and UBL documents, validate UBL against Peppol BIS 3.0 rules, and prepare for future modules such as Peppol sending, billing, document management, and more.

The SDK is designed to be:
- Easy to plug into ASP.NET Core using Dependency Injection  
- Fully compatible with `IHttpClientFactory`  
- Environment-aware (`Production` or `Sandbox`)  
- Versioned (`v1` by default)  
- Flexible (supports multiple API keys)  
- Typed and testable

---

## 🚀 Installation

Install via NuGet:

```bash
dotnet add package Falco.Api

Or using the Package Manager Console:

Install-Package Falco.Api

🧭 Quick Start

1. Register the client in your Program.cs

using Falco.Api;
using Falco.Api.Extensions;

builder.Services.AddFalcoClient(options =>
{
    options.Environment = FalcoEnvironment.Sandbox; // or Production
    options.Version = FalcoApiVersion.V1;
    options.AppSecret = builder.Configuration["Falco:AppSecret"];
    
    // ApiKey is optional and can be overridden per request
    // options.ApiKey = builder.Configuration["Falco:ApiKey"];
});

2. Inject and use FalcoClient

public class ImportService
{
    private readonly FalcoClient _falco;

    public ImportService(FalcoClient falco)
    {
        _falco = falco;
    }

    public async Task<DocumentImportResponse> ImportPdfAsync(byte[] pdfBytes)
    {
        var metadata = new PdfImportMetadata
        {
            DocumentType = "sale_invoice",
            DocumentDate = DateOnly.FromDateTime(DateTime.Today),
            Sender = new PartyMetadata
            {
                Name = "ACME Corp",
                VatNumber = "BE0123456789",
                Address = new PartyAddress
                {
                    Line1 = "Main Street 1",
                    Zip = "1000",
                    City = "Brussels",
                    Country = "BE"
                }
            }
        };

        return await _falco.Imports.ImportPdfAsync(
            pdfBytes,
            "invoice.pdf",
            metadata
        );
    }
}

📥 Importing a PDF

var response = await falco.Imports.ImportPdfAsync(
    pdfBytes,
    "invoice.pdf",
    new PdfImportMetadata
    {
        DocumentType = "sale_invoice",
        DocumentDate = DateOnly.FromDateTime(DateTime.Today),
        SendPeppol = true,
        SendAccounting = true
    }
);

Response example:

{
  "document_id": "doc_123",
  "peppol_status": {
    "status": "submitted",
    "peppol_identifier": "..."
  },
  "accounting_status": {
    "status": "submitted"
  }
}

📤 Importing a UBL

var response = await falco.Imports.ImportUblAsync(
    ublXmlBytes,
    "invoice.xml",
    new UblImportMetadata
    {
        SendPeppol = true,
        SendAccounting = true
    }
);

🧪 Validating a UBL

var validation = await falco.Imports.ValidateUblAsync(ublXmlBytes);

if (validation.Status == "failure")
{
    foreach (var msg in validation.Messages)
    {
        Console.WriteLine($"{msg.Level}: {msg.Description}");
    }
}

🔐 Authentication Model

Every request to Falco uses:

You can override the API key per request:

await falco.Imports.ImportPdfAsync(
    pdfBytes,
    "invoice.pdf",
    metadata,
    apiKeyOverride: clientApiKey
);

🌍 Environments

The SDK automatically selects the correct API base URL:

Configured via:

options.Environment = FalcoEnvironment.Sandbox; // (Production by default)

🧩 API Versioning

The API version is included in the base URL.

options.Version = FalcoApiVersion.V1;

Future versions like V2 will be supported transparently.

⚠️ Error Handling

All non-successful HTTP responses throw FalcoApiException.

try
{
    await falco.Imports.ImportPdfAsync(...);
}
catch (FalcoApiException ex)
{
    Console.WriteLine(ex.StatusCode);
    Console.WriteLine(ex.Problem?.Detail);
}

The exception includes:

• HTTP status code
• Parsed RFC 9457 ProblemDetails
• Raw response body

📄 License

MIT License © Horus Software SA