Manufacturers API

Authentication ¶

Overview ¶

The Papertrail Manufacturer API requires that you provide an Authorization header that includes the token that has been provided to you from Papertrail. If you don’t have this token, please get in touch with Papertrail.

Once you have the token you will need to supply it for every request as a Authorization header:

Authorization: Basic {token}

Uploads ¶

You can store images and uploads (such as PDFs) that can be included with each product import. If you post a different file with the same name as a previous uploaded file, the original file will be overwritten.

Note In order to include an upload in an import, you must upload the file before creating the import!

Imports ¶

An import is a list of products that you want to add to the Papertrail manufacturer’s database. You can add new or replace existing products by creating a new import.

When an import is created, the products are processed asynchronously. You will be able to check on the progress of an import by making a GET request using the id that was provided when the import was created. If there are errors with the import, those errors will be included as part of the response.

Products have required top level attributes, as well as customisable “fields” that allow you to define the properties of the product.

The top level attributes are:

• Name

  The name of the product. This is a required attribute.

• Description

  A description of the product. This is an optional attribute.

• Images

  A list of images that should be associated with the product. This should be a list of file names of images that you have already uploaded to the manufacturers database.

• Uploads

  A list of uploads that should be associated with the product. This should be a list of file names of uploads that you have already uploaded to the manufacturers database.

• Checklists

  A list of checklist ids that should be associated with the product. You should have a list of availble ids that can be associated with a product. If you don’t already have this list, please speak to your Papertrail representative.

• Identifier

  An attribute to identify existing products to be updated. When updating existing products, you need to provide a way to identify the product(s) that should be updated. For example, if you want to update a unique product, you could pass the unique RFID number of that product. Alternatively, if you wanted to update all products with a certain model number, you could use that value as the identifier. This attribute is only required if you are updating existing products.

  The customisable fields attributes are:

  • Label The label of the field. This is a required attribute where the value should be a string. For example, “Barcode”.

  • Type The type of the field. This is a required attribute. You can choose from the following options (array, date, identifier, string, rfid). If you require additional types, please contact your Papertrail representative. Each type has different requirements for the value that should be passed with it.

    • Date: A string in the format of Y-m-d
    • Identifer: A string or integer
    • String: a string
    • RFID: a string or integer
    • Array: a list of valid types

  • Value

    The value of the field. This is a required attribute. The value should be appropriate for the given type of the field.

  • Unique

    Determines if the field should be marked as unique. This is a required field where the value should be a boolean. For example, a unique RFID field should be marked as unique.

  • Generic

    Determines if the field should be marked as generic. This is a required field where the value should be a boolean. All non-unique fields should be marked as generic. However, fields such as the date of manufacturer should be marked as not generic as that value is specific to that individual product.

  • Searchable

    Determines if the field should be searchable. This is a required field where the value should be a boolean. All unique fields should be marked as searchable, plus any non-unique fields that would be appropriate for searching. If you are unsure about which fields to mark as searchable, please speak to your Papertrail representative.

  • Internal Identifier

    Determines if the field should be marked as an internal identifier. This is a required field where the value should be a boolean. All unique fields should be marked as being an internal identifier, as well as any fields that you would use to identify products for updates. For example, model or part number.

Walkthrough ¶

Making requests ¶

In order to make requests to the Papertrail API you are going to need an access token. If you don’t already have an access token you will need to request one by speaking to your Papertrail representative. For the purposes of this tutorial we will be using the following token:

UwIlzlDTxzBRoEvEabWtS2c957Cdw9Q8WSXQ1kRerl8coz1g

In order to use the access token, you must provide it as an Authorization: Basic header of the HTTP request:

Authorization: Basic UwIlzlDTxzBRoEvEabWtS2c957Cdw9Q8WSXQ1kRerl8coz1g

Next we need to provide an Accept header that specifies the version of the API we would like to use. For the purposes of this tutorial we will be using the following Accept header:

Accept: application/vnd.papertrail.api+json; version=1.0

Finally we should also provide the correct Content-Type for the request.

For making JSON requests, you should use:

Content-Type: application/json

For uploading files, you should use:

Content-Type: multipart/form-data

Adding uploads ¶

Before we create an import, first we have to upload any images or PDFs that will be referenced by the products.

To do that we can send a POST request with the following command:

curl -X POST https://api.papertrail.io/manufacturers/uploads \
    -F "file=@kayak.jpg" \
    -H "Authorization: Basic UwIlzlDTxzBRoEvEabWtS2c957Cdw9Q8WSXQ1kRerl8coz1g" \
    -H "Accept: application/vnd.papertrail.api+json; version=1.0" \
    -H "Content-Type: multipart/form-data"

This will return the url of the uploaded file if the request has been successfull:

{
    "data": {
        "url":"https://s3-eu-west-1.amazonaws.com/pt-manufacturers-products/acme/kayak.jpg"
    }
}

Each file that is uploaded must have a unique name. If you wish to modify an existing file, simply upload a new file with the same name as the existing file.

Creating imports ¶

Once all of the uploads have been added to Papertrail a new import can be created. The data to be sent to Papertrail should look like this:

{
    "products": [
        {
           "name": "Unisex Adult Kayak",
           "description": "Unisex adult kayak",
           "images": [
               "kayak.jpg"
           ],
           "uploads": [
               "kayak-instructions.pdf"
           ],
           "checklists": [
               "71e23a1a-e44a-4348-ace2-603c57ec0a77"
           ],
           "fields": [
               {
                  "label": "RFID",
                  "type": "rfid",
                  "value": "6FkpTvWKK8mxzGM4NIVY",
                  "unique": true,
                  "generic": false,
                  "searchable": true,
                  "internal_identifier": true
              },
              {
                 "label": "Date of manufacture",
                 "type": "date",
                 "value": "2018-03-02",
                 "unique": false,
                 "generic": false,
                 "searchable": false,
                 "internal_identifier":false
             },
             {
                "label": "Colour",
                "type": "string",
                "value": "Red",
                "unique": false,
                "generic": true,
                "searchable": false,
                "internal_identifier":false
            },
            {
                "label": "Model",
                "type": "string",
                "value": "Aqua2000",
                "unique": false,
                "generic": true,
                "searchable": true,
                "internal_identifier": true
            }
           ]
        }
    ]
}

Here we have a list of products to be imported into Papertrail (in this case, just one product). Each product must have a name. You can also optionally supply a list of images, a list of uploads, and a list of checklists to be associated with the product.

The images and uploads must refer to the same file name as the files that were uploaded in the previous step.

Each of the customisable properties of the product are included as fields. In the example above we are including the following fields:

• A unique RFID field that will be searchable and used as an internal identifier to identify the product in the future. As this is a unique field, it cannot be a generic field.

• The date the product was manufacturered. This is not a unique field and it is not a generic field as it is specific to this individual product. We don’t want to be able to search on date fields and we don’t want to use the manufacturer date as an internal identifier.

• The colour is a non-unique, generic attribute of the product. We also don’t want to be able to search on the colour and we don’t want to use it as an internal identifiery because it isn’t specific to this product.

• The model of the product is not unique but it is generic as there could be variations. We should be able to search on the model to list all of the variations, and we should use it as an internal identifier as we might want to update across the entire line of products.

curl -X POST https://api.papertrail.io/manufacturers/imports \
    -d @data.json \
    -H "Authorization: Basic UwIlzlDTxzBRoEvEabWtS2c957Cdw9Q8WSXQ1kRerl8coz1g" \
    -H "Accept: application/vnd.papertrail.api+json; version=1.0" \
    -H "Content-Type: application/json"

This will return the following response on success:

{
   "data":{
      "id":"ec0064f2-2b06-4750-a114-844b99c39664",
      "completed_at":null,
      "has_errors":false,
      "new":0,
      "updated":0,
      "segments":{
         "data":[
            {
               "id":"012ace5a-57a0-444c-8bd7-50428345cec0",
               "completed_at":null,
               "errors":[]
            }
         ]
      }
   }
}

The import has now been accepted and will be processed. The import is split into segments and processed sequentially. Once all of the segments of the import have been processed the import will be marked as complete.

If any of the segments produce an error, the has_errors property will show as true and the relevant segment will contain details of the error.

As the segments are processed the new and updated totals will increment. This will show you how the import has been processed so you can ensure that existing products have been updated correctly.

Update existing products ¶

To update existing products, you should create a new import with the new product data. In order to identify existing products you should pass an identifier top level attribute:

For example, to update a single unique product you would use a unique internal identifier field:

{
    "products": [
        {
           "name": "Unisex Adult Kayak",
           "description": "Unisex adult kayak",
           "identifier": "6FkpTvWKK8mxzGM4NIVY",
           "images": ["kayak.jpg"],
           "uploads": ["kayak-instructions.pdf"],
           "checklists": [],
           "fields": [
             {
                "label": "Colour",
                "type": "string",
                "value": "Blue",
                "unique": false,
                "generic": true,
                "searchable": false,
                "internal_identifier":false
            }
           ]
        }
    ]
}

Here we have a list of products to be updated (in this case, just one product). You can include a mix of new and updated products in a single import.

Monitoring for errors ¶

Due to the fact that the import is accepted and processed separately, it’s up to you to monitor existing imports for errors. If you find that an import has errored you can correct and resend the data to try again.

To view the details of an import, you can make a GET request using the relevant id:

curl https://api.papertrail.io/manufacturers/imports/ec0064f2-2b06-4750-a114-844b99c39664 \
    -H "Authorization: Basic UwIlzlDTxzBRoEvEabWtS2c957Cdw9Q8WSXQ1kRerl8coz1g" \
    -H "Accept: application/vnd.papertrail.api+json; version=1.0" \
    -H "Content-Type: application/json"

This will return the import with updated totals:

{
   "data":{
      "id":"ec0064f2-2b06-4750-a114-844b99c39664",
      "completed_at":"2018-03-27T14:04:50+0000",
      "has_errors":false,
      "new":1,
      "updated":0,
      "segments":{
         "data":[
            {
               "id":"012ace5a-57a0-444c-8bd7-50428345cec0",
               "completed_at":"2018-03-27T14:04:50+0000",
               "errors":[]
            }
         ]
      }
   }
}

Alternatively, you can list all the imports that have been created:

curl https://api.papertrail.io/manufacturers/imports \
    -H "Authorization: Basic UwIlzlDTxzBRoEvEabWtS2c957Cdw9Q8WSXQ1kRerl8coz1g" \
    -H "Accept: application/vnd.papertrail.api+json; version=1.0" \
    -H "Content-Type: application/json"