feat(acl): diploma upload stored in the ZGW Documenten API (S-10b, closes #103) (#108)

## What & why

S-10b: the self-service **diploma upload** is now real. After submitting, the citizen picks a PDF and
uploads it; the portal base64-encodes it client-side → BFF → domain → **ACL**, which stores it in the
ZGW **Documenten (DRC) API** as an `enkelvoudiginformatieobject` and relates it to the zaak, then the
`WachtOpDocumenten` wait completes and the case advances to beoordeling. Per §8.1 only the ACL talks to
ZGW.

Closes #103

Mechanism in **ADR-0018** (proposal #107). Builds on S-10a (#102). The zaak-close-on-expiry item is
carved to **#106 (S-10c)**.

## Definition of Done

- [x] Linked Gitea issue (above).
- [x] Failing test committed before the implementation (red→green per layer).
- [x] Conventional Commits referencing the issue (`refs #103`).
- [ ] CI green — all Gitea Actions jobs (pending on this PR).
- [x] `docker compose up` health unaffected (ACL boots on a placeholder informatieobjecttype URL; the real one is injected by verify-domain).
- [x] Docs updated (ADR-0018, demo-script, BACKLOG + S-10c).
- [x] ADR added (`docs/architecture/adr-0018-diploma-upload-via-acl-documenten.md`).
- [x] Demo note in `docs/demo-script.md`.

## Notes for reviewers

- **ACL** (`OpenZaakGateway.StoreDocumentAsync` + `AclService.StoreDiplomaAsync` + `POST /documenten`) reuses the existing gateway patterns (ZGW Bearer, buffered non-chunked body, **no CRS** — Documenten isn't geo). Unit-tested via the stub handler; an **integration test** stores a real document against live OpenZaak (verify-acl).
- **Transport:** base64 JSON on every hop (portal encodes client-side) — I deviated from proposal #107's multipart to keep one contract shape and avoid `IFormFile`/antiforgery/multipart-client plumbing; fine at diploma size (ADR-0018 §Alternatives).
- **Infra:** `seed_catalogus.py` seeds + publishes a "Diploma" `informatieobjecttype` and relates it to the zaaktype (while both concept); `verify-domain` injects its URL into the ACL. No new ZGW scopes (seed applicatie has `heeft_alle_autorisaties`).
- **e2e:** uploads a real PDF (`setInputFiles`) after the openbaar INGEDIEND row confirms the zaak is open (so storage doesn't race the OpenZaak worker).
- **Scope boundary:** the ZGW zaak is not set to a cancellation status on 30-day expiry — that's #106 (S-10c).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: #108

services/acl/Acl.Api/Program.cs

@@ -40,6 +40,15 @@ app.MapPost("/zaken/reference", async (ZaakReferenceRequest body, AclService acl
     return Results.Ok(new { reference });
 });
 
+// Store an uploaded diploma against a zaak (S-10b): the domain sends the file as base64; the ACL
+// creates the ZGW enkelvoudiginformatieobject and relates it to the zaak (§8.1). Returns its URL.
+app.MapPost("/documenten", async (StoreDocumentRequest body, AclService acl, CancellationToken ct) =>
+{
+    var url = await acl.StoreDiplomaAsync(
+        new Uri(body.ZaakUrl), Convert.FromBase64String(body.ContentBase64), body.FileName, body.ContentType, ct);
+    return Results.Ok(new { informatieobjectUrl = url.ToString() });
+});
+
 app.Run();
 
 public sealed record OpenZaakRequest(string Bsn, string Reference);
@@ -48,4 +57,6 @@ public sealed record SetStatusRequest(string ZaakUrl);
 
 public sealed record ZaakReferenceRequest(string ZaakUrl);
 
+public sealed record StoreDocumentRequest(string ZaakUrl, string ContentBase64, string FileName, string ContentType);
+
 public partial class Program;

services/acl/Acl.Application/AclDefaults.cs

@@ -7,4 +7,8 @@ public sealed class AclDefaults
     public required string VerantwoordelijkeOrganisatie { get; init; }
     public required string Vertrouwelijkheidaanduiding { get; init; }
     public required Uri ZaaktypeUrl { get; init; }
+
+    /// <summary>The informatieobjecttype an uploaded diploma is filed under (S-10b). Seeded in the
+    /// catalogus and injected like <see cref="ZaaktypeUrl"/>.</summary>
+    public required Uri InformatieobjecttypeUrl { get; init; }
 }

services/acl/Acl.Application/AclService.cs

@@ -37,4 +37,33 @@ public sealed class AclService(IZaakGateway gateway, AclDefaults defaults, ICloc
 
         return gateway.GetZaakIdentificatieAsync(zaakUrl, ct);
     }
+
+    /// <summary>
+    /// Store an uploaded diploma against the zaak (S-10b): default-fill the ZGW-mandatory document
+    /// fields (informatieobjecttype, bronorganisatie, vertrouwelijkheidaanduiding, taal, creatiedatum)
+    /// and hand the file to the gateway, which creates the informatieobject and relates it to the zaak.
+    /// The domain supplies only the zaak, the bytes, and the file's name/type (§8.1).
+    /// </summary>
+    public Task<Uri> StoreDiplomaAsync(Uri zaakUrl, byte[] content, string fileName, string contentType, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(zaakUrl);
+        ArgumentNullException.ThrowIfNull(content);
+        ArgumentException.ThrowIfNullOrWhiteSpace(fileName);
+        ArgumentException.ThrowIfNullOrWhiteSpace(contentType);
+
+        var request = new DocumentRequest(
+            defaults.Bronorganisatie,
+            defaults.InformatieobjecttypeUrl,
+            defaults.Vertrouwelijkheidaanduiding,
+            zaakUrl,
+            clock.Today,
+            Titel: "Diploma",
+            Auteur: "zorgprofessional",
+            Taal: "nld",
+            Bestandsnaam: fileName,
+            Formaat: contentType,
+            Inhoud: content);
+
+        return gateway.StoreDocumentAsync(request, ct);
+    }
 }

services/acl/Acl.Application/DocumentRequest.cs

@@ -0,0 +1,17 @@
+namespace Acl.Application;
+
+/// <summary>The fully default-filled diploma document the gateway will create in the ZGW Documenten
+/// API and relate to the zaak (S-10b). <see cref="Inhoud"/> is the raw file content; the gateway
+/// base64-encodes it into the ZGW <c>inhoud</c> field.</summary>
+public sealed record DocumentRequest(
+    string Bronorganisatie,
+    Uri Informatieobjecttype,
+    string Vertrouwelijkheidaanduiding,
+    Uri Zaak,
+    DateOnly Creatiedatum,
+    string Titel,
+    string Auteur,
+    string Taal,
+    string Bestandsnaam,
+    string Formaat,
+    byte[] Inhoud);

services/acl/Acl.Application/IZaakGateway.cs

@@ -16,4 +16,11 @@ public interface IZaakGateway
     /// <summary>Read the zaak's <c>identificatie</c> — the public-safe reference the register shows.
     /// The Event Subscriber calls this through the ACL rather than reading ZGW itself (§8.1, #78).</summary>
     Task<string> GetZaakIdentificatieAsync(Uri zaakUrl, CancellationToken ct = default);
+
+    /// <summary>
+    /// Store a diploma document (S-10b): create an <c>enkelvoudiginformatieobject</c> in the ZGW
+    /// Documenten API and relate it to the zaak via a <c>zaakinformatieobject</c>. Returns the URL of
+    /// the created informatieobject.
+    /// </summary>
+    Task<Uri> StoreDocumentAsync(DocumentRequest request, CancellationToken ct = default);
 }

services/acl/Acl.Infrastructure/OpenZaakGateway.cs

@@ -80,6 +80,39 @@ public sealed class OpenZaakGateway(HttpClient http, OpenZaakOptions options) :
         return zaak.Identificatie;
     }
 
