.NET

dotnet new web -n ConstaiaDemo
cd ConstaiaDemo

dotnet user-secrets init
dotnet user-secrets set CONSTAIA_API_KEY ck_test_...
dotnet user-secrets set CONSTAIA_WEBHOOK_SECRET whsec_...

using System.Text.Json;

namespace ConstaiaDemo.Constaia;

public sealed record Analysis(
    string Id,
    string Status,
    bool Livemode,
    DateTimeOffset? CreatedAt,
    DocumentInfo? Document,
    Verdict? Verdict,
    Dictionary<string, Field>? Fields,
    List<string>? Warnings,
    AnalysisError? Error,
    Dictionary<string, string>? Metadata);

public sealed record DocumentInfo(string Type, string? Label, double Confidence);

public sealed record Verdict(List<string> Expected, bool Match, string Status, List<Reason> Reasons);

public sealed record Reason(string Code, string Severity, string Message);

public sealed record Field(JsonElement Value, double? Confidence, bool? Validated);

public sealed record AnalysisError(string Code, string? Message);

public sealed record AnalyzeOptions(
    string[] Expect,
    Checks? Checks = null,
    string? Storage = null,
    bool? Async = null,
    string? Language = null,
    Dictionary<string, string>? Metadata = null);

public sealed record Checks(bool? NotExpired = null, Holder? Holder = null);

public sealed record Holder(string? FullName = null);

public sealed record ApiError(string? Type, string? Code, string? Message, string? Param, string? RequestId);

public sealed record ErrorEnvelope(ApiError? Error);

public sealed record WebhookEvent(string Type, DateTimeOffset? CreatedAt, JsonElement Data);

using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace ConstaiaDemo.Constaia;

public sealed class ConstaiaException(
    int status, string? type, string? code, string message, string? param, string? requestId, TimeSpan retryAfter)
    : Exception(message)
{
    public int Status { get; } = status;
    public string? Type { get; } = type;
    public string? Code { get; } = code;
    public string? Param { get; } = param;
    public string? RequestId { get; } = requestId;
    public TimeSpan RetryAfter { get; } = retryAfter;
}

public sealed class ConstaiaClient(HttpClient http)
{
    private const int MaxRetries = 2;

    public static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web)
    {
        PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    };

    /// <summary>Status "completed" (HTTP 200) or "queued"/"processing" (HTTP 202).</summary>
    public async Task<Analysis> AnalyzeAsync(
        Stream file, string fileName, string? contentType, AnalyzeOptions options, CancellationToken ct = default)
    {
        using var buffer = new MemoryStream();
        await file.CopyToAsync(buffer, ct);
        var bytes = buffer.ToArray();
        var optionsJson = JsonSerializer.Serialize(options, Json);
        var idempotencyKey = Guid.NewGuid().ToString();
        var safeName = fileName.Replace("\"", "");

        for (var attempt = 0; ; attempt++)
        {
            using var form = new MultipartFormDataContent();
            var filePart = new StreamContent(new MemoryStream(bytes));
            if (MediaTypeHeaderValue.TryParse(contentType, out var mediaType))
                filePart.Headers.ContentType = mediaType;
            filePart.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
            {
                Name = "\"file\"",
                FileName = $"\"{safeName}\"",
            };
            form.Add(filePart);
            form.Add(new StringContent(optionsJson, Encoding.UTF8), "\"options\"");

            using var request = new HttpRequestMessage(HttpMethod.Post, "v1/analyze") { Content = form };
            request.Headers.Add("Idempotency-Key", idempotencyKey);

            using var response = await http.SendAsync(request, ct);
            if (response.IsSuccessStatusCode)
                return (await response.Content.ReadFromJsonAsync<Analysis>(Json, ct))!;

            var error = await ToExceptionAsync(response, ct);
            if (response.StatusCode == HttpStatusCode.TooManyRequests && attempt < MaxRetries)
            {
                await Task.Delay(error.RetryAfter, ct);
                continue;
            }
            throw error;
        }
    }

    public async Task<Analysis> GetAnalysisAsync(string id, CancellationToken ct = default)
    {
        using var response = await http.GetAsync($"v1/analyses/{Uri.EscapeDataString(id)}", ct);
        if (!response.IsSuccessStatusCode) throw await ToExceptionAsync(response, ct);
        return (await response.Content.ReadFromJsonAsync<Analysis>(Json, ct))!;
    }

    private static async Task<ConstaiaException> ToExceptionAsync(HttpResponseMessage response, CancellationToken ct)
    {
        ApiError? error = null;
        try
        {
            error = (await response.Content.ReadFromJsonAsync<ErrorEnvelope>(Json, ct))?.Error;
        }
        catch (Exception e) when (e is JsonException or NotSupportedException)
        {
            // Empty or non-JSON body (for example, an intermediate proxy).
        }

        var requestId = error?.RequestId
            ?? (response.Headers.TryGetValues("X-Request-Id", out var values) ? values.FirstOrDefault() : null);
        var status = (int)response.StatusCode;
        return new ConstaiaException(
            status,
            error?.Type,
            error?.Code,
            error?.Message ?? $"HTTP {status}",
            error?.Param,
            requestId,
            response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(1));
    }
}

using System.Security.Cryptography;
using System.Text;

namespace ConstaiaDemo.Constaia;

