From e45dd72d23a698f19c9c533305b6354bd1a1ee02 Mon Sep 17 00:00:00 2001 From: Olha Livitchuk Date: Wed, 9 Sep 2026 15:56:24 +0200 Subject: [PATCH] CC-40120 Glossary Backend API --- _data/sidebars/pbc_all_sidebar.yml | 9 + ...ossary-keys-backend-response-attributes.md | 6 + .../backend-api-create-a-glossary-key.md | 127 +++++++++++ .../backend-api-retrieve-glossary-keys.md | 205 ++++++++++++++++++ ...i-update-translations-of-a-glossary-key.md | 134 ++++++++++++ 5 files changed, 481 insertions(+) create mode 100644 _includes/pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md create mode 100644 docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.md create mode 100644 docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.md create mode 100644 docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.md diff --git a/_data/sidebars/pbc_all_sidebar.yml b/_data/sidebars/pbc_all_sidebar.yml index 9157e403e51..496b9241446 100644 --- a/_data/sidebars/pbc_all_sidebar.yml +++ b/_data/sidebars/pbc_all_sidebar.yml @@ -1751,6 +1751,15 @@ entries: - title: Add push notification subscriptions url: /docs/pbc/all/miscellaneous/manage-using-glue-api/glue-api-add-push-notification-subscriptions.html + - title: Manage glossary keys via Backend API + nested: + - title: Retrieve glossary keys + url: /docs/pbc/all/miscellaneous/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.html + - title: Create a glossary key + url: /docs/pbc/all/miscellaneous/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.html + - title: Update translations of a glossary key + url: /docs/pbc/all/miscellaneous/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.html + - title: Third-party integrations nested: - title: Customer service diff --git a/_includes/pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md b/_includes/pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md new file mode 100644 index 00000000000..3a79d1e3836 --- /dev/null +++ b/_includes/pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md @@ -0,0 +1,6 @@ +| ATTRIBUTE | TYPE | DESCRIPTION | +| --- | --- | --- | +| key | String | Unique key of the glossary entry. It is also the resource `id`. | +| translations | Array | Translations of the key, one entry per configured locale, ordered by `localeName`. The list is always complete: a locale without an active translation is included with `value: null`. | +| translations.localeName | String | Locale name—for example, `en_US`. | +| translations.value | String | Translated text in the locale. `null` when the key has no active translation in the locale. | diff --git a/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.md b/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.md new file mode 100644 index 00000000000..3e144163e25 --- /dev/null +++ b/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.md @@ -0,0 +1,127 @@ +--- +title: "Backend API: Create a glossary key" +description: Learn how to create glossary keys with translations in one or several locales using the Spryker Backend API. +last_updated: Sep 9, 2026 +template: default +related: + - title: Authenticate as a Back Office user + link: docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html + - title: Retrieve glossary keys + link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.html + - title: Update translations of a glossary key + link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.html + - title: Add translations in the Back Office + link: docs/pbc/all/miscellaneous/latest/manage-in-the-back-office/add-translations.html +--- + +The `glossary-keys` resource of the Backend API lets Back Office integrations create glossary keys together with their translations. This document describes how to create a glossary key and which validations the request has to pass. + +## Installation + +The endpoints are provided by the `Glossary` module. For details on installing it, see [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html). + +## Create a glossary key + +To create a glossary key, send the request: + +--- +`POST` **/glossary-keys** + +--- + +### Request + +| HEADER KEY | HEADER VALUE | REQUIRED | DESCRIPTION | +| --- | --- | --- | --- | +| Authorization | string | ✓ | Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by [authenticating as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html). | + +Request sample: create a glossary key with translations in two locales + +`POST https://glue-backend.mysprykershop.com/glossary-keys` + +```json +{ + "data": { + "type": "glossary-keys", + "attributes": { + "key": "general.newsletter.hint", + "translations": [ + { + "localeName": "en_US", + "value": "Subscribe to our newsletter" + }, + { + "localeName": "de_DE", + "value": "Abonnieren Sie unseren Newsletter" + } + ] + } + } +} +``` + +| ATTRIBUTE | TYPE | REQUIRED | DESCRIPTION | +| --- | --- | --- | --- | +| key | String | ✓ | Unique glossary key, up to 255 characters. It becomes the resource `id` and cannot be changed later. Keys are matched case-insensitively, so a key that differs from an existing one only by case is rejected as a duplicate. | +| translations | Array | | Translations of the key. Provide any subset of the configured locales; each `localeName` can appear once. Omit the attribute or send an empty array to create the key without translations. | +| translations.localeName | String | ✓ | Name of a configured locale—for example, `en_US`. | +| translations.value | String | ✓ | Translated text in the locale. Must be a non-empty string. | + +{% info_block infoBox "Locales without a translation" %} + +You can create a key with translations in a subset of the configured locales. The locales you omit are returned with `value: null`, and the key is not translated in those locales until you [add the translations](/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.html). + +{% endinfo_block %} + +### Response + +The response contains the created glossary key with one `translations` entry per configured locale. + +
+Response sample: create a glossary key + +```json +{ + "data": { + "id": "general.newsletter.hint", + "type": "glossary-keys", + "attributes": { + "key": "general.newsletter.hint", + "translations": [ + { + "localeName": "de_DE", + "value": "Abonnieren Sie unseren Newsletter" + }, + { + "localeName": "en_US", + "value": "Subscribe to our newsletter" + } + ] + }, + "links": { + "self": "https://glue-backend.mysprykershop.com/glossary-keys/general.newsletter.hint" + } + } +} +``` + +
+ +{% include /pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md %} + +## Possible errors + +The request is validated as a whole: if any check fails, nothing is created and all failed checks are returned in the `errors` array. + +| STATUS | CODE | REASON | +| --- | --- | --- | +| 422 | 901 | A required attribute is missing, is blank, or has a wrong type—for example, `key => This value should not be blank.` or `translations.0.value => This value should not be blank.` | +| 422 | N/A | A glossary key with the specified `key` already exists. Keys are compared case-insensitively. | +| 422 | N/A | A locale specified in `translations` is not configured, or an entry has no `localeName`. | +| 422 | N/A | A `localeName` appears more than once in `translations`. | +| 422 | N/A | A `value` in `translations` is `null`. When creating a key, every listed locale needs a translated text; to create the key without a translation in a locale, omit that locale. | + +| 401 | N/A | The `Authorization` header is missing, or the access token is invalid or expired. | +| 403 | N/A | The authenticated Back Office user is not allowed to access the `glossary-keys` resource. | + +To view generic errors and status codes of the Backend API, see [Backend API request and response reference](/docs/integrations/spryker-api/backend-api/developing-apis/backend-api-request-and-response-reference.html#http-status-codes). diff --git a/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.md b/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.md new file mode 100644 index 00000000000..6fd7eb9bae9 --- /dev/null +++ b/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.md @@ -0,0 +1,205 @@ +--- +title: "Backend API: Retrieve glossary keys" +description: Learn how to retrieve the glossary key collection and single glossary keys with their translations, and how to paginate, sort, and filter them using the Spryker Backend API. +last_updated: Sep 9, 2026 +template: default +related: + - title: Authenticate as a Back Office user + link: docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html + - title: Create a glossary key + link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.html + - title: Update translations of a glossary key + link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.html + - title: Manage translations in the Back Office + link: docs/pbc/all/miscellaneous/latest/manage-in-the-back-office/manage-translations-in-the-back-office.html +--- + +The `glossary-keys` resource of the Backend API lets Back Office integrations read glossary keys and their translations. This document describes how to retrieve a paginated glossary key collection and a single glossary key. + +## Installation + +The endpoints are provided by the `Glossary` module. For details on installing it, see [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html). + +## Retrieve glossary keys + +To retrieve a paginated collection of glossary keys, send the request: + +--- +`GET` **/glossary-keys** + +--- + +### Request + +| HEADER KEY | HEADER VALUE | REQUIRED | DESCRIPTION | +| --- | --- | --- | --- | +| Authorization | string | ✓ | Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by [authenticating as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html). | + +| QUERY PARAMETER | DESCRIPTION | EXEMPLARY VALUES | +| --- | --- | --- | +| page[limit] | Number of glossary keys per page. Default: `10`, maximum: `100`. A higher value is reduced to the maximum. | `page[limit]=20` | +| page[offset] | Number of glossary keys to skip. Default: `0`. | `page[offset]=20` | +| sort | Sorts the collection by a field. Prefix the field with `-` for descending order. The only supported field is `key`; the collection is sorted by `key` in ascending order by default. Any other field returns a `400` error. | `sort=key`
`sort=-key` | +| filter[glossary-keys.key] | Returns only the glossary keys that contain the specified fragment. The fragment is matched case-insensitively. | `filter[glossary-keys.key]=general.` | +| filter[glossary-keys.value] | Returns only the glossary keys that have at least one active translation, in any locale, containing the specified fragment. The fragment is matched case-insensitively. Removed translations are not matched. | `filter[glossary-keys.value]=Weiter` | + +When both filters are provided, a glossary key has to match both of them. + +| REQUEST | USAGE | +| --- | --- | +| `GET https://glue-backend.mysprykershop.com/glossary-keys` | Retrieve the first page of the glossary key collection. | +| `GET https://glue-backend.mysprykershop.com/glossary-keys?page[limit]=2&page[offset]=2` | Retrieve the second page of the collection with two glossary keys per page. | +| `GET https://glue-backend.mysprykershop.com/glossary-keys?sort=-key` | Retrieve glossary keys sorted by key in descending order. | +| `GET https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.` | Retrieve glossary keys containing `general.`. | +| `GET https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.value]=Weiter` | Retrieve glossary keys with an active translation containing `Weiter` in any locale. | +| `GET https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=button&filter[glossary-keys.value]=Next` | Retrieve glossary keys containing `button` that have an active translation containing `Next`. | + +### Response + +The pagination summary is returned in the top-level `meta.pagination` object, and the pagination links in the top-level `links` object. Collection members do not carry pagination data. + +Every glossary key carries one `translations` entry per configured locale, even when a filter matched the key by one of its translations only. + +
+Response sample: retrieve glossary keys + +```json +{ + "links": { + "self": "https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.", + "first": "https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.&page[limit]=2&page[offset]=0", + "last": "https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.&page[limit]=2&page[offset]=60", + "next": "https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.&page[limit]=2&page[offset]=2" + }, + "meta": { + "pagination": { + "numFound": 61, + "currentPage": 1, + "maxPage": 31, + "currentItemsPerPage": 2 + } + }, + "data": [ + { + "id": "general.back", + "type": "glossary-keys", + "attributes": { + "key": "general.back", + "translations": [ + { + "localeName": "de_DE", + "value": "Zurück" + }, + { + "localeName": "en_US", + "value": "Back" + } + ] + }, + "links": { + "self": "https://glue-backend.mysprykershop.com/glossary-keys/general.back" + } + }, + { + "id": "general.next.button", + "type": "glossary-keys", + "attributes": { + "key": "general.next.button", + "translations": [ + { + "localeName": "de_DE", + "value": "Weiter" + }, + { + "localeName": "en_US", + "value": "Next" + } + ] + }, + "links": { + "self": "https://glue-backend.mysprykershop.com/glossary-keys/general.next.button" + } + } + ] +} +``` + +
+ +| META ATTRIBUTE | TYPE | DESCRIPTION | +| --- | --- | --- | +| pagination.numFound | Integer | Total number of glossary keys in the collection. | +| pagination.currentPage | Integer | Number of the current page. | +| pagination.maxPage | Integer | Total number of pages. | +| pagination.currentItemsPerPage | Integer | Number of glossary keys per page. | + +{% include /pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md %} + +## Retrieve a glossary key + +To retrieve a single glossary key with its translations, send the request: + +--- +`GET` **/glossary-keys/*{% raw %}{{key}}{% endraw %}*** + +--- + +| PATH PARAMETER | DESCRIPTION | +| --- | --- | +| {% raw %}***{{key}}***{% endraw %} | Glossary key to retrieve. The key is matched case-insensitively; the response contains the stored key. To get it, [retrieve glossary keys](#retrieve-glossary-keys). | + +### Request + +| HEADER KEY | HEADER VALUE | REQUIRED | DESCRIPTION | +| --- | --- | --- | --- | +| Authorization | string | ✓ | Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by [authenticating as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html). | + +Request sample: retrieve a glossary key + +`GET https://glue-backend.mysprykershop.com/glossary-keys/general.next.button` + +### Response + +
+Response sample: retrieve a glossary key + +```json +{ + "data": { + "id": "general.next.button", + "type": "glossary-keys", + "attributes": { + "key": "general.next.button", + "translations": [ + { + "localeName": "de_DE", + "value": "Weiter" + }, + { + "localeName": "en_US", + "value": "Next" + } + ] + }, + "links": { + "self": "https://glue-backend.mysprykershop.com/glossary-keys/general.next.button" + } + } +} +``` + +
+ +{% include /pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md %} + +## Possible errors + +| STATUS | CODE | REASON | +| --- | --- | --- | +| 400 | 400 | The `sort` parameter references an unsupported field. The supported fields are listed in the error details. | +| 404 | N/A | The glossary key with the specified key doesn't exist. | + +| 401 | N/A | The `Authorization` header is missing, or the access token is invalid or expired. | +| 403 | N/A | The authenticated Back Office user is not allowed to access the `glossary-keys` resource. | + +To view generic errors and status codes of the Backend API, see [Backend API request and response reference](/docs/integrations/spryker-api/backend-api/developing-apis/backend-api-request-and-response-reference.html#http-status-codes). diff --git a/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.md b/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.md new file mode 100644 index 00000000000..e4bf9b262b8 --- /dev/null +++ b/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.md @@ -0,0 +1,134 @@ +--- +title: "Backend API: Update translations of a glossary key" +description: Learn how to add, change, and remove translations of a glossary key in one or several locales using the Spryker Backend API. +last_updated: Sep 9, 2026 +template: default +related: + - title: Authenticate as a Back Office user + link: docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html + - title: Retrieve glossary keys + link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.html + - title: Create a glossary key + link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.html + - title: Edit translations in the Back Office + link: docs/pbc/all/miscellaneous/latest/manage-in-the-back-office/edit-translations.html +--- + +The `glossary-keys` resource of the Backend API lets Back Office integrations manage the translations of existing glossary keys. This document describes how to add, change, and remove translations of a glossary key. + +## Installation + +The endpoints are provided by the `Glossary` module. For details on installing it, see [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html). + +## Update translations of a glossary key + +To update the translations of a glossary key, send the request: + +--- +`PATCH` **/glossary-keys/*{% raw %}{{key}}{% endraw %}*** + +--- + +| PATH PARAMETER | DESCRIPTION | +| --- | --- | +| {% raw %}***{{key}}***{% endraw %} | Glossary key to update. The key is matched case-insensitively. To get it, [retrieve glossary keys](/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.html#retrieve-glossary-keys). | + +### Request + +| HEADER KEY | HEADER VALUE | REQUIRED | DESCRIPTION | +| --- | --- | --- | --- | +| Authorization | string | ✓ | Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by [authenticating as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html). | + +The update is partial and works per locale. `translations` entries are merged by `localeName`: locales you omit stay untouched, and each entry you send is applied as follows: + +- A non-empty `value` creates the translation of the locale, or overwrites the existing one. A previously removed translation becomes active again. +- `value: null` removes the translation of the locale. The translation is unpublished from the Storefront and is returned as `value: null` afterwards. The glossary key itself is kept. +- An empty string is rejected. + +You can send one or several locales in one request, and combine additions and removals. + +Request sample: change the German translation and remove the English one + +`PATCH https://glue-backend.mysprykershop.com/glossary-keys/general.newsletter.hint` + +```json +{ + "data": { + "type": "glossary-keys", + "id": "general.newsletter.hint", + "attributes": { + "translations": [ + { + "localeName": "de_DE", + "value": "Jetzt Newsletter abonnieren" + }, + { + "localeName": "en_US", + "value": null + } + ] + } + } +} +``` + +| ATTRIBUTE | TYPE | REQUIRED | DESCRIPTION | +| --- | --- | --- | --- | +| translations | Array | ✓ | Translations to apply, merged by `localeName`. Each `localeName` can appear once. | +| translations.localeName | String | ✓ | Name of a configured locale—for example, `en_US`. | +| translations.value | String | ✓ | New translated text in the locale, or `null` to remove the translation. Must not be an empty string. | + +`key` cannot be changed. + +### Response + +The response contains the updated glossary key with one `translations` entry per configured locale, including the locales you didn't send. + +
+Response sample: update translations of a glossary key + +```json +{ + "data": { + "id": "general.newsletter.hint", + "type": "glossary-keys", + "attributes": { + "key": "general.newsletter.hint", + "translations": [ + { + "localeName": "de_DE", + "value": "Jetzt Newsletter abonnieren" + }, + { + "localeName": "en_US", + "value": null + } + ] + }, + "links": { + "self": "https://glue-backend.mysprykershop.com/glossary-keys/general.newsletter.hint" + } + } +} +``` + +
+ +{% include /pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md %} + +## Possible errors + +The request is validated as a whole: if any check fails, nothing is updated and all failed checks are returned in the `errors` array. + +| STATUS | CODE | REASON | +| --- | --- | --- | +| 404 | N/A | The glossary key with the specified key doesn't exist. | +| 422 | 901 | An attribute has a wrong type, or a `value` is an empty string—for example, `translations.0.value => This value is too short. It should have 1 character or more.` | +| 422 | N/A | `key` differs from the key of the glossary key. The key cannot be changed. | +| 422 | N/A | A locale specified in `translations` is not configured, or an entry has no `localeName`. | +| 422 | N/A | A `localeName` appears more than once in `translations`. | + +| 401 | N/A | The `Authorization` header is missing, or the access token is invalid or expired. | +| 403 | N/A | The authenticated Back Office user is not allowed to access the `glossary-keys` resource. | + +To view generic errors and status codes of the Backend API, see [Backend API request and response reference](/docs/integrations/spryker-api/backend-api/developing-apis/backend-api-request-and-response-reference.html#http-status-codes).