Processing personalization results

Last updated on November 11, 2024
•
9 minutes to read

After a successful checkout, you can save the personalization results in your Customer's Canvas account for further processing. Here, the special integration entity Project appears. When creating a project, the corresponding private design is marked as permanent and remains in private storage for as long as this project exists.

Creating projects

The project is primarily used to prepare print files for making a personalized product. Projects store private designs, data obtained during personalization, and information about the order in the online store.

Single-item projects

A separate project is created for each product in the order if the product is linked to the Customer's Canvas specification. Depending on the configuration of the personalization process, a single project may include information about multiple elements and their personalized designs. For example, a project for the product representing a postcard in an envelope may include two elements: a postcard and an envelope.

In the Storefront API, the endpoint Projects_CreateWithSingleItem is responsible for creating projects. You can use it when you have linked your products through a product Reference. The parameters are the product identifier in the online store, order information, and personalization results.

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Authorization: Bearer <TOKEN>" \
-d  "{'orderId': 1004, 'item': { 'productReference': 'invitation', 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }}"

POST https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12
Content-Type: application/json
{
    'orderId': 1004,
    'item': {
        'productReference': 'invitation',
        'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb']
    }
}

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{'orderId': 1004, 'item': { 'productReference': 'invitation', 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }}";
var project = await projectsApiClient.CreateWithSingleItemAsync(storefrontId, null, body);

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{'orderId': 1004, 'item': { 'productReference': 'invitation', 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }}";
var project = _projectsApiClient.createWithSingleItem(storefrontId, null, body);

// Set a real storefront ID
$storefrontId = 12;
// Set a product reference, order ID, and design IDs
$body = "{'orderId': 1004, 'item': { 'productReference': 'invitation', 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }}";
$project = $projectsApiClient->projectsCreate($storefrontId, null, $body);

Here, the designIds array contains private design IDs saved after personalization. The system will automatically run a pipeline linked to the product.

When you don't need to process an order, but only get a print file for a design, you can create a project with a built-in pipeline that performs a single render-hires task for a singe line item. To do so, use the endpoint POST /api/storefront/v1/projects/by-scenario/render-hires. In the request body, pass the RenderHiResScenarioDto data.

In the orderDetails object, you can pass the description of an e-commerce order:

orderId [string] is an order identifier.
orderUrl [string] is a link to the order.
orderNumber [integer] is an order number.
customerId [string] is a customer identifier.
customerName [string] is a customer name.

Specify the line item by ID or by index. The orderLineItemIndex and orderLineItemId fields can be specified at the root level of the body object or in the orderDetails object.

In the scenario object, you can pass the following rendering parameters:

designId [string] is an identifier of a private design.
name [string] is an output file name, result by default.
dpi [integer] is output file DPI, 300 by default.
format ["Pdf", "Jpeg", "Png", "Tiff"] is the output file format, "Pdf" by default.
colorSpace ["Rgb", "Grayscale", "Cmyk"] is the output file color space, "Cmyk" by default.
flipMode ["None", "Horizontal", "Vertical", "Both"] is a flip mode of the output file, "None" by default.
anonymousAccess [boolean] is the mode of accessing the output file, false by default.

Let's render a design from the order 1004 to the file print.pdf.

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/render-hires?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  "{'orderDetails': {'orderId': 1004}, 'orderLineItemId': '642e798d6451dc407693d046', 'scenario': { 'designId': '62da200abb25c5477797d9cb', 'name': 'print'}}"

