2. Get 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.
224224

📘

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.

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:

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.
{
    "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": []
}

📘

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

👍

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.

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.
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)
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)
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)
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)
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

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 :

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

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