public static class ConstaiaWebhook
{
    public static bool Verify(
        string secret, string? id, string? timestamp, string? signatures, string body, int toleranceSeconds = 300)
    {
        if (string.IsNullOrEmpty(id) || string.IsNullOrEmpty(timestamp) || string.IsNullOrEmpty(signatures))
            return false;
        if (!long.TryParse(timestamp, out var ts)
            || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > toleranceSeconds)
            return false;

        var key = Convert.FromBase64String(
            secret.StartsWith("whsec_", StringComparison.Ordinal) ? secret["whsec_".Length..] : secret);
        var expected = HMACSHA256.HashData(key, Encoding.UTF8.GetBytes($"{id}.{timestamp}.{body}"));

        foreach (var part in signatures.Split(' ', StringSplitOptions.RemoveEmptyEntries))
        {
            var comma = part.IndexOf(',');
            if (comma < 0 || part[..comma] != "v1") continue;
            try
            {
                if (CryptographicOperations.FixedTimeEquals(Convert.FromBase64String(part[(comma + 1)..]), expected))
                    return true;
            }
            catch (FormatException)
            {
            }
        }
        return false;
    }
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using ConstaiaDemo.Constaia;
using Microsoft.AspNetCore.Http.Features;
using Microsoft.AspNetCore.Mvc;

const long MaxBytes = 20 * 1024 * 1024;

var builder = WebApplication.CreateBuilder(args);

var apiKey = builder.Configuration["CONSTAIA_API_KEY"]
    ?? throw new InvalidOperationException("CONSTAIA_API_KEY is missing");

builder.Services.AddHttpClient<ConstaiaClient>(client =>
{
    client.BaseAddress = new Uri("https://api.constaia.com/");
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
    // A synchronous analysis can take up to 30 s before returning 202.
    client.Timeout = TimeSpan.FromSeconds(60);
});

builder.WebHost.ConfigureKestrel(o => o.Limits.MaxRequestBodySize = MaxBytes + 1024 * 1024);
builder.Services.Configure<FormOptions>(o => o.MultipartBodyLengthLimit = MaxBytes + 1024 * 1024);

var app = builder.Build();

// Add your authentication here: every analysis spends credits.
app.MapPost("/api/verify", async (
    IFormFile file,
    [FromForm(Name = "full_name")] string? fullName,
    ConstaiaClient constaia,
    ILogger<Program> logger,
    CancellationToken ct) =>
{
    if (file.Length == 0)
        return Results.Json(new { error = new { message = "The document is missing." } }, statusCode: 400);
    if (file.Length > MaxBytes)
        return Results.Json(new { error = new { message = "Max 20 MB." } }, statusCode: 413);

    var options = new AnalyzeOptions(
        Expect: ["es_dni"],
        Checks: new Checks(
            NotExpired: true,
            Holder: string.IsNullOrWhiteSpace(fullName) ? null : new Holder(fullName)),
        Storage: "none",
        Language: "en");

    try
    {
        await using var stream = file.OpenReadStream();
        var analysis = await constaia.AnalyzeAsync(stream, file.FileName, file.ContentType, options, ct);

        if (analysis.Status != "completed")
            // 202: the result will arrive by webhook (or call GetAnalysisAsync).
            return Results.Accepted(value: new { id = analysis.Id, status = analysis.Status });

        return Results.Ok(new
        {
            id = analysis.Id,
            status = analysis.Verdict?.Status,
            reasons = analysis.Verdict?.Reasons.Select(r => r.Message) ?? [],
            warnings = analysis.Warnings,
        });
    }
    catch (ConstaiaException e)
    {
        logger.LogWarning("Constaia {Status} {Code} request_id={RequestId}", e.Status, e.Code, e.RequestId);
        return e.Type == "invalid_request"
            ? Results.Json(new { error = new { message = e.Message } }, statusCode: 422)
            : Results.Json(new { error = new { message = "The document could not be verified. Please try again." } }, statusCode: 502);
    }
}).DisableAntiforgery(); // Token-authenticated API; with cookies, use AddAntiforgery/UseAntiforgery.

app.MapPost("/webhooks/constaia", async (HttpRequest request, IConfiguration config, ILogger<Program> logger) =>
{
    using var reader = new StreamReader(request.Body, Encoding.UTF8);
    var raw = await reader.ReadToEndAsync();

    var secret = config["CONSTAIA_WEBHOOK_SECRET"]
        ?? throw new InvalidOperationException("CONSTAIA_WEBHOOK_SECRET is missing");
    var h = request.Headers;
    if (!ConstaiaWebhook.Verify(secret, h["webhook-id"], h["webhook-timestamp"], h["webhook-signature"], raw))
        return Results.BadRequest();

    var evt = JsonSerializer.Deserialize<WebhookEvent>(raw, ConstaiaClient.Json)!;
    // webhook-id is stable across retries: dedupe on it in your database.
    switch (evt.Type)
    {
        case "analysis.completed" or "analysis.review_required" or "analysis.failed":
        {
            var analysis = evt.Data.Deserialize<Analysis>(ConstaiaClient.Json)!;
            logger.LogInformation("{MessageId} {Type} {AnalysisId} {Verdict}",
                h["webhook-id"].ToString(), evt.Type, analysis.Id, analysis.Verdict?.Status);
            // Queue heavy work (Channel, BackgroundService…) and answer within 15 s.
            break;
        }
        // batch.completed, credits.low, test…
    }
    return Results.NoContent();
});

app.Run();

dotnet run

curl -F "file=@dni_valid.jpg" -F "full_name=María García López" http://localhost:5000/api/verify
curl -F "file=@dni_expired.jpg" http://localhost:5000/api/verify
curl -F "file=@blurry.jpg" http://localhost:5000/api/verify
curl -F "file=@dni_valid.jpg" -F "full_name=Juan Pérez" http://localhost:5000/api/verify