@stamhoofd/backend 2.132.1 → 2.133.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stamhoofd/backend",
-    "version": "2.132.1",
+    "version": "2.133.0",
     "type": "module",
     "main": "./dist/index.js",
     "exports": {
@@ -57,20 +57,20 @@
         "@simonbackx/simple-endpoints": "1.21.1",
         "@simonbackx/simple-errors": "1.5.0",
         "@simonbackx/simple-logging": "1.0.1",
-        "@stamhoofd/backend-env": "2.132.1",
-        "@stamhoofd/backend-i18n": "2.132.1",
-        "@stamhoofd/backend-middleware": "2.132.1",
-        "@stamhoofd/crons": "2.132.1",
-        "@stamhoofd/email": "2.132.1",
-        "@stamhoofd/excel-writer": "2.132.1",
-        "@stamhoofd/logging": "2.132.1",
-        "@stamhoofd/models": "2.132.1",
-        "@stamhoofd/object-differ": "2.132.1",
-        "@stamhoofd/queues": "2.132.1",
-        "@stamhoofd/sql": "2.132.1",
-        "@stamhoofd/structures": "2.132.1",
-        "@stamhoofd/types": "2.132.1",
-        "@stamhoofd/utility": "2.132.1",
+        "@stamhoofd/backend-env": "2.133.0",
+        "@stamhoofd/backend-i18n": "2.133.0",
+        "@stamhoofd/backend-middleware": "2.133.0",
+        "@stamhoofd/crons": "2.133.0",
+        "@stamhoofd/email": "2.133.0",
+        "@stamhoofd/excel-writer": "2.133.0",
+        "@stamhoofd/logging": "2.133.0",
+        "@stamhoofd/models": "2.133.0",
+        "@stamhoofd/object-differ": "2.133.0",
+        "@stamhoofd/queues": "2.133.0",
+        "@stamhoofd/sql": "2.133.0",
+        "@stamhoofd/structures": "2.133.0",
+        "@stamhoofd/types": "2.133.0",
+        "@stamhoofd/utility": "2.133.0",
         "archiver": "7.0.1",
         "axios": "1.16.0",
         "base-x": "3.0.11",
@@ -91,7 +91,7 @@
         "stripe": "16.12.0"
     },
     "devDependencies": {
-        "@stamhoofd/test-utils": "2.132.1",
+        "@stamhoofd/test-utils": "2.133.0",
         "@types/cookie": "0.6.0",
         "@types/luxon": "3.7.1",
         "@types/mailparser": "3.4.6",
@@ -107,5 +107,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "99e4195c2638521cf24f1e5ebef5ae9bf5009d1d"
+    "gitHead": "65d5f0a31f87b8e3b7a23349f08cf7943ef15bda"
 }

package/src/endpoints/global/groups/GetGroupsEndpoint.ts

@@ -133,7 +133,7 @@ export class GetGroupsEndpoint extends Endpoint<Params, Query, Body, ResponseBod
             }
         }
 