+    public async Task<Uri> StoreDocumentAsync(DocumentRequest request, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        // 1. Create the enkelvoudiginformatieobject in the Documenten API (not a geo API — no CRS).
+        var created = await PostForUrlAsync(
+            "/documenten/api/v1/enkelvoudiginformatieobjecten",
+            new EnkelvoudigInformatieobjectDto(
+                request.Bronorganisatie,
+                request.Creatiedatum.ToString("yyyy-MM-dd"),
+                request.Titel,
+                request.Auteur,
+                request.Taal,
+                request.Informatieobjecttype.ToString(),
+                Convert.ToBase64String(request.Inhoud),
+                request.Bestandsnaam,
+                request.Inhoud.Length,
+                request.Vertrouwelijkheidaanduiding,
+                request.Formaat,
+                "definitief",
+                // No usage-rights restrictions apply. Left null, OpenZaak rejects closing the related
+                // zaak with "indicatiegebruiksrecht-unset"; false records the deliberate "none" answer.
+                false),
+            "Creating the informatieobject", ct);
+
+        // 2. Relate it to the zaak (Zaken API — no CRS).
+        await PostAsync("/zaken/api/v1/zaakinformatieobjecten",
+            new ZaakInformatieobjectDto(request.Zaak.ToString(), created.ToString()),
+            "Relating the informatieobject to the zaak", ct);
+
+        return created;
+    }
+
     // POSTs a non-geo ZGW resource (resultaat/status — no CRS headers). Buffers the body so uwsgi gets
     // a Content-Length instead of a chunked body (as with zaak-create).
     private async Task PostAsync(string path, object dto, string action, CancellationToken ct)
