Quotes API

1. Overview

The Zakeke Quotes API is a collection of endpoints designed to manage quotes within the Zakeke ecosystem. These APIs allow you to retrieve quotation requests submitted by customers, approve or reject them, and retrieve the associated order ID once a quote has been approved.

2. List of endpoints

The following are the endpoints available for the Quotes API.

Please Note

All the endpoints have the following base url: https://api.zakeke.com/

warning

All API calls need to be authenticated and authorized via an S2S-type oAuth token. For all the details see the Authentication and Authorization section.

Method	Endpoint	Description
GET	`/v2/quotes`	Retrieve a paginated list of quotes starting from the most recent ones.
GET	`/v2/quotes/{quoteId}`	Retrieve a quote by specifying the ID.
POST	`/v2/quotes/{quoteId}/approve`	Approve a quote and create the associated order.
POST	`/v2/quotes/{quoteId}/reject`	Reject a quote.
GET	`/v2/quotes/getOrderID`	Get the order ID associated with an approved quote.

In the following sections we will provide details of each endpoint with a description of the information they provide and the operations they perform.

3. Error codes

In RESTful API calls, such as those made to Zakeke, HTTP status codes are crucial for indicating the outcome of API requests. Codes in the 2xx range signify successful operations, 4xx errors denote client-side issues, and 5xx errors indicate server-side problems. This system allows developers to quickly identify and address issues with API interactions, enhancing the efficiency of integrating with Zakeke's services.

For certain status codes, Zakeke includes an error message in the response body to elucidate the cause of the error. This is particularly useful when a single status code, like 404 Not Found or 400 Bad Request, could indicate various issues. These messages help developers pinpoint the specific problem, facilitating a more efficient troubleshooting process when integrating with Zakeke's APIs.

4. Retrieve all quotes

This endpoint returns a paginated list of quotes submitted by customers, starting from the most recent ones.

Request

GET https://api.zakeke.com/v2/quotes

The following are the parameters you can use in query string:

Parameter	Data type	Description
pageSize	`integer`	The page size of the result. Default is `15`.
pageNumber	`integer`	The number of the page to return. The first page will have `pageNumber` = 1. Default is `1`.
status	`integer`	Filter quotes by status ID.
dateFrom	`datetime`	Filter quotes created on or after this date.
dateTo	`datetime`	Filter quotes created on or before this date.
formData	`string`	Filter quotes by form data content.
attributionType	`string`	Filter quotes by attribution type.
attributionID	`string`	Filter quotes by attribution ID.

warning

Use pagination parameters and an optimal page size to maintain good performance when running the API.

Response

The API call returns a JSON array with the following structure:

[
  {
    "quoteID": 0,
    "statusID": 0,
    "status": "string",
    "amount": 0,
    "shippingAmount": 0,
    "additionalAmount": 0,
    "additionalAmountLabel": "string",
    "modelPrice": 0,
    "variantName": "string",
    "quantity": 0,
    "customerCode": "string",
    "visitorCode": "string",
    "formData": "string",
    "createdOn": "2024-01-01T00:00:00Z",
    "attributionType": "string",
    "attributionID": "string"
  }
]

Each item of the array represents a quote and its properties have the following meaning:

Property	Data type	Description
quoteID	`integer`	Unique identifier of the quote.
statusID	`integer`	Numeric identifier of the quote status.
status	`string`	Human-readable status of the quote (e.g. Pending, Approved, Rejected).
amount	`decimal`	The quoted amount.
shippingAmount	`decimal`	The shipping amount for the quote.
additionalAmount	`decimal`	Any additional amount applied to the quote.
additionalAmountLabel	`string`	Label describing the additional amount.
modelPrice	`decimal`	The base product price.
variantName	`string`	Name of the product variant.
quantity	`integer`	The quantity requested by the customer.
customerCode	`string`	The customer identifier on your ecommerce.
visitorCode	`string`	The visitor identifier on your ecommerce.
formData	`string`	The form data submitted by the customer with the quote request.
createdOn	`datetime`	Date and time the quote was created.
attributionType	`string`	The type of attribution for the quote.
attributionID	`string`	The attribution identifier for the quote.

Furthermore, when using pagination parameters, the response also returns the following two custom headers:

Parameter	Data type	Description
X-Total-Count	`integer`	The total number of quotes matching the criteria.
X-Has-More-Pages	`boolean`	There is a page following the current one.

Naturally, HTTP headers have textual content but they can be interpreted in the indicated data type.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the quote list.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.

Examples

Example 1 Get the first 20 quotes.

curl -X GET https://api.zakeke.com/v2/quotes?pageSize=20&pageNumber=1 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

The response will have the body with the first 20 quotes and the following custom headers:

X-Total-Count: "35" X-Has-More-Pages: "True"

Example 2 Get pending quotes created after a specific date.

curl -X GET "https://api.zakeke.com/v2/quotes?pageSize=10&pageNumber=1&status=1&dateFrom=2024-01-01" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

