From 8ac1fe1f84e8ad6c2b6aa38df5d9fd47caca84eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karlo=20=C5=A0imunovi=C4=87?= Date: Fri, 17 Apr 2026 15:14:08 +0200 Subject: [PATCH 1/3] Add product libraries management to API documentation This update introduces detailed documentation for managing product libraries within the API. Users can now list, create, retrieve, update, and delete product libraries. - Added endpoints for listing, creating, retrieving, updating, and deleting product libraries - Provided example requests and JSON responses for each operation - Included parameters and response codes for clarity on usage --- source/rest-v2.html.md | 328 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) diff --git a/source/rest-v2.html.md b/source/rest-v2.html.md index 7083b90cddd..318bddcd9d7 100644 --- a/source/rest-v2.html.md +++ b/source/rest-v2.html.md @@ -1138,6 +1138,334 @@ When a collection cannot be deleted because it contains publications, the API re A collection can only be deleted if it contains no publications. +# Product Libraries + +## List all product libraries of a group + +```shell +# This will retrieve all product libraries for a group +curl "https://api.publitas.com/v2/groups/1/product_libraries" \ + -H "Authorization: ApiKey " +``` + +> The above command returns JSON structured like this: + +```json +{ + "product_libraries": [ + { + "id": 1, + "group_id": 1, + "account_id": 10, + "title": "Main Library", + "url": "https://some/feed/file.xml", + "sync_enabled": true, + "sync_hour": 3, + "sync_time_zone": "Europe/Amsterdam", + "hourly_sync_enabled": false, + "integration_instance_id": null, + "external_id": null, + "created_at": "2026-04-01T10:00:00Z", + "updated_at": "2026-04-10T12:00:00Z", + "last_import": { + "id": 42, + "state": "success", + "success_count": 1891, + "failed_count": 0, + "created_at": "2026-04-10T12:00:00Z" + } + } + ] +} +``` + +### HTTP Request + +`GET https://api.publitas.com/v2/groups//product_libraries` + +### URL Parameters + +| Parameter | Description | +| --------- | -------------------------- | +| Group ID | The ID of a specific group | + +### Query Parameters + +See the [Pagination](#pagination) section for pagination parameters. + +The JSON response returns a list of product libraries with the following attributes: + +| Field | Type | Description | +| ----------------------- | ------- | --------------------------------------------------------------------------------------- | +| id | Integer | Product Library ID | +| group_id | Integer | ID of the group this product library belongs to | +| account_id | Integer | ID of the account this product library belongs to | +| title | String | Product Library title | +| url | String | URL of the product feed file backing this library | +| sync_enabled | Boolean | Whether scheduled sync is enabled | +| sync_hour | Integer | Hour of the day (0-23) at which the daily sync runs | +| sync_time_zone | String | Time zone in which `sync_hour` is interpreted (IANA identifier, e.g. `Europe/Amsterdam`) | +| hourly_sync_enabled | Boolean | Whether the library is synced every hour | +| integration_instance_id | Integer | ID of the integration instance backing this library, or `null` if none | +| external_id | String | External identifier for libraries that are synced from an external system | +| created_at | String | ISO 8601 timestamp of creation | +| updated_at | String | ISO 8601 timestamp of last update | +| last_import | Object | Summary of the most recent import, or `null` if the library has never been imported | + +The `last_import` object has the following attributes: + +| Field | Type | Description | +| ------------- | ------- | -------------------------------------------------------------- | +| id | Integer | Import ID | +| state | String | Import state (`processing`, `success`, `failed`) | +| success_count | Integer | Number of products successfully imported | +| failed_count | Integer | Number of products that failed to import | +| created_at | String | ISO 8601 timestamp at which the import was created | + +## Get a specific product library + +```shell +# This endpoint retrieves a specific product library. +curl "https://api.publitas.com/v2/groups/1/product_libraries/1" \ + -H "Authorization: ApiKey " +``` + +> The above command returns JSON structured like this: + +```json +{ + "product_library": { + "id": 1, + "group_id": 1, + "account_id": 10, + "title": "Main Library", + "url": "https://some/feed/file.xml", + "sync_enabled": true, + "sync_hour": 3, + "sync_time_zone": "Europe/Amsterdam", + "hourly_sync_enabled": false, + "integration_instance_id": null, + "external_id": null, + "created_at": "2026-04-01T10:00:00Z", + "updated_at": "2026-04-10T12:00:00Z", + "last_import": { + "id": 42, + "state": "success", + "success_count": 1891, + "failed_count": 0, + "created_at": "2026-04-10T12:00:00Z" + } + } +} +``` + +### HTTP Request + +`GET https://api.publitas.com/v2/groups//product_libraries/` + +### URL Parameters + +| Parameter | Description | +| ------------------ | ------------------------------------ | +| Group ID | The ID of a specific group | +| Product Library ID | The ID of a specific product library | + +## Create a product library + +### HTTP Request + +`POST https://api.publitas.com/v2/groups//product_libraries` + +### URL Parameters + +| Parameter | Description | +| --------- | -------------------------- | +| Group ID | The ID of a specific group | + +```shell +curl "https://api.publitas.com/v2/groups/1/product_libraries" \ + -H "Authorization: ApiKey " \ + -H "Content-Type: application/json" \ + --data '{ + "product_library": { + "title": "Main Library", + "url": "https://some/feed/file.xml", + "sync_enabled": true, + "sync_hour": 3, + "sync_time_zone": "Europe/Amsterdam" + } + }' +``` + +> The above command returns JSON structured like this: + +```json +{ + "product_library": { + "id": 1, + "group_id": 1, + "account_id": 10, + "title": "Main Library", + "url": "https://some/feed/file.xml", + "sync_enabled": true, + "sync_hour": 3, + "sync_time_zone": "Europe/Amsterdam", + "hourly_sync_enabled": false, + "integration_instance_id": null, + "external_id": null, + "created_at": "2026-04-13T16:12:08Z", + "updated_at": "2026-04-13T16:12:08Z", + "last_import": null + } +} +``` + +Creating a product library schedules an initial import of its product feed. + +### Request body parameters + +The following fields need to be sent within a product_library scope (see the right panel for an example): + +| Name | Type | Required | Description | +| ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------ | +| title | String | Yes | Product Library title | +| url | String | No | URL of the product feed file. HTTP, HTTPS, FTP and SFTP are accepted | +| sync_enabled | Boolean | No | Whether scheduled sync is enabled | +| sync_hour | Integer | No | Hour of the day (0-23) at which the daily sync runs | +| sync_time_zone | String | No | Time zone in which `sync_hour` is interpreted (IANA identifier) | +| hourly_sync_enabled | Boolean | No | Whether the library is synced every hour | +| integration_instance_id | Integer | No | ID of the integration instance to back this library, instead of a `url` | + +### Response codes + +This endpoint returns the `201` response code on success. + +## Update a product library + +```shell +# This will update a product library's title and URL. +curl "https://api.publitas.com/v2/groups/1/product_libraries/1" \ + -H "Authorization: ApiKey " \ + -H "Content-Type: application/json" \ + -X PUT \ + --data '{ + "product_library": { + "title": "Updated Title", + "url": "https://some/new/feed.xml" + } + }' +``` + +> The above command returns JSON structured like this: + +```json +{ + "product_library": { + "id": 1, + "group_id": 1, + "account_id": 10, + "title": "Updated Title", + "url": "https://some/new/feed.xml", + "sync_enabled": true, + "sync_hour": 3, + "sync_time_zone": "Europe/Amsterdam", + "hourly_sync_enabled": false, + "integration_instance_id": null, + "external_id": null, + "created_at": "2026-04-13T16:12:08Z", + "updated_at": "2026-04-14T09:30:00Z", + "last_import": { + "id": 42, + "state": "success", + "success_count": 1891, + "failed_count": 0, + "created_at": "2026-04-10T12:00:00Z" + } + } +} +``` + +### HTTP Request + +`PUT https://api.publitas.com/v2/groups//product_libraries/` + +### URL Parameters + +| Parameter | Description | +| ------------------ | ---------------------------------------- | +| Group ID | The ID of a specific group | +| Product Library ID | The ID of the product library to update | + +### Request body parameters + +The following fields need to be sent within a product_library scope (see the right panel for an example): + +| Name | Type | Required | Description | +| ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------ | +| title | String | No | Product Library title | +| url | String | No | URL of the product feed file. HTTP, HTTPS, FTP and SFTP are accepted | +| sync_enabled | Boolean | No | Whether scheduled sync is enabled | +| sync_hour | Integer | No | Hour of the day (0-23) at which the daily sync runs | +| sync_time_zone | String | No | Time zone in which `sync_hour` is interpreted (IANA identifier) | +| hourly_sync_enabled | Boolean | No | Whether the library is synced every hour | +| integration_instance_id | Integer | No | ID of the integration instance to back this library, instead of a `url` | + +Updating `url` or `integration_instance_id` schedules a new import of the library. + +## Delete a product library + +### HTTP Request + +`DELETE https://api.publitas.com/v2/groups//product_libraries/` + +### URL Parameters + +| Parameter | Description | +| ------------------ | ---------------------------------------- | +| Group ID | The ID of a specific group | +| Product Library ID | The ID of the product library to delete | + +```shell +curl -X DELETE "https://api.publitas.com/v2/groups/1/product_libraries/1" \ + -H "Authorization: ApiKey " +``` + +### Response codes + +| Code | Description | +| ---- | ------------------------------------------------------- | +| 204 | No Content - Product library successfully deleted | +| 403 | Forbidden - Invalid API key or insufficient permissions | +| 404 | Not Found - Product library does not exist | + +## Sync a product library + +Triggers an on-demand import of a product library's feed. The import runs asynchronously; poll the library's `last_import` to track progress. + +### HTTP Request + +`POST https://api.publitas.com/v2/groups//product_libraries//sync` + +### URL Parameters + +| Parameter | Description | +| ------------------ | -------------------------------------- | +| Group ID | The ID of a specific group | +| Product Library ID | The ID of the product library to sync | + +```shell +curl -X POST "https://api.publitas.com/v2/groups/1/product_libraries/1/sync" \ + -H "Authorization: ApiKey " +``` + +### Response codes + +| Code | Description | +| ---- | ------------------------------------------------------- | +| 202 | Accepted - Import scheduled | +| 403 | Forbidden - Invalid API key or insufficient permissions | +| 404 | Not Found - Product library does not exist | + # Pages ## Add pages to publication From d0fd0b283c897688856f5edb048c0ff55d5bba03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karlo=20=C5=A0imunovi=C4=87?= Date: Fri, 17 Apr 2026 15:20:02 +0200 Subject: [PATCH 2/3] Add notice for product libraries unavailability Include a notice in the documentation to inform users that all endpoints in the Product Libraries section will return a `422 Unprocessable Entity` error if product libraries are not available for the group. - Enhances error handling transparency for users - Clarifies the conditions under which a failure occurs --- source/rest-v2.html.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/rest-v2.html.md b/source/rest-v2.html.md index 318bddcd9d7..f6cca75f8d3 100644 --- a/source/rest-v2.html.md +++ b/source/rest-v2.html.md @@ -1140,6 +1140,10 @@ A collection can only be deleted if it contains no publications. # Product Libraries + + ## List all product libraries of a group ```shell From 616926c65c563da37ff63fa3b2a0b2db1e186503 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karlo=20=C5=A0imunovi=C4=87?= Date: Tue, 21 Apr 2026 14:35:49 +0200 Subject: [PATCH 3/3] Update external_id type to Integer in response schema The type of the `external_id` attribute in the JSON response has been changed from String to Integer. This change ensures consistency with the data type used in external systems and improves data validation during integration. - Reflects correct data type for external identifiers - Enhances data integrity across the integration process --- source/rest-v2.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/rest-v2.html.md b/source/rest-v2.html.md index f6cca75f8d3..f1a725c27de 100644 --- a/source/rest-v2.html.md +++ b/source/rest-v2.html.md @@ -1211,7 +1211,7 @@ The JSON response returns a list of product libraries with the following attribu | sync_time_zone | String | Time zone in which `sync_hour` is interpreted (IANA identifier, e.g. `Europe/Amsterdam`) | | hourly_sync_enabled | Boolean | Whether the library is synced every hour | | integration_instance_id | Integer | ID of the integration instance backing this library, or `null` if none | -| external_id | String | External identifier for libraries that are synced from an external system | +| external_id | Integer | External identifier for libraries that are synced from an external system | | created_at | String | ISO 8601 timestamp of creation | | updated_at | String | ISO 8601 timestamp of last update | | last_import | Object | Summary of the most recent import, or `null` if the library has never been imported |