@@ -96,6 +129,26 @@ public sealed class OpenZaakGateway(HttpClient http, OpenZaakOptions options) :
         await EnsureSuccessAsync(response, action, ct);
     }
 
+    // POSTs a non-geo ZGW resource and returns the created resource's URL (as PostAsync, but reads back
+    // the `url` of the created object). Buffers the body so uwsgi gets a Content-Length.
+    private async Task<Uri> PostForUrlAsync(string path, object dto, string action, CancellationToken ct)
+    {
+        using var message = new HttpRequestMessage(HttpMethod.Post, new Uri(options.BaseUrl, path))
+        {
+            Content = JsonContent.Create(dto),
+        };
+        message.Headers.Authorization =
+            new AuthenticationHeaderValue("Bearer", ZgwToken.Mint(options.ClientId, options.Secret));
+        await message.Content.LoadIntoBufferAsync(ct);
+
+        using var response = await http.SendAsync(message, ct);
+        await EnsureSuccessAsync(response, action, ct);
+
+        var created = await response.Content.ReadFromJsonAsync<CreatedDto>(ct)
+            ?? throw new InvalidOperationException($"OpenZaak returned an empty response for {action}");
+        return new Uri(created.Url);
+    }
+
     // EnsureSuccessStatusCode discards the response body; ZGW returns a JSON problem detail on 400 that
     // is essential for diagnosing a rejected request, so surface it in the exception.
     private static async Task EnsureSuccessAsync(HttpResponseMessage response, string action, CancellationToken ct)
@@ -182,4 +235,26 @@ public sealed class OpenZaakGateway(HttpClient http, OpenZaakOptions options) :
 
     private sealed record ResultaattypeDto(
         [property: JsonPropertyName("url")] string Url);
+
+    private sealed record CreatedDto(
+        [property: JsonPropertyName("url")] string Url);
+
+    private sealed record EnkelvoudigInformatieobjectDto(
+        [property: JsonPropertyName("bronorganisatie")] string Bronorganisatie,
+        [property: JsonPropertyName("creatiedatum")] string Creatiedatum,
+        [property: JsonPropertyName("titel")] string Titel,
+        [property: JsonPropertyName("auteur")] string Auteur,
+        [property: JsonPropertyName("taal")] string Taal,
+        [property: JsonPropertyName("informatieobjecttype")] string Informatieobjecttype,
+        [property: JsonPropertyName("inhoud")] string Inhoud,
+        [property: JsonPropertyName("bestandsnaam")] string Bestandsnaam,
+        [property: JsonPropertyName("bestandsomvang")] int Bestandsomvang,
+        [property: JsonPropertyName("vertrouwelijkheidaanduiding")] string Vertrouwelijkheidaanduiding,
+        [property: JsonPropertyName("formaat")] string Formaat,
+        [property: JsonPropertyName("status")] string Status,
+        [property: JsonPropertyName("indicatieGebruiksrecht")] bool IndicatieGebruiksrecht);
+
+    private sealed record ZaakInformatieobjectDto(
+        [property: JsonPropertyName("zaak")] string Zaak,
+        [property: JsonPropertyName("informatieobject")] string Informatieobject);
 }

