#
Push documents & variants
--
--
--
--
--
--
--
--
--
--
Here are the steps to follow once you have dealt with predefined values:
- Push Reference documents
- Push Length documents (same process, with different attributes)
- Link Reference and Length documents
- Push variants
This cookbook has a matching Postman collection you can visit here to conduct your tests.
Datamodel used in this example
We are using a simple 2 levels datamodel as an example. The reference document is a "short-skirt".
The "short-skirt" comes in two different colors: "short-skirt-yellow" and "short-skirt-green".
The "short-skirt-yellow" comes in 3 different sizes, and the "short-skirt-green" comes in 2 different sizes.
graph TD A[reference 'short-skirt'] -->|linkType col_ref| B['short-skirt-yellow'] A[reference 'short-skirt'] -->|linkType col_ref| C['short-skirt-green'] B -.-> BV1[Variant S] B -.-> BV2[Variant M] B -.-> BV3[Variant L] C -.-> CV1[Variant S] C -.-> CV2[Variant M]
#
Push reference-type and color-type documents
Pushing reference-type documents and color-type documents work the same way. Only the request body will differ because the attributes are different for each document type. Please refer to the reference-type documents instructions below to also push the color-type documents (or any other relevant document type).
#
Attribute list
Let's consider the following attributes for the reference-type documents:
- reference_name : text
- r_long_name : multline text
- r_season : Predefined Values - single choice
- r_indicative_price : decimal
- r_sellable : boolean
- r_selling_start_date : date
- r_washing : Predefined Values - multiple choice
#
Available Endpoints
To get an existing document:
GET
/api/documents/yellow-skirt
To create new document:
POST
/api/documents
To update an existing document:
PUT
/api/documents/yellow-skirt
To delete an existing document:
DELETE
/api/documents/yellow-skirt
#
Fetch documents
This allows to verify if the document already exists in the PIM, or if it has to be created.
curl --location --globoff --request GET 'https://{{instance}}.quable.com/api/documents/v-neck pullover' \
--header 'Authorization: Bearer _api-token_'
In case of success, the response will come through as an
HTTP 200
.
The fetched resources will be available in a
hydra:member
table.
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"name": "DocumentOutput/name",
"isActive": "DocumentOutput/isActive",
"attributes": "DocumentOutput/attributes",
"documentType": "DocumentOutput/documentType",
"attributeSet": "DocumentOutput/attributeSet",
"classifications": "DocumentOutput/classifications",
"documentLinks": "DocumentOutput/documentLinks",
"assetLinks": "DocumentOutput/assetLinks",
"workflows": "DocumentOutput/workflows",
"tags": "DocumentOutput/tags",
"completenessResults": "DocumentOutput/completenessResults",
"variants": "DocumentOutput/variants",
"mainAssetThumbnailUrl": "DocumentOutput/mainAssetThumbnailUrl",
"dateCreated": "DocumentOutput/dateCreated",
"dateModified": "DocumentOutput/dateModified",
"legacyId": "DocumentOutput/legacyId",
"active": "DocumentOutput/active"
},
"@type": "Document",
"@id": "/api/documents/v-neck%20pullover",
"active": true,
"attributes": {
"r_indicative_price": 199.5,
"r_season": [
{
"id": "Summer28",
"labels": {
"en_GB": null,
"en_US": null,
"fr_FR": "Ete 2028"
}
}
],
"r_sellable": true,
"r_selling_start_date": "2028-02-21 00:00:00",
"r_washing": [
{
"id": "20_degrees",
"labels": {
"en_GB": "20 degrees",
"en_US": "20 degrees",
"fr_FR": "20 degrés"
}
},
{
"id": "handwashing",
"labels": {
"en_GB": "Hand wahsing",
"en_US": "Hand wahsing",
"fr_FR": "Lavage à la main"
}
}
],
"reference_name": {
"en_GB": "V-Neck pullover - Merinos",
"en_US": "V-Neck pullover - Merinos",
"fr_FR": "Pullover col V en mérinos"
}
},
"documentType": {
"@context": "/api/contexts/DocumentType",
"@id": "/api/document-types/reference",
"@type": "DocumentType",
"default": true,
"id": "reference"
},
"attributeSet": {
"@context": "/api/contexts/AttributeSet",
"@id": "/api/attribute-sets/att_set_jacket",
"@type": "AttributeSet",
"id": "att_set_jacket"
},
"classifications": [
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"parentCode": "ClassificationOutput/parentCode",
"catalogId": "ClassificationOutput/catalogId",
"isActive": "ClassificationOutput/isActive",
"attributes": "ClassificationOutput/attributes",
"assetLinks": "ClassificationOutput/assetLinks",
"mainAssetUrl": "ClassificationOutput/mainAssetUrl",
"mainAssetThumbnailUrl": "ClassificationOutput/mainAssetThumbnailUrl",
"dateCreated": "ClassificationOutput/dateCreated",
"dateModified": "ClassificationOutput/dateModified",
"createdBy": "ClassificationOutput/createdBy",
"updatedBy": "ClassificationOutput/updatedBy",
"legacyId": "ClassificationOutput/legacyId",
"active": "ClassificationOutput/active"
},
"@type": "Classification",
"@id": "/api/classifications/classification_men-top-pull",
"catalogId": null,
"id": "classification_men-top-pull",
"legacyId": 1448
}
],
"documentLinks": [],
"assetLinks": [],
"workflows": [],
"tags": [
{
"@context": "/api/contexts/Tag",
"@id": "/api/tags/all_documents_new_6130edc94b136",
"@type": "Tag",
"id": "all_documents_new_6130edc94b136"
}
],
"completenesses": {
"completeness_characteristics_and_care": {
"en_GB": 0.11,
"en_US": 0.11,
"fr_FR": 0.11
}
},
"variants": [],
"mainAssetThumbnailUrl": null,
"dateCreated": "2023-08-23T14:42:29+00:00",
"dateModified": "2023-08-23T14:46:28+00:00",
"id": "v-neck pullover",
"legacyId": 47
}
#
Document creation
This is a POST type of request.
Note
You can also push the set of attributes in the request (but it is not mandatory) and the PIM classification in which the document will appear, like in the example below.
curl --location 'https://{{instance}}.quable.com/api/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer _api-token_' \
--data '{
"id": "short-skirt",
"active": true,
"documentType": {
"id": "reference"
},
"classification": {
"id": "classification_ready_to_wearw5"
},
"attributes": {
"reference_name": {
"fr_FR": "Jupe courte",
"en_US": "Short skirt"
},
"r_long_name": {
"en_US": "Trendy short skirt"
}
}
}
In case of success, the response will come through as an HTTP 201 .
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"name": "DocumentOutput/name",
"isActive": "DocumentOutput/isActive",
"attributes": "DocumentOutput/attributes",
"documentType": "DocumentOutput/documentType",
"attributeSet": "DocumentOutput/attributeSet",
"classifications": "DocumentOutput/classifications",
"documentLinks": "DocumentOutput/documentLinks",
"assetLinks": "DocumentOutput/assetLinks",
"workflows": "DocumentOutput/workflows",
"tags": "DocumentOutput/tags",
"completenessResults": "DocumentOutput/completenessResults",
"variants": "DocumentOutput/variants",
"mainAssetThumbnailUrl": "DocumentOutput/mainAssetThumbnailUrl",
"dateCreated": "DocumentOutput/dateCreated",
"dateModified": "DocumentOutput/dateModified",
"legacyId": "DocumentOutput/legacyId",
"active": "DocumentOutput/active"
},
"@type": "Document",
"@id": "/api/documents/short-skirt",
"active": true,
"attributes": {
"reference_name": {
"en_GB": "Short skirt",
"en_US": "Short skirt",
"fr_FR": "Jupe courte"
},
"r_long_name": {
"en_GB": "Trendy short skirt",
"en_US": "Trendy short skirt",
"fr_FR": null
}
},
"documentType": {
"@context": "/api/contexts/DocumentType",
"@id": "/api/document-types/reference",
"@type": "DocumentType",
"default": true,
"id": "reference"
},
"attributeSet": null,
"classifications": [
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"parentCode": "ClassificationOutput/parentCode",
"catalogId": "ClassificationOutput/catalogId",
"isActive": "ClassificationOutput/isActive",
"attributes": "ClassificationOutput/attributes",
"assetLinks": "ClassificationOutput/assetLinks",
"mainAssetUrl": "ClassificationOutput/mainAssetUrl",
"mainAssetThumbnailUrl": "ClassificationOutput/mainAssetThumbnailUrl",
"dateCreated": "ClassificationOutput/dateCreated",
"dateModified": "ClassificationOutput/dateModified",
"createdBy": "ClassificationOutput/createdBy",
"updatedBy": "ClassificationOutput/updatedBy",
"legacyId": "ClassificationOutput/legacyId",
"active": "ClassificationOutput/active"
},
"@type": "Classification",
"@id": "/api/classifications/classification_ready_to_wearw5",
"catalogId": null,
"id": "classification_ready_to_wearw5",
"legacyId": 1302
}
],
"documentLinks": [],
"assetLinks": [],
"workflows": [],
"tags": [
{
"@context": "/api/contexts/Tag",
"@id": "/api/tags/all_documents_new_6130edc94b136",
"@type": "Tag",
"id": "all_documents_new_6130edc94b136"
}
],
"completenesses": {
"completeness_characteristics_and_care": {
"en_GB": 0,
"en_US": 0,
"fr_FR": 0
}
},
"variants": [],
"mainAssetThumbnailUrl": null,
"dateCreated": "2023-09-21T09:29:50+00:00",
"dateModified": "2023-09-21T09:29:52+00:00",
"id": "short-skirt",
"legacyId": 52
}
#
Document edition
Note
Not all attributes need to be pushed here. The PIM API will consider the body request only.
curl --location --request PUT 'https://{{instance}}.quable.com/api/documents/yellow-skirt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer _api-token_' \
--data '{
"id": "short-skirt",
"attributes": {
"reference_name": {
"fr_FR" : "Jupe courte triangle",
"en_US" : "Short skirt in a triangle shape"
}
}
}'
In case of success, the response will come through as an HTTP 200 .
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"name": "DocumentOutput/name",
"isActive": "DocumentOutput/isActive",
"attributes": "DocumentOutput/attributes",
"documentType": "DocumentOutput/documentType",
"attributeSet": "DocumentOutput/attributeSet",
"classifications": "DocumentOutput/classifications",
"documentLinks": "DocumentOutput/documentLinks",
"assetLinks": "DocumentOutput/assetLinks",
"workflows": "DocumentOutput/workflows",
"tags": "DocumentOutput/tags",
"completenessResults": "DocumentOutput/completenessResults",
"variants": "DocumentOutput/variants",
"mainAssetThumbnailUrl": "DocumentOutput/mainAssetThumbnailUrl",
"dateCreated": "DocumentOutput/dateCreated",
"dateModified": "DocumentOutput/dateModified",
"legacyId": "DocumentOutput/legacyId",
"active": "DocumentOutput/active"
},
"@type": "Document",
"@id": "/api/documents/short-skirt",
"active": true,
"attributes": {
"reference_name": {
"en_GB": "Short skirt in a triangle shape",
"en_US": "Short skirt in a triangle shape",
"fr_FR": "Jupe courte triangle"
}
},
"documentType": {
"@context": "/api/contexts/DocumentType",
"@id": "/api/document-types/reference",
"@type": "DocumentType",
"default": true,
"id": "reference"
},
"attributeSet": null,
"classifications": {
"1": {
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"parentCode": "ClassificationOutput/parentCode",
"catalogId": "ClassificationOutput/catalogId",
"isActive": "ClassificationOutput/isActive",
"attributes": "ClassificationOutput/attributes",
"assetLinks": "ClassificationOutput/assetLinks",
"mainAssetUrl": "ClassificationOutput/mainAssetUrl",
"mainAssetThumbnailUrl": "ClassificationOutput/mainAssetThumbnailUrl",
"dateCreated": "ClassificationOutput/dateCreated",
"dateModified": "ClassificationOutput/dateModified",
"createdBy": "ClassificationOutput/createdBy",
"updatedBy": "ClassificationOutput/updatedBy",
"legacyId": "ClassificationOutput/legacyId",
"active": "ClassificationOutput/active"
},
"@type": "Classification",
"@id": "/api/classifications/classification_ready_to_wearw5",
"catalogId": null,
"id": "classification_ready_to_wearw5",
"legacyId": 1302
}
},
"documentLinks": [],
"assetLinks": [],
"workflows": [],
"tags": [
{
"@context": "/api/contexts/Tag",
"@id": "/api/tags/all_documents_new_6130edc94b136",
"@type": "Tag",
"id": "all_documents_new_6130edc94b136"
}
],
"completenesses": {
"completeness_characteristics_and_care": {
"en_GB": 0,
"en_US": 0,
"fr_FR": 0
}
},
"variants": [],
"mainAssetThumbnailUrl": null,
"dateCreated": "2023-09-21T09:29:50+00:00",
"dateModified": "2023-09-21T09:29:52+00:00",
"id": "short-skirt",
"legacyId": 52
}
#
Document deletion
curl --location --request DELETE 'https://{{instance}}.quable.com/api/documents/yellow-skirt' \
--header 'Authorization: Bearer _api-token_'
In case of success, the response will come through as an HTTP 204 and the response body will be empty.
#
Link reference and color documents
Links can be optional
If your datamodel is simpler than the one presented here, you might not need to create links.
Link type is required
To link documents from different types, you need to create a Link Type first, if the link type you need does not already exist in the PIM.
Once reference-type documents and color-type documents are created, you need to create the links between them, e.g. to define the parent-enfant relationship between the two. Here, "short-skirt-yellow" color document is defined as a child of the "short-skirt" reference document, and their link type is "link_type_reference_reference_color".
curl --location --request POST 'https://{{instance}}.quable.com/api/links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer _api-token_' \
--data '{
"origin": {
"id": "short-skirt"
},
"target": {
"id": "short-skirt-yellow"
},
"linkType": {
"id": "link_type_reference_reference_color"
},
"attributes": [],
"sequence": 1
}'
In case of success, the response will return a 201 created code.
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"linkType": "LinkOutput/linkType",
"origin": "LinkOutput/origin",
"target": "LinkOutput/target",
"sequence": "LinkOutput/sequence",
"attributes": "LinkOutput/attributes",
"dateCreated": "LinkOutput/dateCreated",
"dateModified": "LinkOutput/dateModified",
"legacyId": "LinkOutput/legacyId"
},
"@type": "Link",
"@id": "/api/links/73c1216c-6b27-49bb-9016-128f132a18ab",
"linkType": {
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"name": "LinkTypeOutput/name",
"priority": "LinkTypeOutput/priority",
"maxItems": "LinkTypeOutput/maxItems",
"origin": "LinkTypeOutput/origin",
"target": "LinkTypeOutput/target",
"status": "LinkTypeOutput/status",
"dateCreated": "LinkTypeOutput/dateCreated",
"dateModified": "LinkTypeOutput/dateModified",
"maxCountLinksByOrigin": "LinkTypeOutput/maxCountLinksByOrigin"
},
"@type": "LinkType",
"@id": "/api/link-types/link_type_reference_reference_color",
"id": "link_type_reference_reference_color"
},
"origin": {
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#"
},
"@type": "Document",
"@id": "/api/documents/short-skirt",
"id": "short-skirt"
},
"target": {
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#"
},
"@type": "Document",
"@id": "/api/documents/short-skirt-yellow",
"id": "short-skirt-yellow"
},
"sequence": 1,
"attributes": [],
"dateCreated": "2023-09-21T10:10:13+00:00",
"dateModified": "2023-09-21T10:10:13+00:00",
"id": "73c1216c-6b27-49bb-9016-128f132a18ab",
"legacyId": 291
}
#
Variants
#
Push variants
Variants can be optional
If your PIM does not have the 'variant' feature, this step is not necessary.
We are now going to create and/or edit the variants associated with the color-type documents.
We will consider the following attributes:
classDiagram class Variant { - quable_sku_name : text - sku_size : Predefined Values - single choice }
#
Available endpoints
Get an existing variant:
GET
/api/variants/yellow-skirt-S
Create a new variant:
POST
/api/variants
Update an existing variant:
PUT
/api/variants/yellow-skirt-S
Delete an existing variant:
DELETE
/api/variants/yellow-skirt-S
#
Get variants
This allows to verify if a variant already exists in the PIM.
curl --location --globoff --request GET 'https://{{instance}}.quable.com/api/variant/short-skirt-yellow-s' \
--header 'Authorization: Bearer _api-token_'
In case of success, the response will come through as an
HTTP 200
.
The fetched resources will be available in a
hydra:member
table.
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"name": "VariantOutput/name",
"document": "VariantOutput/document",
"isActive": "VariantOutput/isActive",
"attributes": "VariantOutput/attributes",
"sequence": "VariantOutput/sequence",
"assetLinks": "VariantOutput/assetLinks",
"dateCreated": "VariantOutput/dateCreated",
"classifications": "VariantOutput/classifications",
"dateModified": "VariantOutput/dateModified",
"legacyId": "VariantOutput/legacyId",
"active": "VariantOutput/active"
},
"@type": "Variant",
"@id": "/api/variants/short-skirt-yellow-s",
"name": "Jupe jaune taille S",
"document": {
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#"
},
"@type": "Document",
"@id": "/api/documents/short-skirt-yellow",
"id": "short-skirt-yellow"
},
"active": true,
"attributes": {
"quable_sku_name": {
"en_GB": "S size yellow skirt",
"en_US": "S size yellow skirt",
"fr_FR": "Jupe jaune taille S"
},
"sku_size": [
{
"id": "sku_size_S",
"labels": {
"en_GB": "S",
"en_US": "S",
"fr_FR": "S"
}
}
]
},
"sequence": 1,
"assetLinks": [],
"dateCreated": "2023-09-21T10:14:17+00:00",
"dateModified": "2023-09-21T10:14:17+00:00",
"id": "short-skirt-yellow-s",
"legacyId": 39
}
Link to reference documentation
To add when available
#
Variant creation
Associating the variant with its document ID
Here we are also pushing the document ID to which the variant is assigned.
curl --location 'https://{{instance}}.quable.com/api/variants' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer _api-token_' \
--data '{
"id": "short-skirt-yellow-s",
"active": true,
"document": {
"id": "short-skirt-yellow"
},
"attributes": {
"quable_sku_name": {
"fr_FR" : "Jupe jaune taille S",
"en_US" : "S size yellow skirt"
},
"sku_size": [
{
"id": "sku_size_S"
}
]
}
}
'
In case of success, the response will come through as an HTTP 201 .
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"name": "VariantOutput/name",
"document": "VariantOutput/document",
"isActive": "VariantOutput/isActive",
"attributes": "VariantOutput/attributes",
"sequence": "VariantOutput/sequence",
"assetLinks": "VariantOutput/assetLinks",
"dateCreated": "VariantOutput/dateCreated",
"classifications": "VariantOutput/classifications",
"dateModified": "VariantOutput/dateModified",
"legacyId": "VariantOutput/legacyId",
"active": "VariantOutput/active"
},
"@type": "Variant",
"@id": "/api/variants/short-skirt-yellow-s",
"name": "Jupe jaune taille S",
"document": {
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#"
},
"@type": "Document",
"@id": "/api/documents/short-skirt-yellow",
"id": "short-skirt-yellow"
},
"active": true,
"attributes": {
"quable_sku_name": {
"en_GB": "S size yellow skirt",
"en_US": "S size yellow skirt",
"fr_FR": "Jupe jaune taille S"
},
"sku_size": [
{
"id": "sku_size_S",
"labels": {
"en_GB": "S",
"en_US": "S",
"fr_FR": "S"
}
}
]
},
"sequence": 1,
"assetLinks": [],
"dateCreated": "2023-09-21T10:14:17+00:00",
"dateModified": "2023-09-21T10:14:17+00:00",
"id": "short-skirt-yellow-s",
"legacyId": 39
}
#
Variant edition
Note
Not all attributes need to be pushed here. The PIM API will only consider what is mentioned in the body request and nothing else.
curl --location --request PUT 'https://{{instance}}.quable.com/api/variants/short-skirt-yellow-s' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer _api-token_' \
--data '{
"id": "short-skirt-yellow-s",
"attributes": {
"sku_size": [
{
"id": "sku_size_XS"
}
]
}
}'
In case of success, the response will come through as an HTTP 200 .
{
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"name": "VariantOutput/name",
"document": "VariantOutput/document",
"isActive": "VariantOutput/isActive",
"attributes": "VariantOutput/attributes",
"sequence": "VariantOutput/sequence",
"assetLinks": "VariantOutput/assetLinks",
"dateCreated": "VariantOutput/dateCreated",
"classifications": "VariantOutput/classifications",
"dateModified": "VariantOutput/dateModified",
"legacyId": "VariantOutput/legacyId",
"active": "VariantOutput/active"
},
"@type": "Variant",
"@id": "/api/variants/short-skirt-yellow-s",
"name": "",
"document": {
"@context": {
"@vocab": "https://education-developers.quable.com/api/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#"
},
"@type": "Document",
"@id": "/api/documents/short-skirt-yellow",
"id": "short-skirt-yellow"
},
"active": true,
"attributes": {
"sku_size": [
{
"id": "sku_size_XS",
"labels": {
"en_GB": "XS",
"en_US": "XS",
"fr_FR": "XS"
}
}
]
},
"sequence": 1,
"assetLinks": [],
"dateCreated": "2023-09-21T10:14:17+00:00",
"dateModified": "2023-09-21T10:14:17+00:00",
"id": "short-skirt-yellow-s",
"legacyId": 39
}
#
Variant deletion
curl --location --request DELETE 'https://{{instance}}.quable.com/api/variants/short-skirt-yellow-s' \
--header 'Authorization: Bearer _api-token_'
In case of success, the response will come through as an HTTP 204 and the response body will be empty.