Documentation

 Back to top

PARTNERS API

Tapbuy provides plugins to sync with the main e-commerce platforms (Magento, Prestashop…). This documentation expose the API methods needed to sync Tapbuy e-commerce system with any custom e-commerce platforms.

Endpoint

https://{webservice-domain}/:api_endpoint

  • Technical information
    • supported protocol: https
    • exchange formats: json
    • encoding: UTF-8

Guides

Pagination

All top-level API resources have support for bulk fetches via “list” API methods. For instance you can list products or list customers. These list API methods share a common structure, taking at least these three parameters: limit, offset, and total.

  • Attributes

    • limit: 10 (number) - A limit on the number of items to be returned, between 1 and 100, default is 25.
    • offset: 0 (number) - The offset from the first item to list from.
    • total: 2 (number) - The total number of items that could be returned.
  • Pagination json format

    {
      "limit": 10,
      "offset": 0,
      "total": 2,
      "items":
        [
          {
            "id": 1,
            "description": "first item"
          },
          {
            "id": 2,
            "description": "second item"
          }
        ]
    }

Error

Use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Tapbuy servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., an order is declined), we return a 402 error code.

  • HTTP status code summary

    • 200 - OK: Everything worked as expected.
    • 400 - Bad Request: The request was unacceptable, often due to missing a required parameter.
    • 401 - Unauthorized: No valid API key provided.
    • 402 - Request: Failed The parameters were valid but the request failed.
    • 404 - Not Found: The requested resource doesn’t exist.
    • 409 - Conflict: The request conflicts with another request (perhaps due to using the same idempotent key).
    • 429 - Too Many Requests: Too many requests hit the API too quickly.
    • 500, 502, 503, 504 - Server Errors: Something went wrong on Tapbuy end.
  • Tapbuy error code summary

    • XXX - A Webservice status code
  • Tapbuy error json format

    {
      "code": 100,
      "message": "Connection error, the server is not responding.",
      "errors":
        [
          {
            "code": 1,
            "message": "An error occured"
          }
        ]
    }
  • Handling errors

    Our API libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

Authentication

The retailer API must use OAuth to authorize Tapbuy to access to their API. Provide us client_id and client_secret.

Tokens

Get an Access Token
POST/oauth/token

Returns an access_token which is passed along as a header with all future requests to authenticate the user. You must provide the Authorization: Basic {access_token} or Authorization: Bearer {access_token} header in all other requests. All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Tapbuy clients who want to use the API must get an access_token with the following grant_type:

  • client_credentials: (string) - gets an access_token for a Basic Authorization

  • password: (string) - gets an access_token for an Authorization with a Bearer access_token, optional attributes email/password are needed to get a Bearer access_token

  • refresh_token: (string) - provide a refresh_token to renew a Bearer access_token

The client_id and client_secret provided to Tapbuy will be used to build a basic_auth_header:

basic_auth_header = "Authorization: Basic " + Base64.encode(client_id + “:” client_secret)

Example URI

POST https://webservice.any/oauth/token
Request
HideShow
Headers
Authorization: Basic {basic_auth_header}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "abc123",
  "token_type": "bearer",
  "expires_in": 7776000,
  "created_at": 1457385291,
  "refresh_token": "cba321"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "meta": {},
  "errors": [
    {
      "status": 422,
      "code": "invalid_credentials",
      "title": "Invalid credentials"
    }
  ]
}

Products

Resources to describe real or digital goods.

Product list

Product list
GET/products

Retrieves a list of Product objects.

Example URI

GET https://webservice.any/products
URI Parameters
HideShow
limit
number (optional) 
offset
number (optional) 
filters
array (optional) Example: id_product[]=123

To get only specific products, filters must include pagination parameters (limit, offset)

