@stamhoofd/backend 2.132.1 → 2.134.0

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/endpoints/organization/dashboard/payments/GetPaymentsEndpoint.test.ts

@@ -0,0 +1,158 @@
+import { Request } from '@simonbackx/simple-endpoints';
+import type { Organization, User } from '@stamhoofd/models';
+import { BalanceItem, BalanceItemFactory, BalanceItemPayment, OrderFactory, OrganizationFactory, Payment, Token, UserFactory, WebshopFactory } from '@stamhoofd/models';
+import type { PaginatedResponse, PaymentGeneral, StamhoofdFilter } from '@stamhoofd/structures';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, LimitedFilteredRequest, PaymentMethod, PaymentStatus, PermissionLevel, Permissions, TranslatedString } from '@stamhoofd/structures';
+import { testServer } from '../../../../../tests/helpers/TestServer.js';
+import { GetPaymentsEndpoint } from './GetPaymentsEndpoint.js';
+
+// These tests exercise the balance-item filters reused inside the payments query (balanceItemPayments ->
+// balanceItem -> ...), which is the path where balance_items is joined into another query.
+describe('Endpoint.GetPaymentsEndpoint', () => {
+    const endpoint = new GetPaymentsEndpoint();
+
+    const getPayments = async ({ filter, organization, user }: { filter: StamhoofdFilter | null; organization: Organization; user: User }) => {
+        const token = await Token.createToken(user);
+
+        const request = Request.get({
+            path: '/payments',
+            host: organization.getApiHost(),
+            query: new LimitedFilteredRequest({
+                filter,
+                limit: 100,
+            }),
+            headers: {
+                authorization: 'Bearer ' + token.accessToken,
+            },
+        });
+
+        return testServer.test<PaginatedResponse<PaymentGeneral[], LimitedFilteredRequest>>(endpoint, request);
+    };
+
+    const createFinanceUser = async (organization: Organization) => {
+        return await new UserFactory({
+            organization,
+            permissions: Permissions.create({ level: PermissionLevel.Full }),
+        }).create();
+    };
+
+    const createPaymentForBalanceItem = async (organization: Organization, balanceItem: BalanceItem) => {
+        const payment = new Payment();
+        payment.method = PaymentMethod.Transfer;
+        payment.status = PaymentStatus.Succeeded;
+        payment.organizationId = organization.id;
+        payment.price = 10_00;
+        await payment.save();
+
+        const balanceItemPayment = new BalanceItemPayment();
+        balanceItemPayment.balanceItemId = balanceItem.id;
+        balanceItemPayment.paymentId = payment.id;
+        balanceItemPayment.price = 10_00;
+        balanceItemPayment.organizationId = organization.id;
+        await balanceItemPayment.save();
+
+        return payment;
+    };
+
+    describe('Filtering on the balance item of a payment', () => {
+        test('only returns payments whose balance item is linked to an order of the given webshop', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const user = await createFinanceUser(organization);
+
+            const webshop = await new WebshopFactory({ organizationId: organization.id }).create();
+            const otherWebshop = await new WebshopFactory({ organizationId: organization.id }).create();
+
+            const order = await new OrderFactory({ webshop }).create();
+            const otherOrder = await new OrderFactory({ webshop: otherWebshop }).create();
+
+            const matchingItem = await new BalanceItemFactory({
+                organizationId: organization.id,
+                orderId: order.id,
+                type: BalanceItemType.Order,
+                amount: 1,
+                unitPrice: 10_00,
+            }).create();
+            const matchingPayment = await createPaymentForBalanceItem(organization, matchingItem);
+
+            // Negative control: a payment for a balance item of another webshop's order
+            const otherItem = await new BalanceItemFactory({
+                organizationId: organization.id,
+                orderId: otherOrder.id,
+                type: BalanceItemType.Order,
+                amount: 1,
+                unitPrice: 10_00,
+            }).create();
+            await createPaymentForBalanceItem(organization, otherItem);
+
+            const response = await getPayments({
+                filter: {
+                    balanceItemPayments: {
+                        $elemMatch: {
+                            balanceItem: {
+                                order: {
+                                    webshopId: {
+                                        $in: [webshop.id],
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                organization,
+                user,
+            });
+
+            expect(response.status).toBe(200);
+            expect(response.body.results.map(r => r.id)).toEqual([matchingPayment.id]);
+        });
+
+        test('only returns payments whose balance item matches the given membership type', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const user = await createFinanceUser(organization);
+
+            const createMembershipItem = async (membershipTypeId: string) => {
+                return await new BalanceItemFactory({
+                    organizationId: organization.id,
+                    type: BalanceItemType.PlatformMembership,
+                    amount: 1,
+                    unitPrice: 10_00,
+                    relations: new Map([
+                        [
+                            BalanceItemRelationType.MembershipType,
+                            BalanceItemRelation.create({
+                                id: membershipTypeId,
+                                name: new TranslatedString('Membership type'),
+                            }),
+                        ],
+                    ]),
+                }).create();
+            };
+
+            const matchingItem = await createMembershipItem('membership-type-a');
+            const matchingPayment = await createPaymentForBalanceItem(organization, matchingItem);
+
+            // Negative control: a payment for a balance item with a different membership type
+            const otherItem = await createMembershipItem('membership-type-b');
+            await createPaymentForBalanceItem(organization, otherItem);
+
+            const response = await getPayments({
+                filter: {
+                    balanceItemPayments: {
+                        $elemMatch: {
+                            balanceItem: {
+                                membershipType: {
+                                    $in: ['membership-type-a'],
+                                },
+                            },
+                        },
+                    },
+                },
+                organization,
+                user,
+            });
+
+            expect(response.status).toBe(200);
+            expect(response.body.results.map(r => r.id)).toEqual([matchingPayment.id]);
+        });
+    });
+});

package/src/helpers/StripeInvoicer.ts

@@ -235,7 +235,7 @@ export class StripeReportInvoicer {
                 sellingOrganization,
                 type: 'services',
             });
-            item.VATIncluded = true;
+            item.VATIncluded = !item.VATExcempt; // Makes sure price with VAT always matches the charged amount
             item.quantity = 1;
             item.unitPrice = applicationFee.serviceFee;
             item.createdAt = new Date();
@@ -265,7 +265,7 @@ export class StripeReportInvoicer {
                 sellingOrganization,
                 type: 'services',
             });
-            item.VATIncluded = true;
+            item.VATIncluded = !item.VATExcempt; // Makes sure price with VAT always matches the charged amount
             item.quantity = 1;
             item.unitPrice = applicationFee.transferFee;
             item.createdAt = new Date();
@@ -276,6 +276,17 @@ export class StripeReportInvoicer {
             balanceItems.push(item);
         }
 
+        let total = 0;
+        for (const balanceItem of balanceItems) {
+            total += balanceItem.priceWithVAT;
+        }
+        if (total !== applicationFee.amount) {
+            throw new SimpleError({
+                code: 'price_mismatched',
+                message: 'The charged amount does not match the total application fee for the payment',
+            });
+        }
+
         const systemUser = await User.getSystem();
 
         // Done validation

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;