services/acl/Acl.IntegrationTests/OpenZaakFixture.cs

@@ -77,6 +77,18 @@ public sealed class OpenZaakFixture : IDisposable
         return JsonDocument.Parse(json).RootElement.Clone();
     }
 
+    /// <summary>The URL of the published "Diploma" informatieobjecttype (S-10b), or null when the
+    /// stack has not been seeded with OZ_PUBLISH=1. `status=definitief` returns published types only.</summary>
+    public async Task<Uri?> FindPublishedDiplomaInformatieobjecttypeAsync(CancellationToken ct = default)
+    {
+        var query = new Uri(BaseUrl, "/catalogi/api/v1/informatieobjecttypen?status=definitief");
+        var page = await GetJsonAsync(query, ct);
+        foreach (var iot in page.GetProperty("results").EnumerateArray())
+            if (iot.TryGetProperty("omschrijving", out var o) && o.GetString() == "Diploma")
+                return new Uri(iot.GetProperty("url").GetString()!);
+        return null;
+    }
+
     /// <summary>The zaaktype's eindstatus (terminal statustype) URL — the one an approval sets.</summary>
     public async Task<Uri> FindEindstatustypeAsync(Uri zaaktypeUrl, CancellationToken ct = default)
     {

services/acl/Acl.IntegrationTests/OpenZaakGatewayIntegrationTests.cs

@@ -74,4 +74,58 @@ public sealed class OpenZaakGatewayIntegrationTests(OpenZaakFixture stack)
         var eindstatustype = await stack.FindEindstatustypeAsync(zaaktype!);
         Assert.Equal(eindstatustype.ToString(), status.GetProperty("statustype").GetString());
     }
+
+    [Fact]
+    public async Task Storing_a_diploma_creates_a_real_informatieobject_related_to_the_zaak()
+    {
+        var zaaktype = await stack.FindPublishedBigZaaktypeAsync();
+        Assert.True(zaaktype is not null,
+            "No published BIG-REGISTRATIE zaaktype found — seed the stack with OZ_PUBLISH=1.");
+        var informatieobjecttype = await stack.FindPublishedDiplomaInformatieobjecttypeAsync();
+        Assert.True(informatieobjecttype is not null,
+            "No published Diploma informatieobjecttype found — seed the stack with OZ_PUBLISH=1.");
+
+        var gateway = new OpenZaakGateway(stack.Http, stack.Options);
+        var zaakUrl = await gateway.OpenZaakAsync(new ZaakRequest(
+            Bronorganisatie: "517439943",
+            VerantwoordelijkeOrganisatie: "517439943",
+            Vertrouwelijkheidaanduiding: "openbaar",
+            Zaaktype: zaaktype!,
+            Startdatum: DateOnly.FromDateTime(DateTime.UtcNow),
+            Identificatie: Guid.NewGuid().ToString()));
+
+        var content = System.Text.Encoding.UTF8.GetBytes("%PDF-1.4 synthetic diploma\n");
+        var documentUrl = await gateway.StoreDocumentAsync(new DocumentRequest(
+            Bronorganisatie: "517439943",
+            Informatieobjecttype: informatieobjecttype!,
+            Vertrouwelijkheidaanduiding: "openbaar",
+            Zaak: zaakUrl,
+            Creatiedatum: DateOnly.FromDateTime(DateTime.UtcNow),
+            Titel: "Diploma",
+            Auteur: "zorgprofessional",
+            Taal: "nld",
+            Bestandsnaam: "diploma.pdf",
+            Formaat: "application/pdf",
+            Inhoud: content));
+
+        // The gateway returns the canonical informatieobject URL...
+        Assert.StartsWith(
+            new Uri(stack.BaseUrl, "/documenten/api/v1/enkelvoudiginformatieobjecten/").ToString(),
+            documentUrl.ToString());
+
+        // ...the document is really persisted with the default-filled fields...
+        var doc = await stack.GetJsonAsync(documentUrl);
+        Assert.Equal("diploma.pdf", doc.GetProperty("bestandsnaam").GetString());
+        Assert.Equal(informatieobjecttype.ToString(), doc.GetProperty("informatieobjecttype").GetString());
+        Assert.Equal(content.Length, doc.GetProperty("bestandsomvang").GetInt32());
+        // indicatieGebruiksrecht is recorded as "no restrictions"; left null, OpenZaak would refuse to
+        // close the zaak this document is related to (the S-10b regression that broke the e2e flow).
+        Assert.False(doc.GetProperty("indicatieGebruiksrecht").GetBoolean());
+
+        // ...and it is related to the zaak (a zaakinformatieobject links the two).
+        var relations = await stack.GetJsonAsync(new Uri(stack.BaseUrl,
+            "/zaken/api/v1/zaakinformatieobjecten?informatieobject=" + Uri.EscapeDataString(documentUrl.ToString())));
+        Assert.Contains(relations.EnumerateArray(),
+            r => r.GetProperty("zaak").GetString() == zaakUrl.ToString());
+    }
 }