Request
HideShow
Headers
Authorization: Basic {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "limit": 10,
  "offset": 0,
  "total": 1,
  "items": [
    {
      "id": "abc123",
      "name": "Awesome shirt",
      "short_description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
      "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p><p>Aliquam erat volutpat.</p>",
      "category": "Fashion",
      "brand_name": "FashionShirt",
      "images": [
        {
          "url": "https://product.url/img.png"
        }
      ],
      "url": "https://product.url",
      "attributes_combination": [
        {
          "combination_id": 23,
          "attributes": [
            {
              "name": "color",
              "id": "blue",
              "display_name": "Blue",
              "values": [
                {
                  "id": "blue",
                  "display_name": "Blue",
                  "is_default": true
                }
              ]
            }
          ],
          "is_default": true,
          "price": 120,
          "quantity": 10,
          "reference": "Product Reference",
          "weight": 12,
          "special_price": 100,
          "special_from_date": "2016-07-01 09:00:00",
          "special_to_date": "2016-07-08 23:59:59",
          "ean": 1234567891234
        }
      ],
      "weight": 12,
      "price": 120,
      "quantity": 10,
      "reference": "Product Reference",
      "special_price": 100,
      "special_from_date": "2016-07-01 09:00:00",
      "special_to_date": "2016-07-08 23:59:59",
      "ean": 1234567891234,
      "tax_rate": 20
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "total": {
      "type": "number"
    },
    "items": {
      "type": "array"
    }
  }
}

Stock information

Stock information
GET/products/:id/stock

Returns stock unit available.

Example URI

GET https://webservice.any/products/:id/stock
URI Parameters
HideShow
id
string (required) Example: AB12

The product identifier (id, url hash, …)

combination_id
string (optional) Example: 23

Product combination id

Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "stock": 100
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "stock": {
      "type": "number",
      "description": "Available in stock"
    }
  }
}

Similar products

Similar products
GET/products/:id/similar

Returns product information (title, price, image, attributes…).

Example URI

GET https://webservice.any/products/:id/similar
URI Parameters
HideShow
id
string (required) Example: AB12

The product identifier (id, url hash, …)

Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "limit": 10,
  "offset": 0,
  "total": 1,
  "items": [
    {
      "id": "abc123",
      "name": "Awesome shirt",
      "short_description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
      "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p><p>Aliquam erat volutpat.</p>",
      "category": "Fashion",
      "brand_name": "FashionShirt",
      "images": [
        {
          "url": "https://product.url/img.png"
        }
      ],
      "url": "https://product.url",
      "attributes_combination": [
        {
          "combination_id": 23,
          "attributes": [
            {
              "name": "color",
              "id": "blue",
              "display_name": "Blue",
              "values": [
                {
                  "id": "blue",
                  "display_name": "Blue",
                  "is_default": true
                }
              ]
            }
          ],
          "is_default": true,
          "price": 120,
          "quantity": 10,
          "reference": "Product Reference",
          "weight": 12,
          "special_price": 100,
          "special_from_date": "2016-07-01 09:00:00",
          "special_to_date": "2016-07-08 23:59:59",
          "ean": 1234567891234
        }
      ],
      "weight": 12,
      "price": 120,
      "quantity": 10,
      "reference": "Product Reference",
      "special_price": 100,
      "special_from_date": "2016-07-01 09:00:00",
      "special_to_date": "2016-07-08 23:59:59",
      "ean": 1234567891234,
      "tax_rate": 20
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "total": {
      "type": "number"
    },
    "items": {
      "type": "array"
    }
  }
}

Product import

Product import
GET/products/import

Launches a full products import for the authentificated retailer. Import specific product references using the optional parameter “references”, use a coma separator to import several references at once.

Example URI

