Install the Company Business Units Backend API

Last updated:
Edit on GitHub

This document describes how to install the Company Business Units Backend API, which exposes company business unit data at /company-business-units through the Glue Backend application. For the endpoint reference, see Backend API: Manage company business units.

Prerequisites

Install the required features:

NAME VERSION INSTALLATION GUIDE
Spryker Core 202608.0 Install the Spryker Core feature
Company Account 202608.0 Install the Company Account feature
API Platform — Enable API Platform

Step 1 installs the remaining modules the API depends on, so you do not have to install them beforehand.

API Platform is required

The /company-business-units resource is generated by API Platform, which is not enabled in every project. If your project does not serve any API Platform resource on the Glue Backend application yet, complete Enable API Platform first—this guide assumes the Glue Backend application already boots with SprykerApiPlatformBundle registered.

Install feature core

1) Install the required modules

Install the feature using Composer:

composer require spryker-feature/customer-experience-management --update-with-dependencies
Verification

Make sure the following modules have been installed:

MODULE MINIMUM VERSION EXPECTED DIRECTORY
ApiPlatform — vendor/spryker/api-platform
CompanyBusinessUnit — vendor/spryker/company-business-unit
CompanyUnitAddress — vendor/spryker/company-unit-address
CompanyUnitAddressLabel — vendor/spryker/company-unit-address-label
CustomerExperienceManagement — vendor/spryker-feature/customer-experience-management

The feature pins the module versions it needs in its own composer.json, so step 1 resolves them for you. spryker/api-platform comes from enabling API Platform, which is a prerequisite of this guide.

2) Check the API Platform configuration

The resource schema ships inside the installed package, at vendor/spryker-feature/customer-experience-management/resources/api/backend/company-business-units.resource.yml. The generator finds it as long as the Glue Backend application serves the backend API type and scans the directory the feature is installed into.

In config/GlueBackend/packages/spryker_api_platform.php, confirm that apiTypes() includes backend. Leave sourceDirectories() alone unless your project overrides it—the default already covers installed packages. For what both settings do, see Configuration.

Projects that override sourceDirectories

If your project sets sourceDirectories() explicitly, add the directory the feature is installed into rather than replacing the list. Dropping the other entries hides every resource your project already serves.

Also confirm that config/GlueBackend/bundles.php registers SprykerApiPlatformBundle and ApiPlatformBundle. If it does not, your project has not enabled API Platform for the Glue Backend yet—see Enable API Platform.

3) Set up the database schema and transfer objects

Apply the database schema changes and generate the transfer objects:

docker/sdk console transfer:generate
docker/sdk console propel:install
This step adds a column

CompanyBusinessUnit now declares the uuid column on spy_company_business_unit itself, so the Backend API no longer depends on another module to supply it. Projects that already installed the Company Account Glue API or the Company Account + Order Management feature have the column and the migration is a no-op; every other project gains the column here. Until propel:install has run, the API cannot resolve any business unit.

4) Back-fill the business unit UUIDs

The UUID behavior fills uuid when a business unit is saved, so business units that existed before the column was added have an empty uuid and cannot be addressed by the API. Generate the missing values:

docker/sdk console uuid:generate CompanyBusinessUnit spy_company_business_unit
Verification

Make sure every row has a UUID:

select count(*) from spy_company_business_unit where uuid is NULL;

The result must be 0.

5) Generate the API resources

Generate the API resources, then clear the Glue Backend kernel cache:

docker/sdk cli "GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue api:generate"
rm -rf data/cache/GlueBackend/*
Verification

Make sure the generated resource class exists at src/Generated/Api/Backend/CompanyBusinessUnitsBackendResource.php. If it does not, the schema was not discovered—check the sourceDirectories setting from step 2.

Verification

Request a Back Office access token as described in Authenticate as a Back Office user, then retrieve a business unit collection.

Retrieve a business unit collection

curl "https://glue-backend.mysprykershop.com/company-business-units?page[limit]=1" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/vnd.api+json"

The integration is successful when the request returns 200 with a data array and a meta.pagination object.

Create a business unit to confirm the write path:

curl -X POST "https://glue-backend.mysprykershop.com/company-business-units" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"company-business-units","attributes":{"name":"Headquarters","companyUuid":"{company_uuid}"}}}'

The request returns 201 Created with the created business unit.

Troubleshooting

SYMPTOM CAUSE
404 with error code 007 while src/Generated/Api/Backend/CompanyBusinessUnitsBackendResource.php exists The route is unknown to the API Platform kernel, so the Glue router answered instead. The kernel cache is stale—check that you removed the directory that actually exists under data/cache/GlueBackend/, then re-run step 5 in order. The Glue container’s standard error stream names the real cause: docker logs <glue-backend-container> --since 5m 2>&1 | grep -i exception. See API Platform troubleshooting.
404 on /company-business-units and no generated resource class The schema was not discovered. Confirm that spryker/api-platform is installed, and, if your project overrides sourceDirectories(), that it still covers the directory the feature is installed into.
404 with error code 1217 for a business unit you can see in the Back Office That business unit’s uuid is empty. Run step 4, or save the business unit once in the Back Office to have the UUID behavior fill the column.
404 with error code 1213 when creating a business unit The company named by companyUuid was not found, or that company’s uuid column is empty. Companies carry their own uuid, filled by the UUID behavior when the company is saved.
Validation messages come back in English when another language was requested The feature ships its API messages as data/translation/Api/{locale}.csv inside the installed package, keyed by the English message. If they are not loaded, Symfony falls back to the message itself, so the response stays readable and the problem is easy to miss. Send Accept-Language and compare. Loading these files requires a spryker/api-platform version that reads them—update it to the latest version your project supports.