services/acl/Acl.Tests/AclServiceTests.cs

@@ -30,6 +30,15 @@ public class AclServiceTests
             ReadReferenceFor = zaakUrl;
             return Task.FromResult("REG-FROM-ZAAK");
         }
+
+        public DocumentRequest? StoredDocument;
+        public Uri DocumentResult { get; } = new("http://openzaak/documenten/api/v1/enkelvoudiginformatieobjecten/doc-1");
+
+        public Task<Uri> StoreDocumentAsync(DocumentRequest request, CancellationToken ct = default)
+        {
+            StoredDocument = request;
+            return Task.FromResult(DocumentResult);
+        }
     }
 
     private static AclDefaults Defaults() => new()
@@ -38,6 +47,7 @@ public class AclServiceTests
         VerantwoordelijkeOrganisatie = "517439943",
         Vertrouwelijkheidaanduiding = "openbaar",
         ZaaktypeUrl = new("http://openzaak/catalogi/api/v1/zaaktypen/big"),
+        InformatieobjecttypeUrl = new("http://openzaak/catalogi/api/v1/informatieobjecttypen/dip"),
     };
 
     private sealed class FixedClock(DateOnly today) : IClock
@@ -55,6 +65,7 @@ public class AclServiceTests
             VerantwoordelijkeOrganisatie = "517439943",
             Vertrouwelijkheidaanduiding = "openbaar",
             ZaaktypeUrl = new("http://openzaak/catalogi/api/v1/zaaktypen/big"),
+            InformatieobjecttypeUrl = new("http://openzaak/catalogi/api/v1/informatieobjecttypen/dip"),
         };
         var service = new AclService(gateway, defaults, new FixedClock(new DateOnly(2026, 6, 4)));
 
@@ -81,6 +92,7 @@ public class AclServiceTests
             VerantwoordelijkeOrganisatie = "517439943",
             Vertrouwelijkheidaanduiding = "openbaar",
             ZaaktypeUrl = new("http://openzaak/catalogi/api/v1/zaaktypen/big"),
+            InformatieobjecttypeUrl = new("http://openzaak/catalogi/api/v1/informatieobjecttypen/dip"),
         };
         var service = new AclService(gateway, defaults, new FixedClock(new DateOnly(2026, 6, 4)));
 
@@ -114,6 +126,41 @@ public class AclServiceTests
         Assert.Null(gateway.Approved);
     }
 