5. Retrieve a quote by ID

This endpoint allows you to obtain the full details of a quote by specifying its ID.

Request

GET https://api.zakeke.com/v2/quotes/{quoteId}

The quoteId parameter is the unique identifier of the quote in Zakeke.

Response

The API call returns a JSON object with the following structure:

{
  "quoteID": 0,
  "statusID": 0,
  "status": "string",
  "amount": 0,
  "shippingAmount": 0,
  "additionalAmount": 0,
  "additionalAmountLabel": "string",
  "modelPrice": 0,
  "variantName": "string",
  "quantity": 0,
  "customerCode": "string",
  "visitorCode": "string",
  "formData": "string",
  "additionalInformations": "string",
  "orderDocID": "string",
  "designDocID": "string",
  "compositionDocID": "string",
  "createdOn": "2024-01-01T00:00:00Z",
  "attributionType": "string",
  "attributionID": "string"
}

The response includes all properties from the list endpoint, plus the following additional fields:

Property	Data type	Description
additionalInformations	`string`	Additional information associated with the quote.
orderDocID	`string`	The order document identifier, if the quote has been approved and an order has been created.
designDocID	`string`	The design document identifier associated with the quote.
compositionDocID	`string`	The composition document identifier associated with the quote.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the requested quote.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No quote was found with the ID that matches the request.

Examples

curl -X GET https://api.zakeke.com/v2/quotes/12345 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

6. Approve a quote

This endpoint allows you to approve a quote. When a quote is approved, the associated order is automatically created in Zakeke.

Request

POST https://api.zakeke.com/v2/quotes/{quoteId}/approve

The quoteId parameter is the unique identifier of the quote to approve.

Response

The API call returns a JSON object with the following structure:

{
  "quoteID": 0,
  "status": "string",
  "orderID": "string"
}

where:

Property	Data type	Description
quoteID	`integer`	The unique identifier of the quote.
status	`string`	The updated status of the quote after approval.
orderID	`string`	The identifier of the order created as a result of the approval.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The quote has been approved and the order created.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No quote was found with the ID that matches the request.
409	Conflict	The quote cannot be approved because it is in an invalid state (e.g. already approved or rejected).

Examples

curl -X POST https://api.zakeke.com/v2/quotes/12345/approve \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

7. Reject a quote

This endpoint allows you to reject a quote.

Request

POST https://api.zakeke.com/v2/quotes/{quoteId}/reject

The quoteId parameter is the unique identifier of the quote to reject.

Response

The API call returns a JSON object with the following structure:

{
  "quoteID": 0,
  "status": "string",
  "orderID": null
}

where:

Property	Data type	Description
quoteID	`integer`	The unique identifier of the quote.
status	`string`	The updated status of the quote after rejection.
orderID	`string`	Will be `null` for rejected quotes as no order is created.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The quote has been rejected.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No quote was found with the ID that matches the request.
409	Conflict	The quote cannot be rejected because it is in an invalid state (e.g. already approved or rejected).

Examples

curl -X POST https://api.zakeke.com/v2/quotes/12345/reject \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

8. Get the order ID for a quote

This endpoint allows you to retrieve the order ID associated with an approved quote.

Request

GET https://api.zakeke.com/v2/quotes/getOrderID?quoteId={quoteId}

The quoteId query parameter is the unique identifier of the quote.

Response

The API call returns a JSON object with the following structure:

{
  "quoteID": 0,
  "orderID": "string"
}

where:

Property	Data type	Description
quoteID	`integer`	The unique identifier of the quote.
orderID	`string`	The identifier of the order associated with the approved quote.

warning

This endpoint only returns a result for approved quotes that have an associated order. If the quote has not been approved yet, a 400 Bad Request response will be returned.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the order ID.
400	Bad Request	The quote has no associated order. Only approved quotes have an order.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No quote was found with the ID that matches the request.

Examples

curl -X GET "https://api.zakeke.com/v2/quotes/getOrderID?quoteId=12345" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

Quotes API

1. Overview​

2. List of endpoints​

3. Error codes​

4. Retrieve all quotes​

Request​

Response​

HTTP Response Codes​

Examples​

5. Retrieve a quote by ID​

Request​

Response​

HTTP Response Codes​

Examples​

6. Approve a quote​

Request​

Response​

HTTP Response Codes​

Examples​

7. Reject a quote​

Request​

Response​

HTTP Response Codes​

Examples​

8. Get the order ID for a quote​

Request​

Response​

HTTP Response Codes​

Examples​

1. Overview

2. List of endpoints

3. Error codes

4. Retrieve all quotes

Request

Response

HTTP Response Codes

Examples

5. Retrieve a quote by ID

Request

Response

HTTP Response Codes

Examples

6. Approve a quote

Request

Response

HTTP Response Codes

Examples

7. Reject a quote

Request

Response

HTTP Response Codes

Examples

8. Get the order ID for a quote

Request

Response

HTTP Response Codes

Examples