Retrieve Documents and Options

Now that you have the catalog hierarchy, the (previously stored) document codes are used to retrieve the data of interest.

In this case, it's documents with their:

attributes,
variants,
assets, and
related documents.

📘
Reminder
The previous calls retrieved all (or a single) classification hierarchy structures from the channel and:

all related attributes

all related assets with their attributes

all related documents (the document codes will have been stamped)

Endpoints

/documents

From here, you can request:

all documents
all documents for one or more completeness codes (e.g., to filter on complete documents)
all documents for one or more tags (statuses or workflow steps) codes
a single document
a specific list of documents

Supported methods: GET - returns the documents of a classification.

Example

import requests

url = "https://{{instance}}.quable.com/api_1.php/documents?limit=10&page=2"

payload={}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{token}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response

HTTP Header

200

JSON Body

success

true if all went well, otherwise false

response

An array of documents with additional elements. The response returns an array with all data for:

Field	Description
`fields`	All attributes with their values.
`completeness`	All completeness codes and their ratios.
`tags`	All assigned workflow steps or statuses.
`attribute set`	The attribute set used, if any.
`assets`	All assets.
`variants`	All variants.
`created_at` / `updated_at`	The date and time of creation and the last update.
`created_by` / `updated_by`	The user who performed the creation / update.

Example Response

{
    "links": {
        "first": "https://{{instance}}.quable.com/api_1.php/documents?page=1&limit=10&target_culture=en_GB&document_type_code=&parent_documents=0&target_documents=0&medias_included=1&media_fields_included=0&updated_at_min=",
        "last": "https://{{instance}}.quable.com/api_1.php/documents?page=3750&limit=10&target_culture=en_GB&document_type_code=&parent_documents=0&target_documents=0&medias_included=1&media_fields_included=0&updated_at_min=",
        "prev": "https://{{instance}}.quable.com/api_1.php/documents?page=1&limit=10&target_culture=en_GB&document_type_code=&parent_documents=0&target_documents=0&medias_included=1&media_fields_included=0&updated_at_min=",
        "next": "https://{{instance}}.quable.com/api_1.php/documents?page=3&limit=10&target_culture=en_GB&document_type_code=&parent_documents=0&target_documents=0&medias_included=1&media_fields_included=0&updated_at_min="
    },
    "data": [
        {
            "id": 1369,
            "code": "SHJH897876",
            "type": "document",
            "document_type": "modelColor",
            "active": true,
            "attribute_set": {
                "code": "shoe",
                "label": "Shoe",
                "links": [
                    {
                        "rel": "self",
                        "href": "https://{{instance}}.quable.com/api_1.php/attribute_sets/1577"
                    }
                ]
            },
            "fields": {
                "modelColor_name": "WHITE BOOT",
                "vat_rate": 20,
                "supplier_ref": "5198 PVC/NITRIL",
                "family": "INDIVIDUAL PROTECTION",
                "ecommerce_display": false
            },
            "completeness": {
                "ecommerce": {
                    "en_GB": {
                        "ratio": 1,
                        "success": true
                    },
                    "fr_FR": {
                        "ratio": 0.35,
                        "success": false
                    }
                },
                "internal_portal": {
                    "en_GB": {
                        "ratio": 1,
                        "success": true
                    },
                    "fr_FR": {
                        "ratio": 1,
                        "success": true
                    }
                }
            },
            "tags": [
                "video_required",
                "erp_ready"
            ],
            "medias": [{
                "main_pictures": [
                    {
                        "id": 62987,
                        "name": "white boot Front",
                        "code": "white_boot_001",
                        "type": "image/tiff",
                        "active": true,
                        "created_at": "2020-12-10 11:06:55",
                        "updated_at": "2020-12-21 15:57:45",
                        "source": "white_boot_001.tiff",
                        "links": [
                            {
                                "rel": "self",
                                "href": "https://{{instance}}.quable.com/api_1.php/assets/white_boot_001"
                            },
                            {
                                "rel": "thumbnail",
                                "href": "https://cdn.quable.com/{{instance}}/white_boot_001/600x600/white_boot_001.png"
                            },
                            {
                                "rel": "source",
                                "href": "https://cdn.quable.com/{{instance}}/white_boot_001/original/white_boot_001.tiff"
                            }
                        ]
                    }
                ]
            }],
            "variants": [
                {
                    "id": 617,
                    "code": "SHJH897876.XL",
                    "active": true,
                    "fields": {
                        "size": "XL",
                        "GTIN" : "07865433478980AZ8979",
                        "EAN" : "0987656865432"
                    },
                    "links": {
                        "rel": "self",
                        "href": "https://{{instance}}.quable.com/api_1.php/variants/AZAOI767.001"
                    },
                    "medias": []
                }
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "https://{{instance}}.quable.com/api_1.php/documents/SHJH897876"
                },
                {
                    "rel": "tree",
                    "href": "https://{{instance}}.quable.com/api_1.php/classifications/329"
                }
            ],
            "created_at": "2019-03-08 17:11:22",
            "updated_at": "2021-01-06 16:22:15",
            "created_by": "",
            "updated_by": {
                "id": 10,
                "username": "john.doz"
            }
        },
        {
            "id": 1370,
            "code": "39610",
            "type": "document",
            "document_type": "model",
            "active": true
        }
    ],
    "count": "1231",
    "included": []
}