+    [Fact]
+    public async Task Storing_a_diploma_default_fills_the_document_fields_and_returns_its_url()
+    {
+        var gateway = new FakeGateway();
+        var defaults = Defaults();
+        var service = new AclService(gateway, defaults, new FixedClock(new DateOnly(2026, 6, 4)));
+        var zaak = new Uri("http://openzaak/zaken/api/v1/zaken/abc");
+
+        var url = await service.StoreDiplomaAsync(zaak, [1, 2, 3], "diploma.pdf", "application/pdf");
+
+        Assert.Equal(gateway.DocumentResult, url);
+        var req = gateway.StoredDocument!;
+        Assert.Equal(zaak, req.Zaak);
+        Assert.Equal(defaults.InformatieobjecttypeUrl, req.Informatieobjecttype);
+        Assert.Equal("517439943", req.Bronorganisatie);
+        Assert.Equal("openbaar", req.Vertrouwelijkheidaanduiding);
+        Assert.Equal(new DateOnly(2026, 6, 4), req.Creatiedatum);
+        Assert.Equal("nld", req.Taal);
+        Assert.Equal("diploma.pdf", req.Bestandsnaam);
+        Assert.Equal("application/pdf", req.Formaat);
+        Assert.Equal(new byte[] { 1, 2, 3 }, req.Inhoud);
+    }
+
+    [Fact]
+    public async Task Storing_a_diploma_rejects_null_or_blank_arguments()
+    {
+        var service = new AclService(new FakeGateway(), Defaults(), new FixedClock(new DateOnly(2026, 6, 4)));
+        var zaak = new Uri("http://openzaak/zaken/api/v1/zaken/abc");
+
+        await Assert.ThrowsAsync<ArgumentNullException>(() => service.StoreDiplomaAsync(null!, [1], "d.pdf", "application/pdf"));
+        await Assert.ThrowsAsync<ArgumentNullException>(() => service.StoreDiplomaAsync(zaak, null!, "d.pdf", "application/pdf"));
+        await Assert.ThrowsAnyAsync<ArgumentException>(() => service.StoreDiplomaAsync(zaak, [1], " ", "application/pdf"));
+        await Assert.ThrowsAnyAsync<ArgumentException>(() => service.StoreDiplomaAsync(zaak, [1], "d.pdf", " "));
+    }
+
     [Fact]
     public async Task Reading_a_zaak_reference_returns_the_zaaks_identificatie()
     {

services/acl/Acl.Tests/OpenZaakGatewayTests.cs

@@ -432,4 +432,114 @@ public class OpenZaakGatewayTests
         b64 = (b64.Length % 4) switch { 2 => b64 + "==", 3 => b64 + "=", _ => b64 };
         return Encoding.UTF8.GetString(Convert.FromBase64String(b64));
     }