POST https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/render-hires?storefrontId=12
Content-Type: application/json
{
    'orderDetails': {'orderId': 1004},
    'orderLineItemId': '642e798d6451dc407693d046', 
    'scenario': { 'designId': '62da200abb25c5477797d9cb', 'name': 'print'}
}

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{'orderDetails': {'orderId': 1004}, 'orderLineItemId': '642e798d6451dc407693d046', 'scenario': { 'designId': '62da200abb25c5477797d9cb', 'name': 'print'}}";
var project = await projectsApiClient.CreateByRenderHiResScenarioAsync(storefrontId, null, body);

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{'orderDetails': {'orderId': 1004}, 'orderLineItemId': '642e798d6451dc407693d046', 'scenario': { 'designId': '62da200abb25c5477797d9cb', 'name': 'print'}}";
var project = _projectsApiClient.createByRenderHiResScenario(storefrontId, null, body);

// Set a real storefront ID
$storefrontId = 12;
// Set a product reference, order ID, and design IDs
$body = "{'orderDetails': {'orderId': 1004}, 'orderLineItemId': '642e798d6451dc407693d046', 'scenario': { 'designId': '62da200abb25c5477797d9cb', 'name': 'print'}}";
$project = $projectsApiClient->projectsCreateByRenderHiResScenario($storefrontId, null, $body);

Multi-item projects

To rid yourself from implementing post-processing of the results of single-item projects and at the same time process the entire order, you can use the endpoint Projects_CreateWithMultipleItems, which creates a project for many products. This endpoint uses pipelines specified in every product configuration and the post-processing pipeline specified in the integration settings.

In the request body, pass the CreateMultiItemProjectDto data.

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/with-multiple-items?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  "{'orderId': 1004, 'items': [{ 'orderLineItemIndex': 0, 'productReference': '24298', 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }, { 'orderLineItemIndex': 1, "productReference": "24299", 'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9'] }]}"

POST https://api.customerscanvashub.com/api/storefront/v1/projects/with-multiple-items?storefrontId=12
Content-Type: application/json
{
    'orderId': 1004,
    'items': [{
        'orderLineItemIndex': 0,
        'productReference': '24298',
        'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb']
    },
    {
        'orderLineItemIndex': 1,
        'productReference': '24299',
        'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9']
    }]
}

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{'orderId': 1004, 'items': [{ 'orderLineItemIndex': 0, 'productReference': '24298', 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }, { 'orderLineItemIndex': 1, 'productReference': '24299', 'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9'] }]}";
var project = await projectsApiClient.CreateWithMultipleItemsAsync(storefrontId, null, body);

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{'orderId': 1004, 'items': [{ 'orderLineItemIndex': 0, 'productReference': '24298', 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }, { 'orderLineItemIndex': 1, 'productReference': '24299', 'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9'] }]}";
var project = _projectsApiClient.createWithMultipleItems(storefrontId, null, body);

When you haven't linked products by product reference, you can create a product by using the endpoint Projects_CreateBySpecificPipelineScenario. It creates a project to process several line items of an order.

In the request body, pass the CreateProjectBySpecificPipelineScenarioDto data. You can use an arbitrary pipeline defined in your BackOffice panel or the pipeline linked to the product. In the latter case, get its ID through the endpoint GET /api/storefront/v1/products/{id}.

When defining the scenario object, you must specify the pipelines to be applied by name or by ID:

pipelineId [integer] is an identifier of an existing processing pipeline, which will be applied to all the items.
postProcessingPipelineId [integer] is an existing processing pipeline identifier for project post-processing.
itemPipelines [] is an array of objects describing connections between project items (by itemName) and processing pipelines (by pipelineId). Here, you can configure a set of pipelines applicable to different items as an alternative to a single pipeline specified in pipelineId.

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/specific-pipeline?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  "{'orderDetails': {'orderId': 1004}, 'items': [{ 'orderLineItemIndex': 0, 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }, { 'orderLineItemIndex': 1, 'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9'] }], 'scenario': {'pipelineId': 247, 'postProcessingPipelineId': 243}}"

