From e1a4ab7b84fab192a949d47d1327feabb8d5e0d6 Mon Sep 17 00:00:00 2001 From: Evelyn Fischer Date: Tue, 6 Jun 2023 14:12:52 +0200 Subject: [PATCH] Modified getting started guide, updated products-api.yml --- ...authentication.md => 01_authentication.md} | 0 .../{03_scopes.md => 02_scopes.md} | 0 .../{01_introduction.md => README.md} | 19 ++- 04_products_api/API_error_codes.md | 51 +++++++ 04_products_api/README.md | 128 ++++++++++++++++++ .../products-api.yml | 0 README.md | 29 ++-- references/README.md | 5 - 8 files changed, 213 insertions(+), 19 deletions(-) rename 01_getting-started/{02_authentication.md => 01_authentication.md} (100%) rename 01_getting-started/{03_scopes.md => 02_scopes.md} (100%) rename 01_getting-started/{01_introduction.md => README.md} (66%) create mode 100644 04_products_api/API_error_codes.md create mode 100644 04_products_api/README.md rename {references => 04_products_api}/products-api.yml (100%) delete mode 100644 references/README.md diff --git a/01_getting-started/02_authentication.md b/01_getting-started/01_authentication.md similarity index 100% rename from 01_getting-started/02_authentication.md rename to 01_getting-started/01_authentication.md diff --git a/01_getting-started/03_scopes.md b/01_getting-started/02_scopes.md similarity index 100% rename from 01_getting-started/03_scopes.md rename to 01_getting-started/02_scopes.md diff --git a/01_getting-started/01_introduction.md b/01_getting-started/README.md similarity index 66% rename from 01_getting-started/01_introduction.md rename to 01_getting-started/README.md index 445c283..7d4fec3 100644 --- a/01_getting-started/01_introduction.md +++ b/01_getting-started/README.md @@ -7,10 +7,25 @@ We support secure communication and require client applications to implement TLS With this [endpoint](https://keycloak.apps.otto.de/sec-api/auth/realms/retailapi-prod/.well-known/openid-configuration) for [OAuth 2.0 endpoint discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06) you can use the returned information to obtain details about the OAuth 2.0 authorization server, such as endpoints for token and user information, as well as the supported OAuth 2.0 flows. -The OTTO Retail-API sandbox environment allows API testing without affecting or interacting with your live data. +## Environments + +In order to implement and test the OTTO Retail-API we offer a sandbox environment. Using this sandbox enviroment you can test your implementation without affecting or interacting with your live data. + The base URL for your requests determines whether the request is executed in the production or sandbox environment. + The following base URLs are available for all resources: -* Production base URL: https://retail-api.otto.de * Sandbox environment base URL: https://retail-api-sandbox.otto.de +* Production base URL: https://retail-api.otto.de + +Please only use the production environment AFTER succesfully testing your implementation in the sandbox environment. + +## Authentication + +You can find the information about the authentication [here](01_authentication.md). + +## Scopes + +You can find the information about the different scopes we offer [here](02_scopes.md). + diff --git a/04_products_api/API_error_codes.md b/04_products_api/API_error_codes.md new file mode 100644 index 0000000..98904c7 --- /dev/null +++ b/04_products_api/API_error_codes.md @@ -0,0 +1,51 @@ +# API error codes + +You can find the list of error codes below. + +### Change Log + +| *Date* | *Classification* | *Description* | +|------------|------------------|------------------------------------| +| 2023-06-02 | Documentation | Intial Version of error codes list | + +## List of error codes + +| code | severity | level | description | +|-----------------------------------------------|----------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ATTRIBUTE_IS_UNKNOWN | warning | product / variant | The transmitted attribute is not known. Please only submit attributes that belong to the category group. | +| ATTRIBUTE_LEVEL_IS_INVALID | warning | product / variant | The level at which the attribute was sent is not correct. Either a product attribute was sent at variation level or a variation attribute was sent at product level. Please check and correct the attribute level and resubmit the product data. | +| ATTRIBUTE_UNIT_IS_INVALID | warning | product / variant | The unit of the attribute is invalid. Please check the unit of the attribute and submit the product data again with correct unit. | +| ATTRIBUTE_VALUE_EXCEEDS_MAX_LENGTH | warning | product / variant | The maximum length of the value has been exceeded. Ensure that the length restriction is met and retransmit the affected product or variant. | +| ATTRIBUTE_VALUE_IS_INVALID | warning | product / variant | The attribute value provided is invalid. Please correct the value to one of the allowed values and upload the affected variations again. | +| ATTRIBUTE_VALUE_IS_NOT_BOOLEAN | warning | product / variant | The attribute value is not boolean. Please correct the value to a boolean value and resubmit the product data. | +| ATTRIBUTE_VALUE_IS_NOT_DATE | warning | product / variant | The attribute value does not correspond to the valid data type. Please submit the value as a date in the format YYYY-MM-DD. | +| ATTRIBUTE_VALUE_IS_NOT_DECIMAL | warning | product / variant | The attribute value does not correspond to the valid data type. Correct the format and resubmit the affected variations. A valid input is e.g.: 5391.22. | +| ATTRIBUTE_VALUE_IS_NOT_INTEGER | warning | product / variant | The attribute value does not correspond to the valid data type. Correct the format and resubmit the affected variations. A valid input is e.g.: 42. | +| ATTRIBUTE_VALUE_IS_NOT_POSITIVE | warning | product / variant | The attribute value must not be negative. Please correct the value to one greater than or equal to zero and upload the affected variations again. | +| ATTRIBUTE_VALUE_IS_ZERO | warning | product / variant | The attribute value must not be zero. Please correct the value to a value other than zero and upload the affected variations again. | +| BRAND_ID_IS_UNKNOWN | error | product | The transmitted brand id is not known. Please check the value or contact the support if you want to transmit a new one. | +| CATEGORY_GROUP_ID_IS_UNKNOWN | error | product | The transmitted category group id is not known. A list of valid category group ids can be obtained from the /products/category-groups endpoint. | +| CATEGORY_IS_UNKNOWN | error | product | The transmitted category is not known. Please select a valid category from the list provided for this category group and re-upload the affected product. | +| EAN_IS_INVALID | error | variant | The given EAN is invalid. Please resubmit the data with a valid EAN. | +| EAN_IS_NOT_UNIQUE_WITHIN_PRODUCT | error | product | You have provided one EAN for several variants of the product, however an EAN must be unique for a given variant. Please update the variants. | +| EAN_IS_NOT_UNIQUE_WITHIN_SUPPLIER_CODE | error | product | The given EAN is already in use and may be assigned only once within a supplier. Please update the product which is already assigned with the EAN or contact the support to the delete the existing product. | +| LEGACY_PRODUCT_UPDATE_REQUIRES_ALL_VARIATIONS | error | product | All variations of the product have to be submitted to update this product. Please add the missing variations and re-upload the affected product. | +| LEGACY_SKU_EAN_IS_MISSING | error | product | The ean attribute must be specified for all variations of the product. Please add the EAN attribute, specify a valid EAN and retransmit the affected variations. | +| LEGACY_SKU_IS_ASSOCIATED_TO_DIFFERENT_PRODUCT | error | product | The variation is already associated with another product and cannot be associated with the given product. Please contact support with the code and a list of affected variations. | +| MEDIA_ASSET_FILE_TYPE_IS_NOT_SUPPORTED | warning | variant | The format of the specified media asset is not supported. Please make sure that the URL refers to an image/document in jpg, jpeg, png or pdf format. | +| MEDIA_ASSET_IS_NOT_ACCESSIBLE | warning | variant | The provided media asset cannot be accessed. Please make sure that the URL can be accessed from external services (e.g. no password or internal network protection). | +| MEDIA_ASSET_IS_NOT_AVAILABLE | warning | variant | The given media asset cannot be reached. Please provide a valid URL and upload affected variations again. | +| MEDIA_ASSET_IS_NOT_PROCESSABLE | warning | variant | The given media asset cannot be processed. Please provide a valid URL and upload affected variations again. | +| MEDIA_ASSET_PROTOCOL_IS_UNKNOWN | warning | variant | The provided media asset URI is not supported. Please provide references to media assets as http(s) links only. Other file protocols like (S)FTP are not supported at the moment. | +| MEDIA_ASSET_SIZE_EXCEEDS_LIMIT | warning | variant | Maximum file size exceeded. For media assets of type IMAGE, DIMENSIONAL_DRAWING, ENERGY_EFFICIENCY_LABEL and MATERIAL_SAMPLE there is a file size limit of 25MB. All other types have a file size limit of 10MB. | +| MEDIA_ASSET_TYPE_IS_NOT_SUPPORTED | warning | variant | The specified type value does not correspond to a valid value. Please select a valid value and resubmit the variations. | +| MEDIA_ASSET_URI_IS_INVALID | warning | variant | The media asset URL is invalid. Please provide a syntactically correct URL without any special characters. | +| MISSING_VARIATION_TO_UPDATE_PRODUCT_ATTRIBUTE | error | product | To change characteristics on product level, all variations affected by this have to be re-submitted. Please add the missing variations and re-upload the revised data. | +| PACKING_UNIT_ID_IS_NOT_UNIQUE | error | variant | The packing unit id must be unique within the variation. Assign a unique packing unit id for each packing unit and retransmit affected variations. | +| PERMISSION_IS_MISSING_FOR_SUPPLIER_CODE | error | product | The permission is missing for the specified supplier code. Please correct the supplier code and retransmit the affected product. In case a correction is not possible please contact the support. | +| RECOMMENDED_ATTRIBUTE_IS_MISSING | info | product / variant | A recommended attribute was not submitted. Please provide the attribute to enhance the product data quality. | +| SKU_IS_ASSOCIATED_TO_DIFFERENT_PRODUCT | error | variant | The variation identifier (sku) is already associated to a different product and cannot be associated to the given product. Enter a unique sku and re-upload the affected variations. | +| SKU_IS_NOT_UNIQUE_IN_PRODUCT | error | product | The variation identifier (sku) is already used for this product and must be unique for each variation. Please correct the sku and re-upload the affected variations. | +| SUPPLIER_CODE_IS_NOT_AUTHORIZED | error | product | The supplier code is not authorized to use the API. Use an authorized supplier code or contact the support to authorize the supplier code. | +| SUPPLIER_CODE_IS_UNKNOWN | error | product | The supplier code provided is not known. Please correct the supplier code and retransmit the affected product. In case a correction is not possible please contact the support. | +| UNKNOWN | error | product / variant | An unknown error has occurred. Please try again or contact the support if the error persists. | diff --git a/04_products_api/README.md b/04_products_api/README.md new file mode 100644 index 0000000..0f1520b --- /dev/null +++ b/04_products_api/README.md @@ -0,0 +1,128 @@ +# OTTO Retail-API specifications + +At the moment our API is in a beta version. This means that - although the API is already in a very advanced and stable state - there is still the possibility that different elements of the API might change (path, parameters, return objects etc.) as we are learning from the feedback of our early adaptors. We welcome explicitly early adaptors at this point. + +### Scope + +The API supports the submission of product data including prices, media assets and packing units in production. + +### Known limitations + +Please note that articles where you need to specify material composition such as textiles cannot be send via the API at this time as the API does not yet support the delivery of material compositions. + +### Change Log + +| *Date* | *Classification* | *Description* | +| 2023-06-02 | Documentation | Intial Version of documentation | +| 2023-06-02 | New Version | Initial Version of the api has been released. | + +## Implementing the products API + +To implement the API you need to go through the following steps: + + - Obtain a sandbox client in the OTTO supplier connect + - Implement the API using the sandbox client + - Contact us via the Otto supplier connect helpdesk that you are ready to submit data in production in order to get production clearance + - Obtain the production client in the OTTO supplier connect + - Start submitting your product data + +The specification of the products API can be found [here](products-api.yml). + +### Environments + +We offer a sandbox and a production environment for our API. Please request a client for the sandbox environment and implement and test the API in the sandbox environment BEFORE requesting and using the API in the production environment. The client for the production environment will only be provided when you have successfully submitted data in the sandbox environment. More information about the different environments can be found [here](../01_getting-started/README.md) + +The API as well as the metadata (brands, category groups, ..) that you can retrieve via the API endpoint is identical for both environments, however your submitted product data in the sandbox environments will be deleted regularly as this is used only for testing the API. + +### Authentication + +The information about the authentication can be found [here](../01_getting-started/02_authentication.md) + +## Preparation of product data transfer + +If you want to submit your product data, you will need to follow the following generic process: + + - Step 1: Retrieve the brand id of your product via the *brands* endpoint + - Step 2: Retrieve the category group id for your product category group from the list of category groups via the *category-groups* endpoint. + - Step 3: Retrieve the details (list of category specific attributes) for your category group via the *category-groups* endpoint + +## Submitting product data + +You can then submit your data via the *products* endpoint using the brand id (retrieved via step 1), the category group id (retrieved via step 2) and providing the product data. The product data is composed out of *category specific* (list obtained via step 3) and *category overarching attributes* (can be found in the documentation of the *products* endpoint). + +Please take into account that OTTO is using a two-stage model using products and variants. + +When submitting your product data, you will retrieve a *jobId* together with the *processing status* of your data submission. + +You can then get the status (in process/finished) and result of your upload via the *job* endpoint. + +## Status of your data submission + +The status of your data submission contains information about: + +- The **jobId** of your data submission +- The number of so far **processed** products +- The **total** number of submitted products + +Once the number of so far processed products equals the total number of submitted products, your data submission has been finished. Alternatively you can check if there is a product status left in "IN_PROGRESS" (see below). + +## Result of your data submission + +The result of your data submission as well as the processing details are given either on the product or variant level, depending on its origin. + +On the *product level* you can find the following information for the entire product: + +- The **status** of your submitted *product*: + + | *IN_PROGRESS* | The data submission of the product is still in progress | + | *ACCEPTED* |Your product has been accepted/updated in our system | + | *PARTIALLY_ACCEPTED*| Some of the variants of your product has been accepted/updated but not all due to errors in these variants. Please refer to the result of the individual variants in order to find out which variants were not accepted and for which reasons. | + | *NOT_ACCEPTED* |Your product (and all the related variants) has not been accepted due to errors. Please refer to the details of the product and variants in order to find out the reasons | + +- The **errors**, **warnings** and **infos** for your submitted *product*. + + - Each element is composed out of + - a *title* providing the description of the element + - a *code* to identify the element + - a list of *details* providing more details of the element (e.g. the affected attribute). + - Please see below for the list and explanation of the possible elements. + - All reported elements in the **errors** block lead to a rejection of the entire product. The product will not be created/updated at all. + - All reported elements in the **warnings** block lead to a rejection of the individual attribute: The product will still be created/updated in general, however the individual attribute will not be set or - in case of an update - it will be reset. + - All reported elements in the **infos** block will not affect the data submission and are for information purpose only (e.g. providing information about not yet submitted recommended information) + +On the *variants level* you can find the following information for the individual variant: + +- The **status** of your submitted *product*: + + | *IN_PROGRESS* | The data submission of the variant is still in progress | + | *ACCEPTED* |Your variant has been accepted/updated in our system | + | *NOT_ACCEPTED* |Your variant has not been accepted due to errors. Please refer to the details in order to find out the reasons | + +- The **errors**, **warnings** and **infos** for your submitted *variant*: + + - Each element is composed out of + - a *title* providing the description of the element + - a *code* to identify the element + - a list of *details* providing more details of the element (e.g. the affected attribute). + - Please see below for the list and explanation of the possible elements. + - All elements in the **errors** block lead to a rejection of the entire variant + - All elements in the **warnings** block lead to a rejection of the individual attribute: The variant will be still be created/updated in general, however the individual attribute will not be set or - in case of an update - it will be reset. + - All elements in the **infos** block will not affect the data submission and are for information purpose only (e.g. providing information about not yet submitted recommended information) + +In case of errors or warnings, you can resubmit your data after correcting the errors and warnings. + +## Updating your data + +You can update your product data via the products endpoint in the same way as you submit the data on creation of your products/variants. + +Please take into account the following guidelines when updating your products: + +- The API only supports *full updates*. This means that you always will have to provide the full set of product data for your variant. If you do not specify a product data value in an update, this product data value will be reset for a succesful update. If the update is not succesful, the value will be untouched. + +- If you want to update data on a *product level*, you will always need to submit all variants of the product. Failing to do so will result in an error and a rejection of the data submission. If you only want to update data on a variant level, you can submit individual variants without problems. + +- If you want to update data on a *product level*, you will always need to submit the entire product (with all variants) in one call. Failing to do so will be interpreted as a partial product update and result in an error and a rejection of the data submission. + +## Error handling + +The list of errors, warnings and infos that are given by the API can be found [here](API_error_codes.md). diff --git a/references/products-api.yml b/04_products_api/products-api.yml similarity index 100% rename from references/products-api.yml rename to 04_products_api/products-api.yml diff --git a/README.md b/README.md index e81c395..6dd061b 100644 --- a/README.md +++ b/README.md @@ -4,27 +4,32 @@ Latest published version: [**PDF**](https://github.com/otto-de/retail-api-hub-documentation/releases/download/v1.0.0/otto-retail-api-guidelines.pdf) [**HTML**](https://github.com/otto-de/retail-api-hub-documentation/releases/download/v1.0.0/otto-retail-api-guidelines.html) +### Getting access -## Getting access -The OTTO Retail-API is only available to suppliers with access to OTTO Supplier Connect. -If you are a registered supplier, log into your OTTO Supplier Connect account and request a Retail-API client. -Once your request has been processed, you will receive a client ID and client secret, both of which are required for authentication. +The OTTO Retail-API is only available to suppliers with access to OTTO Supplier Connect. If you are a registered supplier, log into your OTTO Supplier Connect account and request a Retail-API client. Once your request has been processed, you will receive a client ID and client secret, both of which are required for authentication. -If you have any questions, comments or require assistance, please don't hesitate to contact us and we will get back to you as soon as possible. -As a registered supplier, open a new ticket in OTTO Supplier Connect via the Helpdesk and select the subcategory "Retail-API". +If you have any questions, as a registered supplier, open a new ticket in OTTO Supplier Connect via the Helpdesk and select the subcategory "API". -Before you start the implementation, please read the [Getting Started](01_getting-started) guide. +### Getting started -For detailed information on how to use our API, see [About the API](02_about-the-api). +Before you start the implementation, please read the [Getting Started guide](01_getting-started), where you can learn more about the authentication, the different environments and the scopes. -Please also refer to the [OTTO API Guidelines](03_api_guidelines/000_index.md). +### Implementing the API -The OTTO Retail-API specifications can be found in the [References](references) folder. +To implement the API we offer a sandbox environment which you can use to develop and test the API access. As a first step, please request a client for the sandbox environment. Once you have successfully submitted your data in the sandbox environment please request the client for production use in order to submit your data to OTTO. +To implement the API you find all the necessary information in the detailed API Guide: [About the API](04_products_api) -## This repository +### Further information + +Further general information can be found in the [OTTO API Guidelines](03_api_guidelines/000_index.md) and [About the API](02_about-the-api). + +### This repository This repository contains a collection of documents and related materials for the implementation of the OTTO Retail-API. To contribute to this repository, please see the [contribution guidelines](CONTRIBUTING.md). -# License +### License We have published these guidelines under the CC-BY-4.0 (Creative commons Attribution 4.0) license. Please see [LICENSE file](LICENSE). + + + diff --git a/references/README.md b/references/README.md deleted file mode 100644 index 30ae55d..0000000 --- a/references/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# OTTO Retail-API specifications - -## Products API - -The specification of the products API can be found [here](products-api.yml). \ No newline at end of file