GET https://webservice.any/products/import
URI Parameters
HideShow
references
string (optional) Example: PQDF1234,PQDF1235
Request
HideShow
Headers
Authorization: Basic {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Customers

Create customer

Create customer
POST/customers

Create a customer and returns customer data.

Example URI

POST https://webservice.any/customers
URI Parameters
HideShow
email
string (required) Example: elon@teslamotors.com
firstname
string (required) Example: elon
lastname
string (required) Example: musk
gender
string (optional) Example: m
password
string (optional) Example: vivaeads
address1
string (required) Example: `19 Bd Poissoniere
address2
string (optional) Example: WAI BNP Paribas
post_code
string (required) Example: 75002
iso_code
string (required) Example: FR
phone_number
number (required) Example: 0623456789
billing_address1
string (optional) Example: `19 Bd Poissoniere
billing_address2
string (optional) Example: WAI BNP Paribas
billing_post_code
string (optional) Example: 75002
billing_iso_code
string (optional) Example: FRA
billing_phone_number
number (optional) Example: `0623456789`,
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "abc123",
  "email": "elon@teslamotors.com",
  "firstname": "Elon",
  "lastname": "Musk",
  "phone": 623456789,
  "shipping_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  },
  "billing_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer identifier"
    },
    "email": {
      "type": "string",
      "description": "The email of the customer"
    },
    "firstname": {
      "type": "string",
      "description": "The firstname of the customer"
    },
    "lastname": {
      "type": "string",
      "description": "The lastname of the customer"
    },
    "phone": {
      "type": "number",
      "description": "Phone number"
    },
    "shipping_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The main address of the customer"
    },
    "billing_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The billing address of the customer (if different than shipping)"
    }
  },
  "required": [
    "id",
    "email",
    "firstname",
    "lastname",
    "phone"
  ]
}

Edit customer

Edit customer
PUT/customers

Edit customers password and returns customer data.

Example URI

PUT https://webservice.any/customers
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "abc123",
  "email": "elon@teslamotors.com",
  "firstname": "Elon",
  "lastname": "Musk",
  "phone": 623456789,
  "shipping_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  },
  "billing_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer identifier"
    },
    "email": {
      "type": "string",
      "description": "The email of the customer"
    },
    "firstname": {
      "type": "string",
      "description": "The firstname of the customer"
    },
    "lastname": {
      "type": "string",
      "description": "The lastname of the customer"
    },
    "phone": {
      "type": "number",
      "description": "Phone number"
    },
    "shipping_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The main address of the customer"
    },
    "billing_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The billing address of the customer (if different than shipping)"
    }
  },
  "required": [
    "id",
    "email",
    "firstname",
    "lastname",
    "phone"
  ]
}

Forgotten password

Forgotten password
POST/customer/:id/forgotten_password

Initiate the forgotten password process (send the email to customer)

Example URI

POST https://webservice.any/customer/:id/forgotten_password
Request
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Log customer

Log customer
GET/customers/login

Logs the customer in, updates the access_token grant_type and retrieves customer data.

Example URI

GET https://webservice.any/customers/login
Request
HideShow
Headers
Authorization: Basic {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "abc123",
  "email": "elon@teslamotors.com",
  "firstname": "Elon",
  "lastname": "Musk",
  "phone": 623456789,
  "shipping_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  },
  "billing_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  },
  "access_token": "abc123",
  "token_type": "bearer",
  "expired_in": 7776000,
  "created_at": 1457385291,
  "refresh_token": "cba321"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer identifier"
    },
    "email": {
      "type": "string",
      "description": "The email of the customer"
    },
    "firstname": {
      "type": "string",
      "description": "The firstname of the customer"
    },
    "lastname": {
      "type": "string",
      "description": "The lastname of the customer"
    },
    "phone": {
      "type": "number",
      "description": "Phone number"
    },
    "shipping_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The main address of the customer"
    },
    "billing_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The billing address of the customer (if different than shipping)"
    },
    "access_token": {
      "type": "string"
    },
    "token_type": {
      "type": "string"
    },
    "expired_in": {
      "type": "number"
    },
    "created_at": {
      "type": "number"
    },
    "refresh_token": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "email",
    "firstname",
    "lastname",
    "phone"
  ]
}

Retrieve customer

Retrieve customer
GET/customers/:id

Retrieve customer data.

Example URI

GET https://webservice.any/customers/:id
URI Parameters
HideShow
id
string (optional) Example: abc123