-        const maxLimit = Context.auth.hasSomePlatformAccess() ? 1000 : 100;
+        const maxLimit = Context.optionalAuth?.hasSomePlatformAccess() ? 1000 : 100;
 
         if (request.query.limit > maxLimit) {
             throw new SimpleError({

package/src/endpoints/organization/dashboard/organization/PatchOrganizationEndpoint.test.ts

@@ -1,11 +1,13 @@
 import { Request } from '@simonbackx/simple-endpoints';
 import type { Organization, User, Webshop } from '@stamhoofd/models';
 import { GroupFactory, OrganizationFactory, OrganizationRegistrationPeriod, RegistrationPeriodFactory, Token, UserFactory, WebshopFactory } from '@stamhoofd/models';
-import { AccessRight, MemberResponsibility, OrganizationPrivateMetaData, OrganizationRegistrationPeriod as OrganizationRegistrationPeriodStruct, Organization as OrganizationStruct, PermissionLevel, PermissionRoleDetailed, PermissionRoleForResponsibility, Permissions, PermissionsResourceType, ResourcePermissions, Version } from '@stamhoofd/structures';
+import { AccessRight, Address, Company, MemberResponsibility, OrganizationMetaData, OrganizationPrivateMetaData, OrganizationRegistrationPeriod as OrganizationRegistrationPeriodStruct, Organization as OrganizationStruct, PeppolEndointId, PermissionLevel, PermissionRoleDetailed, PermissionRoleForResponsibility, Permissions, PermissionsResourceType, ResourcePermissions, Version } from '@stamhoofd/structures';
 
 import type { AutoEncoderPatchType, PatchableArrayAutoEncoder } from '@simonbackx/simple-encoding';
 import { PatchableArray, PatchMap } from '@simonbackx/simple-encoding';
 import { STExpect, TestUtils } from '@stamhoofd/test-utils';
+import { Country } from '@stamhoofd/types/Country';
+import nock from 'nock';
 import { testServer } from '../../../../../tests/helpers/TestServer.js';
 import { PatchOrganizationEndpoint } from './PatchOrganizationEndpoint.js';
 
@@ -1282,6 +1284,192 @@ describe('Endpoint.PatchOrganization', () => {
         });
     });
 
+    describe('custom PEPPOL endpoint id on companies', () => {
+        const belgianAddress = () => Address.create({
+            street: 'Demostraat',
+            number: '12',
+            city: 'Gent',
+            postalCode: '9000',
+            country: Country.Belgium,
+        });
+
+        function mockDirectoryFound(schemeID: string, id: string, entityName = 'Directory Name') {
+            return nock('https://directory.peppol.eu')
+                .get('/search/1.0/json')
+                .query({ participant: `iso6523-actorid-upis::${schemeID}:${id}` })
+                .reply(200, {
+                    'total-result-count': 1,
+                    matches: [{
+                        participantID: { scheme: 'iso6523-actorid-upis', value: `${schemeID}:${id}` },
+                        entities: [{ name: [{ name: entityName }] }],
+                    }],
+                } as nock.Body);
+        }
+
+        afterEach(() => {
+            nock.cleanAll();
+        });
+
+        const companiesPut = (company: Company): PatchableArrayAutoEncoder<Company> => {
+            const arr: PatchableArrayAutoEncoder<Company> = new PatchableArray();
+            arr.addPut(company);
+            return arr;
+        };
+
+        const companiesPatch = (patch: AutoEncoderPatchType<Company>): PatchableArrayAutoEncoder<Company> => {
+            const arr: PatchableArrayAutoEncoder<Company> = new PatchableArray();
+            arr.addPatch(patch);
+            return arr;
+        };
+
+        test('a normal organization admin cannot add a company with a custom PEPPOL endpoint id', async () => {
+            const scope = mockDirectoryFound('0208', '0123456789');
+            const organization = await new OrganizationFactory({}).create();
+            const user = await new UserFactory({ organization, permissions: Permissions.create({ level: PermissionLevel.Full }) }).create();
+            const token = await Token.createToken(user);
+
+            const patch = OrganizationStruct.patch({
+                id: organization.id,
+                meta: OrganizationMetaData.patch({
+                    companies: companiesPut(Company.create({
+                        name: 'Demo Company',
+                        address: belgianAddress(),
+                        customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '0123456789' }),
+                    })),
+                }),
+            });
+
+            await expect(patchOrganization({ patch, organization, token })).rejects.toThrow(
+                STExpect.simpleError({ code: 'permission_denied', field: 'customPeppolEndpointId' }),
+            );
+
+            // The directory must not have been contacted: the permission check happens first.
+            expect(scope.isDone()).toBe(false);
+        });
+
+        test('a normal organization admin cannot patch a custom PEPPOL endpoint id onto an existing company', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const company = Company.create({ name: 'Demo Company', address: belgianAddress() });
+            organization.meta.companies = [company];
+            await organization.save();
+
+            const user = await new UserFactory({ organization, permissions: Permissions.create({ level: PermissionLevel.Full }) }).create();
+            const token = await Token.createToken(user);
+
+            const patch = OrganizationStruct.patch({
+                id: organization.id,
+                meta: OrganizationMetaData.patch({
+                    companies: companiesPatch(Company.patch({
+                        id: company.id,
+                        customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '0123456789' }),
+                    })),
+                }),
+            });
+
+            await expect(patchOrganization({ patch, organization, token })).rejects.toThrow(
+                STExpect.simpleError({ code: 'permission_denied', field: 'customPeppolEndpointId' }),
+            );
+        });
+
+        test('a platform admin can set a custom PEPPOL endpoint id that is validated against the directory', async () => {
+            const scope = mockDirectoryFound('0088', '5412345000013');
+            const organization = await new OrganizationFactory({}).create();
+            const user = await new UserFactory({ globalPermissions: Permissions.create({ level: PermissionLevel.Full }) }).create();
+            const token = await Token.createToken(user);
+
+            const patch = OrganizationStruct.patch({
+                id: organization.id,
+                meta: OrganizationMetaData.patch({
+                    companies: companiesPut(Company.create({
+                        name: 'Demo Company',
+                        address: belgianAddress(),
+                        customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013' }),
+                    })),
+                }),
+            });
+
+            const response = await patchOrganization({ patch, organization, token });
+
+            expect(scope.isDone()).toBe(true);
+            expect(response.body.meta.companies).toHaveLength(1);
+            expect(response.body.meta.companies[0].customPeppolEndpointId).toMatchObject({
+                schemeID: '0088',
+                id: '5412345000013',
+                // The registered entity name from the directory is stored.
+                entityName: 'Directory Name',
+            });
+        });
+
+        test('a client-supplied entityName is ignored and overwritten by the directory value', async () => {
+            mockDirectoryFound('0088', '5412345000013', 'Directory Name');
+            const organization = await new OrganizationFactory({}).create();
+            const user = await new UserFactory({ globalPermissions: Permissions.create({ level: PermissionLevel.Full }) }).create();
+            const token = await Token.createToken(user);
+
+            const patch = OrganizationStruct.patch({
+                id: organization.id,
+                meta: OrganizationMetaData.patch({
+                    companies: companiesPut(Company.create({
+                        name: 'Demo Company',
+                        address: belgianAddress(),
+                        customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013', entityName: 'Spoofed name' }),
+                    })),
+                }),
+            });
+
+            const response = await patchOrganization({ patch, organization, token });
+
+            expect(response.body.meta.companies[0].customPeppolEndpointId?.entityName).toBe('Directory Name');
+        });
+
+        test('a KBO custom PEPPOL endpoint id that does not match the company number is rejected', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const user = await new UserFactory({ globalPermissions: Permissions.create({ level: PermissionLevel.Full }) }).create();
+            const token = await Token.createToken(user);
+
+            const patch = OrganizationStruct.patch({
+                id: organization.id,
+                meta: OrganizationMetaData.patch({
+                    companies: companiesPut(Company.create({
+                        name: 'Demo Company',
+                        address: belgianAddress(),
+                        customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '9999999999' }),
+                    })),
+                }),
+            });
+
+            await expect(patchOrganization({ patch, organization, token })).rejects.toThrow(
+                STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }),
+            );
+        });
+
+        test('a platform admin gets an error when the custom PEPPOL endpoint id is unknown to the directory', async () => {
+            nock('https://directory.peppol.eu')
+                .get('/search/1.0/json')
+                .query({ participant: 'iso6523-actorid-upis::0088:5412345000013' })
+                .reply(200, { 'total-result-count': 0, matches: [] } as nock.Body);
+
+            const organization = await new OrganizationFactory({}).create();
+            const user = await new UserFactory({ globalPermissions: Permissions.create({ level: PermissionLevel.Full }) }).create();
+            const token = await Token.createToken(user);
+
+            const patch = OrganizationStruct.patch({
+                id: organization.id,
+                meta: OrganizationMetaData.patch({
+                    companies: companiesPut(Company.create({
+                        name: 'Demo Company',
+                        address: belgianAddress(),
+                        customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013' }),
+                    })),
+                }),
+            });
+
+            await expect(patchOrganization({ patch, organization, token })).rejects.toThrow(
+                STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }),
+            );
+        });
+    });
+
     describe('userMode organization', () => {
         beforeEach(async () => {
             TestUtils.setEnvironment('userMode', 'organization');

package/src/endpoints/organization/dashboard/organization/PatchOrganizationEndpoint.ts

@@ -660,6 +660,20 @@ export class PatchOrganizationEndpoint extends Endpoint<Params, Query, Body, Res
         return new Response(struct);
     }
 
+    /**
+     * A custom PEPPOL endpoint id may only be set by full platform admins for now.
+     */
+    private requirePeppolPermission() {
+        if (!Context.auth.hasPlatformFullAccess()) {
+            throw new SimpleError({
+                code: 'permission_denied',
+                message: 'Only platform admins can set a custom PEPPOL endpoint id',
+                human: $t('%Zcg'),
+                field: 'customPeppolEndpointId',
+            });
+        }
+    }
+
     async validateCompanies(organization: Organization, companies: PatchableArrayAutoEncoder<Company> | Company[]) {
         if (isPatchableArray(companies)) {
             for (const patch of companies.getPatches()) {
@@ -674,6 +688,10 @@ export class PatchOrganizationEndpoint extends Endpoint<Params, Query, Body, Res
                     });
                 }
 
+                if (patch.customPeppolEndpointId !== undefined) {
+                    this.requirePeppolPermission();
+                }
+
                 // Changed VAT number
                 const prepatched = original.patch(patch);
                 await ViesHelper.checkCompany(prepatched, patch);
@@ -692,6 +710,10 @@ export class PatchOrganizationEndpoint extends Endpoint<Params, Query, Body, Res
                     });
                 }
 