📘
Note
The links element allows you to browse the results and includes the default parameters (automatically added if not originally provided).

👍
Note
Using pagination, you can retrieve documents according to specific parameters.

URL parameters

You can use the following parameters individually or combined to obtain the desired results.

Parameter	Description
`updated_at_min`	To provide a date to filter the results.
`document_type`	To provide a code for a unique document type to filter the results.
`quable-codes`	To pass codes in the header to retrieve a specific list of documents.
`quable-completenesses`	To limit the results to documents with specific completeness codes. Only complete documents for all codes provided will be present in the response.
`quable-tags`	To limit the results to documents with specific workflow step or status codes.

Example: updated_at_min

import requests

url = "https://{{instance}}.quable.com/api_1.php/documents?targetCulture=fr_FR&updated_at_min=2020-06-16T14:00:00"

payload={}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{token}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example: document_type

import requests

url = "https://{{instance}}.quable.com/api_1.php/documents?targetCulture=fr_FR&document_type=modelColor"

payload={}
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example: quable-codes

import requests

url = "https:/{{instance}}.quable.com/api_1.php/documents?limit=10&page=1"

payload={}
headers = {
    'Content-Type': 'application/json',
    'quable-codes': 'G39610,39610',
    'Authorization': 'Bearer {{token}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

Example: quable-completenesses

import requests

url = "https://{{instance}}.quable.com/api_1.php/documents?limit=10&page=1"

payload={}
headers = {
  'Content-Type': 'application/json',
  'quable-completenesses': 'ecommerce,internal_portal',
  'Authorization': 'Bearer {{token}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example: quable-tags

import requests

url = "https://{{instance}}.quable.com/api_1.php/documents?limit=10&page=1"

payload={}
headers = {
  'Content-Type': 'application/json',
  'quable-tags': 'erp_ready',
  'Authorization': 'Bearer {{token}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Output contract parameters

Parameter	Description
`parent_documents`	Includes parent links in the response. (boolean - default: false)
`target_documents`	Includes child links in the response. (boolean - default: false)
`media_included`	Includes asset links in the response. (boolean - default: true)
`media_fields_included`	Includes asset attributes in response. (boolean - default: false)

Complex Example

Since the API does not allow infinite recursion, there are times when it will be necessary to make two calls.

Let's say you need to do this:

documents "product"
	- asset via the "article_images_media" link
	- asset via the "fiche_technique" link
	- documents "product" via the the "cross_sell" link
		- asset via the "article_images_media" link
		- asset via the "fiche_technique link

You will have to do:

Part 1:

documents "product"
	- asset via the "article_images_media" link
	- asset via the "fiche_technique" link
	- documents "product" via the "cross_sell" link

And then your job will manage the second part:

Part 2:

- documents "product" via the "cross_sell" link
		- asset via the "article_images_media" link
		- asset via the "fiche_technique" link