LOGO
LOGO
 

API Documentation

Current Version: 2.0

This API allows you to create and manage your orders with Tucia in a simple, programmatic way using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions.

With this API, you are able to add Tucia's human-powered photo editing functionality to any application. This is especially useful for resellers who have their own websites or apps, and outsource the real editing service to Tucia.

 

Schema

All API access is over HTTPS, and accessed from https://api.tucia.com/v2. All data is sent and received as JSON.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

e.g.: 2017-12-02T16:00:00+04:00

Back to top

 

HTTP Verbs

The Tucia API uses HTTP verbs appropriate to each action.

GET

Used for retrieving resources.

POST

Used for creating resources, or performing custom actions.

PUT

Used for updating resources.

DELETE

Used for deleting resources.

Back to top

 

Error messages

If an error occurs, whether on the server or client side, the error message(s) will be returned in an errors array. For example:

{
   "errors": ["Invalid order ID"]
}

Back to top

 

Pagination

Requests that return multiple items (e.g.: a list of all your orders) will be paginated to 20 items per page. The optional page parameter can be supplied to define which page to be returned.

Back to top

 

Authorization

The Tucia API uses Basic Auth for authorization. The first step is to go to account settings to generate a private pair of API KEY and API SECRET.

Before each request, you need to use HMAC-SHA256 algorithm to generate a signature, composed of the API KEY, API SECRET, a timestamp and the payload.

This is an example of implementation in PHP:

<?php

//This is an example payload:

$payloadArray=array(

    'project_name' => 'beach wedding',

    'instructions' => array('slim the waist', 'tan skin more')

);

//Merge the payload with API KEY and a timestamp:

$queryArray=array_merge($payloadArray, array(

    'api_key' => 'YOUR_API_KEY',

    'timestamp' =>gmdate('U')

));

//Order the parameters by key ascending:

ksort($queryArray);

//Convert the queryArray to string by JSON:

$queryString=json_encode($queryArray);

//Generate API signature:

$queryArray['signature']=hash_hmac('sha256', $queryString, 'YOUR_API_SECRET');

?>

The final query parameters will be something like this:

api_key

01B9C5C41C88D9403424C05AC4960323

instructions

['slim the waist', 'tan skin more']

project_name

beach wedding

timestamp

1512787346

signature

6a0b7f40fad6126500a21d6236086558c5d49594abe4b5bb491901de51fcc7a1

Back to top

 

Account

 

1. Retrieve account balance (in credits):

 

HTTP Request:

GET /account/balance

No query parameter is needed for this method.

 

Example response:

{
   "errors": [],
   "data": {
      "credits": 17.3
    }
}

Back to top

 

Orders

 

1. List orders:

 

HTTP Request:

GET /orders

Retrieves a list of your orders, ordered by create time descending.

 

Query Parameters:

Name Type Description

filter_status

string
optional

Filter orders by order status. Can be one of: all, editing, revising, paused, reviewing, closed, Default: all

example:

revising

filter_customer_id

string
optional

Filter orders by your own customer id.

example:

1234

filter_keywords

array
optional

Filter orders by 1 or more keywords. Each element in the array should be string type with minimum length of 6 characters

example:

array('wedding', 'portrait')

page

integer
optional

For pagination. Default: 1

example:

5

 

Example successful response:

{
   "errors": [],
   "per_page": 20,
   "current_page": 5,
   "total_pages": 27,
   "total_results": 538,
   "filter_status": 'all',
   "filter_keywords": '',
   "filter_customer_id": '',
   "sort_by": 'ordered_at',
   "data": [
       {
         "order_id": "UVWXYZ123",
         "project_name": "John's wedding",
         "customer_id": 1234,
         "price": 3,
         "status": "editing",
         "revision": 0,
         "ordered_at": "2017-12-02T16:00:00+04:00"
       },
       {
         "order_id": "UVWXYZ456",
         "project_name": "Chloe's portrait",
         "customer_id": 4567,
         "price": 1,
         "status": "revising",
         "revision": 1,
         "ordered_at": "2017-12-02T16:00:00+04:00"
       }
       ... ...
   ]
}

Back to top

 

 

2. Create order:

 

HTTP Request:

POST /orders/create

Credits in your account will be deducted accordingly. If credits are insufficient, errors will be returned

 

Query Parameters:

Name Type Description

project_name

string
optional

If blank, a random name will be assigned

example:

John's wedding

instructions

array
required

It's allowed to send an one-element array with a large chunk of text, but it's better to separate into short sentences and append each to the array

example:

array('slim waist', 'tan skin')

customer_id

string
optional

If you are a reseller, you can specify your customer_id in your own application.

example:

1234

images

array
required

Each element in the array represents 1 image, and must contains 3 parameters:
1. publicly accessible url of the image;
2. service type: "basic" or "extensive"; any other value will be considered as a reference image;
3. an optional instruction only applying to this image;