+                if (put.customPeppolEndpointId) {
+                    this.requirePeppolPermission();
+                }
+
                 await ViesHelper.checkCompany(put, put);
             }
         } else {
@@ -705,6 +727,10 @@ export class PatchOrganizationEndpoint extends Endpoint<Params, Query, Body, Res
             }
 
             for (const company of companies) {
+                if (company.customPeppolEndpointId) {
+                    this.requirePeppolPermission();
+                }
+
                 await ViesHelper.checkCompany(company, company);
             }
         }

package/src/helpers/ViesHelper.test.ts

@@ -1,4 +1,4 @@
-import { Address, Company } from '@stamhoofd/structures';
+import { Address, Company, PeppolEndointId } from '@stamhoofd/structures';
 import { STExpect, TestUtils } from '@stamhoofd/test-utils';
 import { Country } from '@stamhoofd/types/Country';
 import nock from 'nock';
@@ -7,6 +7,9 @@ import { ViesHelper } from './ViesHelper.js';
 const VIES_HOST = 'https://ec.europa.eu';
 const VIES_PATH = '/taxation_customs/vies/rest-api/check-vat-number';
 
+const DIRECTORY_HOST = 'https://directory.peppol.eu';
+const DIRECTORY_PATH = '/search/1.0/json';
+
 describe('ViesHelper', () => {
     /**
      * Registers a mock for the (only) external dependency: the VIES check-vat-number endpoint.
@@ -253,5 +256,146 @@ describe('ViesHelper', () => {
             expect(patch.VATNumber).toBe('BE0411905847');
             expect(patch.companyNumber).toBe('0411905847');
         });
+
+        describe('custom PEPPOL endpoint id', () => {
+            function mockDirectoryFound(participant: string, entityName = 'Directory Name') {
+                return nock(DIRECTORY_HOST)
+                    .get(DIRECTORY_PATH)
+                    .query({ participant })
+                    .reply(200, {
+                        'total-result-count': 1,
+                        matches: [{
+                            participantID: { scheme: 'iso6523-actorid-upis', value: participant.split('::')[1] },
+                            entities: [{ name: [{ name: entityName }] }],
+                        }],
+                    } as nock.Body);
+            }
+
+            function mockDirectoryNotFound(participant: string) {
+                return nock(DIRECTORY_HOST)
+                    .get(DIRECTORY_PATH)
+                    .query({ participant })
+                    .reply(200, { 'total-result-count': 0, matches: [] } as nock.Body);
+            }
+
+            // Use a GLN endpoint id for the generic directory/entityName tests: it has no
+            // extra constraints, unlike a KBO (0208) id which must match the company number.
+            const companyWithPeppol = () => Company.create({
+                name: 'Demo Company',
+                address: belgianAddress(),
+                customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013' }),
+            });
+
+            test('validates the id against the directory when it was changed', async () => {
+                const scope = mockDirectoryFound('iso6523-actorid-upis::0088:5412345000013');
+
+                const company = companyWithPeppol();
+                const patch = Company.patch({ customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013' }) });
+
+                await expect(ViesHelper.checkCompany(company, patch)).resolves.toBeUndefined();
+                expect(scope.isDone()).toBe(true);
+                // The registered entity name is stored from the directory.
+                expect(company.customPeppolEndpointId?.entityName).toBe('Directory Name');
+            });
+
+            test('overwrites a client-supplied entityName with the value from the directory', async () => {
+                mockDirectoryFound('iso6523-actorid-upis::0088:5412345000013');
+
+                const company = Company.create({
+                    name: 'Demo Company',
+                    address: belgianAddress(),
+                    customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013', entityName: 'Client supplied name' }),
+                });
+                const patch = Company.patch({ customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013', entityName: 'Client supplied name' }) });
+
+                await ViesHelper.checkCompany(company, patch);
+
+                // entityName is server-controlled: the client value is discarded.
+                expect(company.customPeppolEndpointId?.entityName).toBe('Directory Name');
+                expect(patch.customPeppolEndpointId).not.toBeNull();
+                expect((patch.customPeppolEndpointId as PeppolEndointId | undefined)?.entityName).toBe('Directory Name');
+            });
+
+            test('does not contact the directory when the id did not change', async () => {
+                const scope = mockDirectoryFound('iso6523-actorid-upis::0088:5412345000013');
+
+                const company = companyWithPeppol();
+                const patch = Company.patch({ name: 'Renamed Company' });
+
+                await ViesHelper.checkCompany(company, patch);
+                expect(scope.isDone()).toBe(false);
+            });
+
+            test('rejects an id that is unknown to the directory', async () => {
+                mockDirectoryNotFound('iso6523-actorid-upis::0088:5412345000013');
+
+                const company = companyWithPeppol();
+                const patch = Company.patch({ customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013' }) });
+
+                await expect(ViesHelper.checkCompany(company, patch)).rejects.toThrow(
+                    STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }),
+                );
+            });
+
+            test('does not contact the directory when the id is cleared', async () => {
+                const scope = mockDirectoryFound('iso6523-actorid-upis::0088:5412345000013');
+
+                const company = Company.create({ name: 'Demo Company', address: belgianAddress() });
+                const patch = Company.patch({ customPeppolEndpointId: null });
+
+                await ViesHelper.checkCompany(company, patch);
+                expect(scope.isDone()).toBe(false);
+            });
+
+            test('rejects a KBO endpoint id for a non-Belgian company before contacting the directory', async () => {
+                const scope = mockDirectoryFound('iso6523-actorid-upis::0208:0411905847');
+
+                const company = Company.create({
+                    name: 'Demo Company',
+                    address: Address.create({ street: 'Damstraat', number: '1', city: 'Amsterdam', postalCode: '1012', country: Country.Netherlands }),
+                    customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '0411905847' }),
+                });
+                const patch = Company.patch({ customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '0411905847' }) });
+
+                await expect(ViesHelper.checkCompany(company, patch)).rejects.toThrow(
+                    STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }),
+                );
+                expect(scope.isDone()).toBe(false);
+            });
+
+            test('rejects a KBO endpoint id that does not match the company number before contacting the directory', async () => {
+                const scope = mockDirectoryFound('iso6523-actorid-upis::0208:9999999999');
+
+                const company = Company.create({
+                    name: 'Demo Company',
+                    address: belgianAddress(),
+                    companyNumber: '0411905847',
+                    customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '9999999999' }),
+                });
+                const patch = Company.patch({ customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '9999999999' }) });
+
+                await expect(ViesHelper.checkCompany(company, patch)).rejects.toThrow(
+                    STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }),
+                );
+                expect(scope.isDone()).toBe(false);
+            });
+
+            test('accepts a KBO endpoint id that matches the company number', async () => {
+                mockVies({ valid: true });
+                const scope = mockDirectoryFound('iso6523-actorid-upis::0208:0411905847');
+
+                const company = Company.create({
+                    name: 'Demo Company',
+                    address: belgianAddress(),
+                    companyNumber: '0411905847',
+                    customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '0411905847' }),
+                });
+                const patch = Company.patch({ customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0208', id: '0411905847' }) });
+
+                await expect(ViesHelper.checkCompany(company, patch)).resolves.toBeUndefined();
+                expect(scope.isDone()).toBe(true);
+                expect(company.customPeppolEndpointId?.entityName).toBe('Directory Name');
+            });
+        });
     });
 });

package/src/helpers/ViesHelper.ts

@@ -1,9 +1,11 @@
 import type { AutoEncoderPatchType } from '@simonbackx/simple-encoding';
 import { isSimpleError, isSimpleErrors, SimpleError } from '@simonbackx/simple-errors';
 import type { Company } from '@stamhoofd/structures';
+import { PeppolScheme } from '@stamhoofd/structures';
 import { Country } from '@stamhoofd/types/Country';
 import axios from 'axios';
 import jsvat from 'jsvat-next';
+import { PeppolDirectoryService } from '../services/PeppolDirectoryService.js';
 
 export class ViesHelperStatic {
     testMode = false;
@@ -27,6 +29,43 @@ export class ViesHelperStatic {
     }
 
     async checkCompany(company: Company, patch: AutoEncoderPatchType<Company> | Company) {
+        // Validate the custom PEPPOL endpoint id, but only when it actually changed.
+        // In a patch, `customPeppolEndpointId` is undefined unless the client changed it;
+        // for a full company it is always set (null or a value), so we validate a set value.
+        if (patch.customPeppolEndpointId !== undefined && company.customPeppolEndpointId) {
+            const endpointId = company.customPeppolEndpointId;
+
+            // A KBO (0208) endpoint id is the Belgian enterprise number, so it must belong to a
+            // Belgian company and be identical to this company's own company number.
+            if (endpointId.schemeID === (PeppolScheme.KBO as string)) {
+                if (company.address?.country !== Country.Belgium) {
+                    throw new SimpleError({
+                        code: 'invalid_field',
+                        message: 'A KBO PEPPOL id can only be used for a Belgian company',
+                        human: $t('%Zck'),
+                        field: 'customPeppolEndpointId',
+                    });
+                }
+
+                const companyPeppolId = company.peppolCompanyId;
+                if (!companyPeppolId || endpointId.id.replace(/\D+/g, '') !== companyPeppolId.id.replace(/\D+/g, '')) {
+                    throw new SimpleError({
+                        code: 'invalid_field',
+                        message: 'A KBO PEPPOL id must match the company number',
+                        human: $t('%ZcZ'),
+                        field: 'customPeppolEndpointId',
+                    });
+                }
+            }
+
+            // validate() fills in the server-controlled entityName from the PEPPOL directory.
+            await PeppolDirectoryService.validate(endpointId);
+
+            // Write the validated endpoint id back as a full replacement so any client-supplied
+            // entityName is discarded: entityName can only ever be set by the server.
+            patch.customPeppolEndpointId = endpointId;
+        }
+
         if (!company.address) {
             // Not allowed to set
             patch.companyNumber = null;

package/src/services/InvoiceXMLService.test.ts

@@ -0,0 +1,161 @@
+import { BalanceItemFactory, Invoice, InvoicedBalanceItem, OrganizationFactory } from '@stamhoofd/models';
+import { Address, Company, File, PaymentCustomer, PeppolEndointId, VATSubtotal } from '@stamhoofd/structures';
+import { Country } from '@stamhoofd/types/Country';
+import { v4 as uuidv4 } from 'uuid';
+import { vi } from 'vitest';
+import { InvoicePdfService } from './InvoicePdfService.js';
+import { InvoiceXMlService } from './InvoiceXMLService.js';
+
+describe('InvoiceXMlService', () => {
+    beforeEach(() => {
+        // The pdf is embedded as base64 in the UBL; avoid the real network download.
+        vi.spyOn(InvoicePdfService, 'downloadPdf').mockResolvedValue(Buffer.from('%PDF-1.4 test'));
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    const belgianAddress = () => Address.create({
+        street: 'Teststraat',
+        number: '1',
+        city: 'Gent',
+        postalCode: '9000',
+        country: Country.Belgium,
+    });
+
+    const seller = () => Company.create({
+        name: 'Seller BV',
+        VATNumber: 'BE0411905847',
+        companyNumber: '0411905847',
+        address: belgianAddress(),
+        administrationEmail: 'billing@seller.be',
+    });
+
+    /**
+     * Builds and persists a minimal, valid invoice for the given customer company, with one
+     * invoiced line, so that InvoiceXMlService.buildXml can generate the UBL.
+     */
+    const buildInvoiceFor = async (company: Company) => {
+        const organization = await new OrganizationFactory({}).create();
+
+        const invoice = new Invoice();
+        invoice.organizationId = organization.id;
+        invoice.number = 'F2026-001';
+        invoice.invoicedAt = new Date(2026, 0, 15);
+        invoice.pdf = new File({ id: uuidv4(), server: 'https://files.example.com', path: 'test.pdf', size: 100, name: 'invoice', contentType: 'application/pdf' });
+        invoice.customer = PaymentCustomer.create({ company });
+        invoice.seller = seller();
+        invoice.totalWithVAT = 12_10;
+        invoice.totalWithoutVAT = 10_00;
+        invoice.VATTotalAmount = 2_10;
+        invoice.payableRoundingAmount = 0;
+        invoice.VATTotal = [VATSubtotal.create({ VATPercentage: 21, taxablePrice: 10_00, VAT: 2_10 })];
+        await invoice.save();
+
+        const balanceItem = await new BalanceItemFactory({ organizationId: organization.id, amount: 1, unitPrice: 10_00 }).create();
+
+        const item = new InvoicedBalanceItem();
+        item.organizationId = organization.id;
+        item.invoiceId = invoice.id;
+        item.balanceItemId = balanceItem.id;
+        item.name = 'Test item';
+        item.unitPrice = 10_00;
+        item.totalWithoutVAT = 10_00;
+        item.quantity = 1_00_00;
+        item.VATPercentage = 21;
+        item.balanceInvoicedAmount = 12_10;
+        await item.save();
+
+        return invoice;
+    };
+
+    test('generates XML for a Belgian company with a VAT number', async () => {
+        const company = Company.create({
+            name: 'Customer BV',
+            VATNumber: 'BE0123456749',
+            companyNumber: '0123456749',
+            address: belgianAddress(),
+        });
+        const invoice = await buildInvoiceFor(company);
+
+        const xml = await InvoiceXMlService.buildXml(invoice);
+
+        expect(xml).toContain('<cbc:Name>Customer BV</cbc:Name>');
+        // No custom PEPPOL id: the endpoint id is the derived KBO number.
+        expect(xml).toContain('<cbc:EndpointID schemeID="0208">0123456749</cbc:EndpointID>');
+        // The legal entity company id is the derived KBO number.
+        expect(xml).toContain('<cbc:CompanyID schemeID="0208">0123456749</cbc:CompanyID>');
+        // The VAT number is registered as a tax scheme.
+        expect(xml).toContain('<cbc:CompanyID>BE0123456749</cbc:CompanyID>');
+    });
+
+    test('generates XML for a Belgian company with only a company number', async () => {
+        const company = Company.create({
+            name: 'Customer VZW',
+            VATNumber: null,
+            companyNumber: '0123456749',
+            address: belgianAddress(),
+        });
+        const invoice = await buildInvoiceFor(company);
+
+        const xml = await InvoiceXMlService.buildXml(invoice);
+
+        expect(xml).toContain('<cbc:Name>Customer VZW</cbc:Name>');
+        expect(xml).toContain('<cbc:EndpointID schemeID="0208">0123456749</cbc:EndpointID>');
+        expect(xml).toContain('<cbc:CompanyID schemeID="0208">0123456749</cbc:CompanyID>');
+        // No VAT number for this company: no customer VAT tax scheme.
+        expect(xml).not.toContain('BE0123456749');
+    });
+
+    test('generates XML for a Belgian company with a VAT number and a custom PEPPOL id', async () => {
+        const company = Company.create({
+            name: 'Customer BV',
+            VATNumber: 'BE0123456749',
+            companyNumber: '0123456749',
+            address: belgianAddress(),
+            customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013' }),
+        });
+        const invoice = await buildInvoiceFor(company);
+
+        const xml = await InvoiceXMlService.buildXml(invoice);
+
+        // The custom PEPPOL id is used as the delivery endpoint id.
+        expect(xml).toContain('<cbc:EndpointID schemeID="0088">5412345000013</cbc:EndpointID>');
+        // But the legal entity company id remains the derived KBO number.
+        expect(xml).toContain('<cbc:CompanyID schemeID="0208">0123456749</cbc:CompanyID>');
+        expect(xml).toContain('<cbc:CompanyID>BE0123456749</cbc:CompanyID>');
+    });
+
+    test('generates XML for a Belgian company with only a company number and a custom PEPPOL id', async () => {
+        const company = Company.create({
+            name: 'Customer VZW',
+            VATNumber: null,
+            companyNumber: '0123456749',
+            address: belgianAddress(),
+            customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0060', id: '123456789' }),
+        });
+        const invoice = await buildInvoiceFor(company);
+
+        const xml = await InvoiceXMlService.buildXml(invoice);
+
+        expect(xml).toContain('<cbc:EndpointID schemeID="0060">123456789</cbc:EndpointID>');
+        expect(xml).toContain('<cbc:CompanyID schemeID="0208">0123456749</cbc:CompanyID>');
+        expect(xml).not.toContain('BE0123456749');
+    });
+
+    test('cannot generate XML for a company without a company number, even with a custom PEPPOL id', async () => {
+        const company = Company.create({
+            name: 'No Number',
+            VATNumber: null,
+            companyNumber: null,
+            address: belgianAddress(),
+            customPeppolEndpointId: PeppolEndointId.create({ schemeID: '0088', id: '5412345000013' }),
+        });
+        const invoice = await buildInvoiceFor(company);
+
+        // The legal entity company id (peppolCompanyId) requires a VAT or company number,
+        // so a custom endpoint id alone is not enough.
+        await expect(InvoiceXMlService.buildXml(invoice)).rejects.toThrow('Missing customer peppol id');
+    });
+});