+
+    // --- StoreDocumentAsync (diploma upload / S-10b) ---
+
+    private static readonly Uri Informatieobjecttype =
+        new("http://openzaak/catalogi/api/v1/informatieobjecttypen/dip");
+
+    private static DocumentRequest SampleDocument(byte[]? inhoud = null) => new(
+        Bronorganisatie: "517439943",
+        Informatieobjecttype: Informatieobjecttype,
+        Vertrouwelijkheidaanduiding: "openbaar",
+        Zaak: new Uri(ZaakUrl),
+        Creatiedatum: new DateOnly(2026, 6, 4),
+        Titel: "Diploma",
+        Auteur: "zorgprofessional",
+        Taal: "nld",
+        Bestandsnaam: "diploma.pdf",
+        Formaat: "application/pdf",
+        Inhoud: inhoud ?? [1, 2, 3, 4]);
+
+    // Routes the two document calls: POST /enkelvoudiginformatieobjecten (documenten) then
+    // POST /zaakinformatieobjecten (zaken).
+    private static StubHandler DocumentStub(Recorder rec) => new(async req =>
+    {
+        rec.Requests.Add(req);
+        rec.ContentLengths.Add(req.Content?.Headers.ContentLength);
+        rec.Bodies.Add(req.Content is null ? null : await req.Content.ReadAsStringAsync());
+
+        return req.RequestUri!.ToString().Contains("/enkelvoudiginformatieobjecten")
+            ? Json(HttpStatusCode.Created, """{"url":"http://openzaak/documenten/api/v1/enkelvoudiginformatieobjecten/doc-1"}""")
+            : Json(HttpStatusCode.Created, """{"url":"http://openzaak/zaken/api/v1/zaakinformatieobjecten/rel-1"}""");
+    });
+
+    [Fact]
+    public async Task Storing_a_document_creates_the_informatieobject_then_relates_it_to_the_zaak()
+    {
+        var rec = new Recorder();
+
+        var url = await Gateway(DocumentStub(rec)).StoreDocumentAsync(SampleDocument([10, 20, 30]));
+
+        Assert.Equal("http://openzaak/documenten/api/v1/enkelvoudiginformatieobjecten/doc-1", url.ToString());
+
+        // 1. Create the enkelvoudiginformatieobject in the Documenten API.
+        var create = rec.Sent("/enkelvoudiginformatieobjecten");
+        Assert.Equal(HttpMethod.Post, create.Request.Method);
+        Assert.Equal("http://openzaak/documenten/api/v1/enkelvoudiginformatieobjecten",
+            create.Request.RequestUri!.ToString());
+        Assert.Equal("Bearer", create.Request.Headers.Authorization!.Scheme);
+        Assert.Contains("\"bronorganisatie\":\"517439943\"", create.Body);
+        Assert.Contains("\"informatieobjecttype\":\"http://openzaak/catalogi/api/v1/informatieobjecttypen/dip\"", create.Body);
+        Assert.Contains("\"creatiedatum\":\"2026-06-04\"", create.Body);
+        Assert.Contains("\"titel\":\"Diploma\"", create.Body);
+        Assert.Contains("\"auteur\":\"zorgprofessional\"", create.Body);
+        Assert.Contains("\"taal\":\"nld\"", create.Body);
+        Assert.Contains("\"bestandsnaam\":\"diploma.pdf\"", create.Body);
+        Assert.Contains("\"formaat\":\"application/pdf\"", create.Body);
+        Assert.Contains("\"vertrouwelijkheidaanduiding\":\"openbaar\"", create.Body);
+        Assert.Contains("\"status\":\"definitief\"", create.Body);
+        // indicatieGebruiksrecht must be set explicitly (false = no usage restrictions); left null,
+        // OpenZaak refuses to close the zaak this document is related to ("indicatiegebruiksrecht-unset").
+        Assert.Contains("\"indicatieGebruiksrecht\":false", create.Body);
+        // The file content is base64-encoded into `inhoud`, with its byte length in `bestandsomvang`.
+        Assert.Contains($"\"inhoud\":\"{Convert.ToBase64String([10, 20, 30])}\"", create.Body);
+        Assert.Contains("\"bestandsomvang\":3", create.Body);
+
+        // 2. Relate that informatieobject to the zaak (Zaken API — no CRS).
+        var relate = rec.Sent("/zaakinformatieobjecten");
+        Assert.Equal(HttpMethod.Post, relate.Request.Method);
+        Assert.Equal("http://openzaak/zaken/api/v1/zaakinformatieobjecten",
+            relate.Request.RequestUri!.ToString());
+        Assert.Contains($"\"zaak\":\"{ZaakUrl}\"", relate.Body);
+        Assert.Contains("\"informatieobject\":\"http://openzaak/documenten/api/v1/enkelvoudiginformatieobjecten/doc-1\"", relate.Body);
+    }
+
+    [Fact]
+    public async Task Storing_a_document_buffers_the_body_and_sends_no_crs_headers()
+    {
+        // uwsgi rejects a chunked body (Content-Length must be present); the Documenten API is not a
+        // geo API, so no CRS headers (unlike the Zaken zaak-create).
+        var rec = new Recorder();
+
+        await Gateway(DocumentStub(rec)).StoreDocumentAsync(SampleDocument());
+
+        var create = rec.Sent("/enkelvoudiginformatieobjecten");
+        Assert.NotNull(create.Length);
+        Assert.True(create.Length > 0);
+        Assert.False(create.Request.Headers.Contains("Accept-Crs"));
+        Assert.False(create.Request.Content!.Headers.Contains("Content-Crs"));
+    }
+
+    [Fact]
+    public async Task Storing_a_document_surfaces_an_openzaak_rejection()
+    {
+        var handler = new StubHandler(_ =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.BadRequest)
+            {
+                Content = new StringContent("""{"detail":"bad"}""", Encoding.UTF8, "application/json"),
+            }));
+
+        var ex = await Assert.ThrowsAsync<HttpRequestException>(
+            () => Gateway(handler).StoreDocumentAsync(SampleDocument()));
+        Assert.Contains("bad", ex.Message);
+    }
+
+    [Fact]
+    public async Task Storing_a_document_rejects_a_null_request()
+    {
+        var handler = new StubHandler(_ => throw new InvalidOperationException("should not be sent"));
+
+        await Assert.ThrowsAsync<ArgumentNullException>(() => Gateway(handler).StoreDocumentAsync(null!));
+    }
 }