The customer identifier

Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "abc123",
  "email": "elon@teslamotors.com",
  "firstname": "Elon",
  "lastname": "Musk",
  "phone": 623456789,
  "shipping_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  },
  "billing_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer identifier"
    },
    "email": {
      "type": "string",
      "description": "The email of the customer"
    },
    "firstname": {
      "type": "string",
      "description": "The firstname of the customer"
    },
    "lastname": {
      "type": "string",
      "description": "The lastname of the customer"
    },
    "phone": {
      "type": "number",
      "description": "Phone number"
    },
    "shipping_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The main address of the customer"
    },
    "billing_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The billing address of the customer (if different than shipping)"
    }
  },
  "required": [
    "id",
    "email",
    "firstname",
    "lastname",
    "phone"
  ]
}

Email autocompletion

Email autocompletion
GET/customers/email-autocompletion

Returns customer email addresses matching the string passed (search within retailer customers members).

Example URI

GET https://webservice.any/customers/email-autocompletion
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "limit": 10,
  "offset": 0,
  "total": 1,
  "items": [
    {
      "id": "abc123",
      "email": "elon@teslamotors.com",
      "firstname": "Elon",
      "type": "retailer"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "total": {
      "type": "number"
    },
    "items": {
      "type": "array"
    }
  }
}

Find customer

Find customer
GET/customers

Check if a customer with phone or email exists

Example URI

GET https://webservice.any/customers
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "abc123",
  "email": "elon@teslamotors.com",
  "firstname": "Elon",
  "lastname": "Musk",
  "phone": 623456789,
  "shipping_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  },
  "billing_address": {
    "id": 0,
    "firstname": "elon",
    "lastname": "musk",
    "company": "musk",
    "address1": "1, infinite loop steet",
    "address2": "``",
    "post_code": "75002",
    "city": "Paris",
    "iso_code": "FR",
    "phone_number": 623456789
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer identifier"
    },
    "email": {
      "type": "string",
      "description": "The email of the customer"
    },
    "firstname": {
      "type": "string",
      "description": "The firstname of the customer"
    },
    "lastname": {
      "type": "string",
      "description": "The lastname of the customer"
    },
    "phone": {
      "type": "number",
      "description": "Phone number"
    },
    "shipping_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The main address of the customer"
    },
    "billing_address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Address identifier"
        },
        "firstname": {
          "type": "string",
          "description": "Firstname"
        },
        "lastname": {
          "type": "string",
          "description": "Lastname"
        },
        "company": {
          "type": "string",
          "description": "Lastname"
        },
        "address1": {
          "type": "string",
          "description": "Address 1"
        },
        "address2": {
          "type": "string",
          "description": "Address 2"
        },
        "post_code": {
          "type": "string",
          "description": "Post code"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "iso_code": {
          "type": "string",
          "description": "Country iso code"
        },
        "phone_number": {
          "type": "number",
          "description": "Phone number"
        }
      },
      "required": [
        "id",
        "firstname",
        "lastname",
        "address1",
        "post_code",
        "city",
        "iso_code",
        "phone_number"
      ],
      "description": "The billing address of the customer (if different than shipping)"
    }
  },
  "required": [
    "id",
    "email",
    "firstname",
    "lastname",
    "phone"
  ]
}

Get customer addresses

Get customer addresses
GET/customer/addresses/:id

Returns customer addresses.

Example URI

GET https://webservice.any/customer/addresses/:id
URI Parameters
HideShow
id
number (optional) Example: 11

Customer id

Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "limit": 10,
  "offset": 0,
  "total": 1,
  "items": [
    {
      "id": 0,
      "firstname": "elon",
      "lastname": "musk",
      "company": "musk",
      "address1": "1, infinite loop steet",
      "address2": "``",
      "post_code": "75002",
      "city": "Paris",
      "iso_code": "FR",
      "phone_number": 623456789
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "total": {
      "type": "number"
    },
    "items": {
      "type": "array"
    }
  }
}

Update customer address

Update customer address
PUT/customer/addresses/:id

Update given customer address

Example URI

PUT https://webservice.any/customer/addresses/:id
URI Parameters
HideShow
id
number (required) Example: 11