example:

array(
   ['http://abc.com/a.jpg', 'basic', 'this is for basic service']
   ['http://abc.com/b.jpg', 'extensive', 'this one is a complicated edit']
   ['http://abc.com/c.jpg', '', 'for reference only']
)

 

Example successful response:

{
   "errors": [],
   "data": {
      "order_id": "UVWXYZ123",
      "project_name": "John's wedding",
      "customer_id": 1234,
      "price": 3,
      "status": "editing",
      "ordered_at": "2017-12-02T16:00:00+04:00",
      "estimated_delivery": "2017-12-03T12:00:00+04:00"
    }
}

Example error response:

{
   "errors": [
      'insufficient balance: 2 credits',
      'one file is not accessible from our server: http://abc.com/b.jpg'
   ]
}

Back to top

 

 

3. Cancel order:

 

HTTP Request:

DELETE /orders/cancel

A new order can be canceled within 15 min of submission

 

Query Parameters:

Name Type Description

order_id

string
required

example:

UVWXYZ123

cancel_reason

array
optional

example:

selected wrong service

 

Example successful response:

{
   "errors": [],
   "data": {
      "order_id": "UVWXYZ123",
      "project_name": "John's wedding",
      "status": "canceled",
      "ordered_at": "2017-12-02T16:00:00+04:00",
      "canceled_at": "2017-12-02T16:05:00+04:00"
    }
}

Example error response:

{
   "errors": [
      '10 min deadline passed'
   ]
}

Back to top

 

 

4. Fetch order:

 

HTTP Request:

GET /orders/:order_id

Retrieves detailed information and edited photos of a specific order

 

Example successful response:

{
   "errors": [],
   "data": [
       {
         "order_id": "UVWXYZ123",
         "project_name": "John's wedding",
         "customer_id": 1234,
         "price": 3,
         "status": "reviewing",
         "revision": 2,
         "ordered_at": "2017-12-02T16:00:00+04:00",
         "edited_images": [
             {
                "id": "syd3ue2",
                "name": "abc_edited1.jpg",
                "width": 5760,
                "height": 3840,
                "size": "3.23MB",
                "revision": 1,
                "uploaded_at": "2017-12-03T12:30:00+04:00",
                "thumb": "https://............/small/thumb.jpg",
                "origin": "https://............/private/url/for/download"
             },
             {
                "id": "xbsh9sk",
                "name": "abc_edited2.jpg",
                "width": 5760,
                "height": 3840,
                "size": "4.18MB",
                "revision": 2,
                "uploaded_at": "2017-12-04T09:30:00+04:00",
                "thumb": "https://............/small/thumb.jpg",
                "origin": "https://............/private/url/for/download"
             }
         ]
       }
   ]
}

Back to top

 

 

5. Revise order:

 

HTTP Request:

POST /orders/:order_id/revise

Submit a revision request for a specific order when it is in "reviewing" status

 

Query Parameters:

Name Type Description

instructions

array
required

The revision instructions are image-bound. For each edited image, a unique image ID is set and can be retrieved via the /orders/:order_id API. For each element in this array, you must specify the image id as the key and revison instructions as the value.

example:

Assuming syd3ue2 and xbsh9sk are the example IDs for 2 example edited images

array(
   "syd3ue2"=>array("slim waist more", "tan skin more"),
   "xbsh9sk"=>array("make eyes bigger")
)

 

Example successful response:

{
   "errors": [],
   "data": {
      "order_id": "UVWXYZ123",
      "project_name": "John's wedding",
      "customer_id": 1234,
      "price": 3,
      "status": "revising",
      "revision": 2,
      "ordered_at": "2017-12-02T16:00:00+04:00",
      "revision_requested_at": "2017-12-03T16:00:00+04:00",
      "estimated_delivery": "2017-12-05T12:00:00+04:00"
    }
}

Example error response:

{
   "errors": [
      'invalid order status',
      'image ID not found: sh38nsk'
   ]
}

Back to top

 

 

6. Approve order:

 

HTTP Request:

POST /orders/:order_id/approve

Approve (or close) a specific order when it is in "reviewing" status

 

Query Parameters:

Name Type Description

feedback

array
optional

Anything you want us to know after the order is closed.

example:

good job! I hope this editor will do my future orders when possible.

 

Example successful response:

{
   "errors": [],
   "data": {
      "order_id": "UVWXYZ123",
      "project_name": "John's wedding",
      "customer_id": 1234,
      "price": 3,
      "status": "closed",
      "revision": 2,
      "ordered_at": "2017-12-02T16:00:00+04:00",
      "closed_at": "2017-12-05T12:00:00+04:00"
    }
}

Example error response:

{
   "errors": [
      'invalid order status'
   ]
}

Back to top

 

If you have any questions or suggestions about this API, don't hesitate to let us know.