Install the Company Business Unit Addresses Backend API

Last updated:
Edit on GitHub

This document describes how to install the Company Business Unit Addresses Backend API. The API exposes company business unit address data at /company-business-unit-addresses through the Glue Backend application. For the endpoint reference, see Backend API: Manage company business unit addresses.

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 that the API depends on, so you do not have to install them separately.

API Platform is required

The /company-business-unit-addresses 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 is included in the installed package at vendor/spryker-feature/customer-experience-management/resources/api/backend/company-business-unit-addresses.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. Do not change sourceDirectories() unless your project overrides it. The default configuration already covers installed packages. For what both settings do, see Configuration.

Projects that override sourceDirectories

If your project sets sourceDirectories() explicitly, add the directory where the feature is installed instead of replacing the existing 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

CompanyUnitAddress declares the uuid column on spy_company_unit_address, so the Backend API no longer depends on the storefront module that previously provided it. Projects that already installed the Company Account Glue API have the column and the migration is a no-op; every other project gains the column here. Until propel:install has run, the address endpoints cannot filter or resolve addresses by UUID.

4) Back-fill the address UUIDs

The UUID behavior fills uuid when an address is saved, so addresses 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 CompanyUnitAddress spy_company_unit_address
Verification

Verify that every row has a UUID:

select count(*) from spy_company_unit_address 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/CompanyBusinessUnitAddressesBackendResource.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 an address collection.

Retrieve an address collection

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

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

Create an address to confirm the write path:

curl -X POST "https://glue-backend.mysprykershop.com/company-business-unit-addresses" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"company-business-unit-addresses","attributes":{"companyUuid":"{company_uuid}","iso2Code":"DE","street":"Julie-Wolfthorn-Straße","city":"Berlin","zipCode":"10115"}}}'

The request returns 201 Created with the created address.

Troubleshooting

SYMPTOM CAUSE
404 with error code 007 while src/Generated/Api/Backend/CompanyBusinessUnitAddressesBackendResource.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-unit-addresses 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.
The collection returns addresses, but filtering by companyUuid or companyBusinessUnitUuid returns everything The uuid column is missing from spy_company_unit_address, so the repository skips the UUID filter instead of failing. Run step 3.
404 with error code 1227 for an address you can see in the Back Office That address’s uuid is empty. Run step 4, or save the address once in the Back Office to have the UUID behavior fill the column.
422 with error code 1210 for a valid country code The shop does not stock that country. Countries are managed by the Country module; add the country before you use its code.
Validation messages come back in English when another language was requested The feature includes its API messages in data/translation/Api/{locale}.csv inside the installed package. The messages use the English message as the key. 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 the package to the latest version your project supports.