package/src/services/InvoiceXMLService.ts

@@ -202,7 +202,7 @@ export class InvoiceXMlService {
                     }
                     <cac:PartyLegalEntity>
                         <cbc:RegistrationName>${esc(company.name)}</cbc:RegistrationName>
-                        <cbc:CompanyID schemeID="0208">${esc(companyNumber)}</cbc:CompanyID>
+                        <cbc:CompanyID schemeID="${esc(customerPeppolCompanyId.schemeID)}">${esc(customerPeppolCompanyId.id)}</cbc:CompanyID>
                     </cac:PartyLegalEntity>
                     ${
                         customerEmail
@@ -398,15 +398,17 @@ export class InvoiceXMlService {
             return;
         }
 
-        if (invoice.customer.company?.VATNumber === null) {
-            console.log('Skipping PEPPOL for invoice ' + invoice.id + ', recipient not subject to VAT');
-            return;
-        }
+        if (!invoice.customer.company?.customPeppolEndpointId) {
+            if (invoice.customer.company?.VATNumber === null) {
+                console.log('Skipping PEPPOL for invoice ' + invoice.id + ', recipient not subject to VAT');
+                return;
+            }
 
-        // Check VAT number is belgian
-        if (!invoice.customer.company?.VATNumber.startsWith('BE')) {
-            console.log('Skipping PEPPOL for invoice ' + invoice.id + ', recipient outside Belgium');
-            return;
+            // Check VAT number is belgian
+            if (!invoice.customer.company?.VATNumber.startsWith('BE')) {
+                console.log('Skipping PEPPOL for invoice ' + invoice.id + ', recipient outside Belgium');
+                return;
+            }
         }
 
         try {

package/src/services/PeppolDirectoryService.test.ts

@@ -0,0 +1,139 @@
+import { PeppolEndointId } from '@stamhoofd/structures';
+import { STExpect } from '@stamhoofd/test-utils';
+import nock from 'nock';
+import { PeppolDirectoryService } from './PeppolDirectoryService.js';
+
+const DIRECTORY_HOST = 'https://directory.peppol.eu';
+const DIRECTORY_PATH = '/search/1.0/json';
+
+describe('PeppolDirectoryService', () => {
+    /**
+     * Mocks the PEPPOL directory search endpoint for a given participant query.
+     * Returns the nock scope so tests can assert whether it was actually called.
+     */
+    function mockDirectory(participant: string, response: unknown, statusCode = 200) {
+        return nock(DIRECTORY_HOST)
+            .get(DIRECTORY_PATH)
+            .query({ participant })
+            .reply(statusCode, response as nock.Body);
+    }
+
+    /**
+     * A directory response that contains a single match for the given participant value.
+     */
+    function matchResponse(value: string) {
+        return {
+            version: '1.0',
+            'total-result-count': 1,
+            matches: [
+                {
+                    participantID: { scheme: 'iso6523-actorid-upis', value },
+                    entities: [{ name: [{ name: 'Demo Company' }], countryCode: 'BE' }],
+                },
+            ],
+        };
+    }
+
+    afterEach(() => {
+        nock.cleanAll();
+        nock.disableNetConnect();
+    });
+
+    test('resolves when the participant is registered in the directory', async () => {
+        const scope = mockDirectory('iso6523-actorid-upis::0208:0123456789', matchResponse('0208:0123456789'));
+
+        const endpointId = PeppolEndointId.create({ schemeID: '0208', id: '0123456789' });
+        await expect(PeppolDirectoryService.validate(endpointId)).resolves.toBeUndefined();
+
+        expect(scope.isDone()).toBe(true);
+        // The registered entity name from the directory is stored on the endpoint id.
+        expect(endpointId.entityName).toBe('Demo Company');
+    });
+
+    test('overwrites a pre-existing entityName with the value from the directory', async () => {
+        mockDirectory('iso6523-actorid-upis::0208:0123456789', matchResponse('0208:0123456789'));
+
+        const endpointId = PeppolEndointId.create({ schemeID: '0208', id: '0123456789', entityName: 'Client supplied name' });
+        await PeppolDirectoryService.validate(endpointId);
+
+        expect(endpointId.entityName).toBe('Demo Company');
+    });
+
+    test('sets entityName to null when the directory match has no entity name', async () => {
+        mockDirectory('iso6523-actorid-upis::0208:0123456789', {
+            'total-result-count': 1,
+            matches: [{ participantID: { scheme: 'iso6523-actorid-upis', value: '0208:0123456789' }, entities: [] }],
+        });
+
+        const endpointId = PeppolEndointId.create({ schemeID: '0208', id: '0123456789', entityName: 'stale' });
+        await PeppolDirectoryService.validate(endpointId);
+
+        expect(endpointId.entityName).toBeNull();
+    });
+
+    test('trims whitespace around the scheme and id before querying', async () => {
+        const scope = mockDirectory('iso6523-actorid-upis::0088:5412345000013', matchResponse('0088:5412345000013'));
+
+        await expect(
+            PeppolDirectoryService.validate(PeppolEndointId.create({ schemeID: ' 0088 ', id: ' 5412345000013 ' })),
+        ).resolves.toBeUndefined();
+
+        expect(scope.isDone()).toBe(true);
+    });
+
+    test('rejects an unsupported scheme without contacting the directory', async () => {
+        const scope = mockDirectory('iso6523-actorid-upis::9999:123', matchResponse('9999:123'));
+
+        await expect(
+            PeppolDirectoryService.validate(PeppolEndointId.create({ schemeID: '9999', id: '123' })),
+        ).rejects.toThrow(STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }));
+
+        expect(scope.isDone()).toBe(false);
+    });
+
+    test('rejects an empty id without contacting the directory', async () => {
+        const scope = mockDirectory('iso6523-actorid-upis::0208:', matchResponse('0208:'));
+
+        await expect(
+            PeppolDirectoryService.validate(PeppolEndointId.create({ schemeID: '0208', id: '   ' })),
+        ).rejects.toThrow(STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }));
+
+        expect(scope.isDone()).toBe(false);
+    });
+
+    test('rejects when the participant is not found in the directory', async () => {
+        mockDirectory('iso6523-actorid-upis::0060:123456789', {
+            version: '1.0',
+            'total-result-count': 0,
+            matches: [],
+        });
+
+        await expect(
+            PeppolDirectoryService.validate(PeppolEndointId.create({ schemeID: '0060', id: '123456789' })),
+        ).rejects.toThrow(STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }));
+    });
+
+    test('rejects when the directory only returns a different participant', async () => {
+        mockDirectory('iso6523-actorid-upis::0208:0123456789', matchResponse('0208:9999999999'));
+
+        await expect(
+            PeppolDirectoryService.validate(PeppolEndointId.create({ schemeID: '0208', id: '0123456789' })),
+        ).rejects.toThrow(STExpect.simpleError({ code: 'invalid_field', field: 'customPeppolEndpointId' }));
+    });
+
+    test('throws service_unavailable when the directory errors out', async () => {
+        mockDirectory('iso6523-actorid-upis::0208:0123456789', { message: 'Internal Server Error' }, 500);
+
+        await expect(
+            PeppolDirectoryService.validate(PeppolEndointId.create({ schemeID: '0208', id: '0123456789' })),
+        ).rejects.toThrow(STExpect.simpleError({ code: 'service_unavailable', field: 'customPeppolEndpointId' }));
+    });
+
+    test('throws service_unavailable when the directory returns an unexpected response', async () => {
+        mockDirectory('iso6523-actorid-upis::0208:0123456789', { unexpected: true });
+
+        await expect(
+            PeppolDirectoryService.validate(PeppolEndointId.create({ schemeID: '0208', id: '0123456789' })),
+        ).rejects.toThrow(STExpect.simpleError({ code: 'service_unavailable', field: 'customPeppolEndpointId' }));
+    });
+});