POST https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/specific-pipeline?storefrontId=12
Content-Type: application/json
{
    'orderDetails': {'orderId': 1004},
    'items': [{
        'orderLineItemIndex': 0,
        'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb']
    },
    {
        'orderLineItemIndex': 1,
        'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9']
    }],
    'scenario': { 'pipelineId': 247, 'postProcessingPipelineId': 243 }
}

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{'orderDetails': {'orderId': 1004}, 'items': [{ 'orderLineItemIndex': 0, 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }, { 'orderLineItemIndex': 1, 'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9'] }], 'scenario': {'pipelineId': 247, 'postProcessingPipelineId': 243}}";
var project = await projectsApiClient.CreateWithMultipleItemsAsync(storefrontId, null, body);

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{'orderDetails': {'orderId': 1004}, 'items': [{ 'orderLineItemIndex': 0, 'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb'] }, { 'orderLineItemIndex': 1, 'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9'] }], 'scenario': {'pipelineId': 247, 'postProcessingPipelineId': 243}}";
var project = _projectsApiClient.createWithMultipleItems(storefrontId, null, body);

Browsing projects

You can get a list of projects related to a given online store and track their status by using the Storefront API endpoint Projects_GetAll. This endpoint supports a paginated output as well as filtering by creation date and status.

curl -X \
GET "https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12

var storefrontId = 12; // Set a real storefront ID here
var projects = await projectsApiClient.GetAllAsync(storefrontId: storefrontId);

var storefrontId = 12; // Set a real storefront ID here
var projects = _projectsApiClient.getAll(null, null, null, null, null, null, null, null, null, storefrontId);

$storefrontId = 12; // Set a real storefront ID here
$projects = $projectsApiClient->projectsGetAll($storefrontId);

Working with projects

During the life cycle of a project, it can move from one status to another, reflecting the completed stages: creation, confirmation, preparation of a print file, production of products, delivery, and so on.

To get information about possible project states and transitions between them, you can use the endpoints Projects_GetAllStatuses and Projects_GetAllTransitions.

curl -X \
GET "https://api.customerscanvashub.com/api/storefront/v1/projects/statuses" \
-H  "accept: text/plain" \
-H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/projects/statuses

var projectStatuses = await projectsApiClient.GetAllStatusesAsync();

var projectStatuses = _projectsApiClient.getAllStatuses();

$projectStatuses = $projectsApiClient->projectsGetAllStatuses();

The transition between states is performed using the endpoint Projects_ChangeStatus. For example, if the project ID is 906, you can make it confirmed as follows:

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/906/transitions/confirm" \
-H  "accept: text/plain" \
-H  "Authorization: Bearer <TOKEN>"

POST https://api.customerscanvashub.com/api/storefront/v1/projects/906/transitions/confirm

var projectId = 906; // Set a project ID
var transition = "confirm"; // Set a transition name
var projectStatus = await projectsApiClient.ChangeStatusAsync(projectId, transition);

var projectId = 906; // Set a project ID
var transition = "confirm"; // Set a transition name
var projectStatus = _projectsApiClient.changeStatus(projectId, transition);

$projectId = 906; // Set a project ID
$transition = "confirm"; // Set a transition name
$projectStatus = $projectsApiClient->projectsChangeStatus($projectId, $transition);

To prepare and download a print file for making a personalized product, you can get its URL from the response of the endpoint GET /api/storefront/v1/projects/{id}/processing-results. The only parameter is the project identifier. For example, if the project ID is 906, you can get the print file links as follows:

curl -X \
GET "https://api.customerscanvashub.com/api/storefront/v1/projects/906/processing-results" \
-H  "accept: text/plain" \
-H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/projects/906/processing-results

var projectId = 906; // Set a project ID here
var pdfLink = await projectsApiClient.GetProjectPdfUrlAsync(projectId);

var projectId = 906; // Set a project ID here
var pdfLink = _projectsApiClient.getProjectPdfUrl(projectId);

$projectId = 906; // Set a project ID here
$pdfLink = $projectsApiClient->projectsGetProjectPdfUrl($projectId);

Next, let's learn how to download rendered print files.