Customer id

id_address
number (required) Example: 22

Address id

address1
string (required) Example: 10 rue de Paris

Address address1

address2
string (optional) Example: batiment B

Address address2

firstname
string (required) Example: Jean

Address firstname

lastname
string (required) Example: Valjean

Address lastname

post_code
string (required) Example: 75000

Address postcode

city
string (required) Example: Paris

Address city

phone_number
string (required) Example: +33699887744

Address phone

iso_code: `FR` (string) - Country iso_code
string (required) 
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json

Add customer address

Add customer address
POST/customer/addresses

Add given customer address

Example URI

POST https://webservice.any/customer/addresses
URI Parameters
HideShow
id
number (required) Example: 11

Customer id

address1
string (required) Example: 10 rue de Paris

Address address1

address2
string (optional) Example: batiment B

Address address2

firstname
string (required) Example: Jean

Address firstname

lastname
string (required) Example: Valjean

Address lastname

post_code
string (required) Example: 75000

Address postcode

city
string (required) Example: Paris

Address city

phone_number
string (required) Example: +33699887744

Address phone

iso_code: `FR` (string) - Country iso_code
string (required) 
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json

Checkout

Carriers

Carriers
GET/carriers

Get available carrier list.

Example URI

GET https://webservice.any/carriers
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "ups",
  "name": "UPS",
  "delay": "2 days",
  "ranges": [
    {
      "id": 12,
      "type": "price",
      "delimiter1": 0,
      "delimiter2": 500,
      "price": 5,
      "tax_rate": 20,
      "zones": [
        {
          "id": 3,
          "iso_code: `FR` (string, required) - Zone iso_code": "Hello, world!",
          "name": "France"
        }
      ]
    }
  ],
  "free_delivery": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Carrier identifier"
    },
    "name": {
      "type": "string",
      "description": "Carrier name"
    },
    "delay": {
      "type": "string",
      "description": "Average delivery delay"
    },
    "ranges": {
      "type": "array",
      "description": "Carrier ranges"
    },
    "free_delivery": {
      "type": "boolean",
      "description": "Carrier is free ?"
    }
  },
  "required": [
    "id",
    "name",
    "delay",
    "ranges",
    "free_delivery"
  ]
}

Cart vouchers

Cart vouchers
GET/cart/vouchers

Get available vouchers.

Example URI

GET https://webservice.any/cart/vouchers
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "type": "amount",
  "amount": 100,
  "code": "REBATE20",
  "free_shipping": false,
  "conditions": [
    {
      "id": 1,
      "type": "customer",
      "type_id: `11` (number) - Condition type id (customer_id, carrier_id or voucher_id)": "Hello, world!"
    }
  ],
  "date_start": "2016-10-01 00:00:00",
  "date_end": "2016-10-30 23:59:59",
  "minimum_amount": 10,
  "quantity": 100,
  "quantity_per_user": 1,
  "action": "order",
  "action_products": [
    {
      "id": "abc123",
      "name": "Awesome shirt",
      "short_description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
      "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p><p>Aliquam erat volutpat.</p>",
      "category": "Fashion",
      "brand_name": "FashionShirt",
      "images": [
        {
          "url": "https://product.url/img.png"
        }
      ],
      "url": "https://product.url",
      "attributes_combination": [
        {
          "combination_id": 23,
          "attributes": [
            {
              "name": "color",
              "id": "blue",
              "display_name": "Blue",
              "values": [
                {
                  "id": "blue",
                  "display_name": "Blue",
                  "is_default": true
                }
              ]
            }
          ],
          "is_default": true,
          "price": 120,
          "quantity": 10,
          "reference": "Product Reference",
          "weight": 12,
          "special_price": 100,
          "special_from_date": "2016-07-01 09:00:00",
          "special_to_date": "2016-07-08 23:59:59",
          "ean": 1234567891234
        }
      ],
      "weight": 12,
      "price": 120,
      "quantity": 10,
      "reference": "Product Reference",
      "special_price": 100,
      "special_from_date": "2016-07-01 09:00:00",
      "special_to_date": "2016-07-08 23:59:59",
      "ean": 1234567891234,
      "tax_rate": 20
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Voucher id"
    },
    "type": {
      "type": "string",
      "description": "Voucher type, can be amount or percent"
    },
    "amount": {
      "type": "number",
      "description": "Voucher amount"
    },
    "code": {
      "type": "string",
      "description": "Voucher code"
    },
    "free_shipping": {
      "type": "boolean",
      "description": "Voucher include free shipping"
    },
    "conditions": {
      "type": "array",
      "description": "Voucher application rules"
    },
    "date_start": {
      "type": "string",
      "description": "Voucher starting date"
    },
    "date_end": {
      "type": "string",
      "description": "Voucher ending date"
    },
    "minimum_amount": {
      "type": "number",
      "description": "Voucher minimum to be applied (Taxes included)"
    },
    "quantity": {
      "type": "number",
      "description": "Voucher quantity"
    },
    "quantity_per_user": {
      "type": "number",
      "description": "Voucher quantity per user"
    },
    "action": {
      "type": "string",
      "description": "Voucher reduction applied on. Can be order or products"
    },
    "action_products": {
      "type": "array",
      "description": "Voucher products concerned if action is products"
    }
  },
  "required": [
    "type",
    "amount",
    "code",
    "free_shipping",
    "action"
  ]
}