package/src/services/PeppolDirectoryService.ts

@@ -0,0 +1,111 @@
+import { SimpleError } from '@simonbackx/simple-errors';
+import type { PeppolEndointId } from '@stamhoofd/structures';
+import { PeppolScheme } from '@stamhoofd/structures';
+import axios from 'axios';
+
+/**
+ * The PEPPOL schemes (ISO 6523 ICD codes) we currently support for a custom
+ * PEPPOL endpoint id. The scheme identifier is the numeric code used in the
+ * PEPPOL participant identifier (e.g. `iso6523-actorid-upis::0208:...`).
+ */
+export const supportedPeppolSchemes: string[] = Object.values(PeppolScheme);
+
+export class PeppolDirectoryServiceStatic {
+    /**
+     * Validates a custom PEPPOL endpoint id: the scheme must be supported and the
+     * participant must be registered in the PEPPOL directory. Throws a SimpleError
+     * (with field `customPeppolEndpointId`) when the id is invalid or unknown.
+     */
+    async validate(endpointId: PeppolEndointId): Promise<void> {
+        const schemeID = endpointId.schemeID.trim();
+        const id = endpointId.id.trim();
+
+        if (!supportedPeppolSchemes.includes(schemeID)) {
+            throw new SimpleError({
+                code: 'invalid_field',
+                message: 'Unsupported PEPPOL scheme ' + schemeID,
+                human: $t('%ZcX'),
+                field: 'customPeppolEndpointId',
+            });
+        }
+
+        if (id.length === 0) {
+            throw new SimpleError({
+                code: 'invalid_field',
+                message: 'Missing PEPPOL endpoint id',
+                human: $t('%ZcY'),
+                field: 'customPeppolEndpointId',
+            });
+        }
+
+        const participant = `iso6523-actorid-upis::${schemeID}:${id}`;
+
+        let data: any;
+        try {
+            const response = await axios.request({
+                method: 'GET',
+                url: 'https://directory.peppol.eu/search/1.0/json',
+                params: { participant },
+            });
+            data = response.data;
+        } catch (e) {
+            // The directory is unavailable: we can't validate the id right now.
+            console.error('PEPPOL directory error', e);
+            throw new SimpleError({
+                code: 'service_unavailable',
+                message: 'PEPPOL directory unavailable',
+                human: $t('%Zcf'),
+                field: 'customPeppolEndpointId',
+            });
+        }
+
+        if (typeof data !== 'object' || data === null || !Array.isArray(data.matches)) {
+            throw new SimpleError({
+                code: 'service_unavailable',
+                message: 'Invalid response from PEPPOL directory',
+                human: $t('%Zcf'),
+                field: 'customPeppolEndpointId',
+            });
+        }
+
+        console.log('PEPPOL lookup', participant, data);
+
+        const expected = `${schemeID}:${id}`.toLowerCase();
+        const match = data.matches.find((m: any) => {
+            return typeof m?.participantID?.value === 'string'
+                && m.participantID.value.toLowerCase() === expected;
+        });
+
+        if (!match) {
+            throw new SimpleError({
+                code: 'invalid_field',
+                message: 'PEPPOL participant not found in directory: ' + participant,
+                human: $t('%Zcr', { id: `${schemeID}:${id}` }),
+                field: 'customPeppolEndpointId',
+            });
+        }
+
+        // Store the registered entity name from the directory. This is server-controlled
+        // and overwrites any value the client may have sent (see ViesHelper.checkCompany).
+        endpointId.entityName = this.extractEntityName(match);
+    }
+
+    /**
+     * Best-effort extraction of the registered entity name from a PEPPOL directory match.
+     * The directory returns one or more entities, each with a list of localized names.
+     */
+    private extractEntityName(match: any): string | null {
+        const entities = Array.isArray(match?.entities) ? match.entities : [];
+        for (const entity of entities) {
+            const names = Array.isArray(entity?.name) ? entity.name : [];
+            for (const n of names) {
+                if (typeof n?.name === 'string' && n.name.trim().length > 0) {
+                    return n.name.trim();
+                }
+            }
+        }
+        return null;
+    }
+}
+
+export const PeppolDirectoryService = new PeppolDirectoryServiceStatic();