Merge branch 'app-catalogs' of https://github.com/akeneo/pim-api-docs into app-catalogs

Author: meganelepalud-akeneo

content/apps/catalogs.md

@@ -2,13 +2,22 @@
 
 ## Overview
 
+<<<<<<< HEAD
 This guide introduces the catalog feature and explains why using catalogs to retrieve Akeneo data. 
+=======
+This guide introduces the catalog feature. With catalogs, you will save time during development because Akeneo PXM Studio
+will manage your **product selection** and give you direct access to the relevant data.
+With catalogs, you don't need to develop interfaces about filtering products, locales or attributes.
+>>>>>>> e6e4c6c0ebf5c8f6f6d3274d2066a8812d80227a
 
 ### What's a catalog?
 
-With catalogs, Akeneo users can configure which products they want to share with your app thanks to a **product selection** composed of one or several criteria that allow you to filter products. 
+A catalog is a selection of products defined by one or several criteria. (families, categories, ...)
 
-When your app uses catalogs to retrieve product data, it automatically enables the Catalogs tab and creates catalogs in Akeneo.
+Catalogs are only created by apps and are configured by Akeneo users themselves from Akeneo PXM Studio. This feature is
+only visible if the app manage catalogs.
+
+![Catalogs](../img/apps/catalogs-list.png)
 
 ![Catalogs for apps](../img/apps/app-catalog-list.png)
 
@@ -20,6 +29,13 @@ Most of the time, developers must design, develop and maintain a filter interfac
 Using catalogs for apps prevents you from adding this filtering interface to your app. When you retrieve product information related to a catalog, you only retrieve the data your app needs to process. 
 
 Moreover, with catalogs, you don't have to master the entire PIM structure anymore to deliver a relevant filtering interface, as the Akeneo PXM Studio already provides it to your users. 
+![Product Selection](../img/apps/catalogs-product-selection.png)
+
+### Limits
+
+::: warning
+You can only create **up to 15 catalogs** per app.
+:::
 
 ### Next steps
 
@@ -29,6 +45,11 @@ Moreover, with catalogs, you don't have to master the entire PIM structure anymo
 ## Getting started with catalogs
 
 This guide describes how to use the catalog features with your app. 
+<!-- - Discover how users configure catalogs in the Akeneo PXM Studio TODO Add link -->
+
+## Getting started with catalogs
+
+To create and use a catalog, an app must send some requests to the PIM REST API.
 
 ### What you'll learn
 
@@ -38,24 +59,52 @@ After completing this tutorial, you'll be able to create and use catalogs to ret
 
 - You have a Partner account and a developer sandbox.
 - Your app already manages the authorization step
+- You have an app able to use the authorization process.
 
 ### Step 1: Ask for catalog scopes
 
-<!-- TODO -->
+In the documentation [Ask for authorizations](/apps/authentication-and-authorization.html#step-2-ask-for-authorizations), 
+you discovered how to ask for scopes.
+
+If you want to manage catalogs, you need to ask for at least 4 scopes:
+- `read_products`
+- `read_catalogs`
+- `write_catalogs`
+- `delete_catalogs`
+
+Once these scopes are accepted by Akeneo users during the installation of your app, you will be able to manage and use
+catalogs.
 
 ### Step 2: Create catalogs
 
-<!-- TODO -->
+Checkout the [Create a new catalog](/api-reference.html#post_app_catalog) endpoint documentation to find out how
+to create one.
 
 By default, when you create a catalog in the Akeneo PXM Studio, the catalog is disabled. It means that until a user hasn't enabled it, you won't be able to retrieve products for this catalog. Note that only users can enable a catalog. 
+::: info
+You should create a catalog with the more descriptive name possible. It will help your users to know how to configure it.
+:::
 
-::: warning
-You can create **up to 15 catalogs** per app.
-::: 
+Catalogs created **are always disabled by default** in the Akeneo PXM Studio. Only Akeneo users are able to enable a 
+catalog. You must wait for any of your users to enable it before using it.
+
+To help your users, you can give them a link to directly access the catalog configuration interface:
+
+``` http
+
+https://my-pim.cloud.akeneo.com/connect/apps/v1/catalogs/{catalog id}
+```
+
+At any moment, you can verify if the catalog is enabled by calling the [get catalog endpoint](/api-reference.html#get_app_catalog).
 
 ### Step 3: Get products using catalogs
 
-<!-- TODO -->
+::: warning
+The endpoint for retrieving the list of product uuids will be available soon.
+:::
+
+Once you have an enabled catalog, you will be able to paginate the corresponding product uuids using this
+[endpoint](/api-reference.html#Appcatalogproduct).
 
 ### Next steps
 - Learn [how to synchronize Akeneo data](/getting-started/synchronize-pim-products-6x/welcome.html)