Payment option list

Payment option list
GET/payment_options

Get a list of available payment methods for retailer

Example URI

GET https://webservice.any/payment_options
Request
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "limit": 10,
  "offset": 0,
  "total": 1,
  "items": [
    {
      "type": "paypal",
      "credit_card_datas": {
        "bank_name": "Société générale",
        "bank_iban": "FRKK BBBB BGGG GGCC CCCC CCCC CLL",
        "bank_swift": "FRJIKOLOMP",
        "pspid": "mypspid",
        "signature": "HDJSDS456456464SDS",
        "signature_encrypr": "SHA1"
      },
      "paypal_datas": {
        "mode": "live",
        "username": "paypal-elonmusk@tesla.io",
        "password": "SQSFS54DDAA",
        "signature": "AAKKDSLDKSLDSDS444DSSDSDSDSDS"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "total": {
      "type": "number"
    },
    "items": {
      "type": "array"
    }
  }
}

Orders

Create an order

Create an order
POST/order

Create an order returns order data. This method must check product availability and price accuracy.

Example URI

POST https://webservice.any/order
URI Parameters
HideShow
products
Product (required) 
delivery_address
CustomerAddress (required) 
billing_address: (CustomerAddress, optional) - If null, billing_address is delivery_address
string (required) 
shipping_method
string (required) Example: ups
payment_method
string (required) Example: `ogone`,
customer
Customer (required) 

Customer data to create the account

vouchers
array[Voucher] (required) 

Used vouchers

Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json

Retrieve Order

Retrieve Order
GET/order/:id

Returns order data.

Example URI

GET https://webservice.any/order/:id
Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "abc123",
  "email": "elon@teslamotors.com"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer identifier"
    },
    "email": {
      "type": "string",
      "description": "The email of the customer"
    }
  },
  "required": [
    "id"
  ]
}

Retrieve Order tracking number

Retrieve Order tracking number
GET/order/tracking-number/:id

Returns order tracking number.

Example URI

GET https://webservice.any/order/tracking-number/:id
URI Parameters
HideShow
id
string (required) Example: OMG1

Order id

Request
HideShow
Headers
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "tracking_number": "UPS10FEDX"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tracking_number": {
      "type": "string"
    }
  }
}
Receive ROI estimation
Send
Login
Request a new password

Votre formulaire a été soumis. Nous revenons vers vous dans les plus brefs délais. N'hésitez pas à nous contacter si vous avez des questions, nous serons ravis d'y répondre !
L'équipe Tapbuy

Best,

The Tapbuy Team

Close

Best,

The Tapbuy Team

Close