How To Automate Offline Sales Import

This article will provide a guide to automate this process via the usage of our API.

To find out more about the manual upload of files, click here.

Prerequisites

• A user with access to the Powered By Jumbo admin platform with ‘Offline Sales Upload’ capability enabled.
• CSV file with the correct format

API

Authentication

Before you can upload a file for processing, you need to authenticate the API user.

Note that the channel that sales will be associated against will be

When using the API, sales will be recorded against the channel of the authenticated user in the same way it is done if the file was manually uploaded.

Make sure that whatever user you are authenticating with has the correct channel assigned to them.

URL

POST: {your-pbj-website}/api-admin/login

Header

"accept: application/json"
"Content-Type: application/json"

Request Body

{
  "username": "yourusername",
  "password": "yourpassword"
}

Response

200 Success Response

If valid credentials are provided, you will get a 200 success response. Most of the information can be ignored; the critical information you need to store is the “access_token”, “refresh_token” and the “channels”.

{
  "messages": [],
  "result": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6..truncated..lOk8gfh6HcwaQ",
    "refresh_token": "509bd88d-6177-4536-bdbd-64e242b677ee",
    "admin": {
      "capabilities": [
        "admin",
        "bulksales.upload"
      ],
      "channels": [
        {
          "channel_key": "charity_lotery",
          "channel_name": "Charity Lottery",
          "is_default": true
        }
      ],
      "email": "useremail@example.com",
      "id": "AAAA-BBBB-CCCC-DDDD",
      "name": "User Name"
    }
  }
}

401 Unauthorized

If the wrong credentials are provided, you will get a 401 response. If you get this response, check the credentials and try again.

{
  "messages": [
    {
      "code": "incorrect_details",
      "level": "error",
      "message": "Username or password is incorrect."
    }
  ]
}

Example Curl

curl -X POST "https://{your-pbj-website}/api-admin/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"password\":\"yourpassword\",\"username\":\"yourusername\"}"

File Upload

Once you have authentication credentials, you are ready to upload your ‘.CSV’ file for processing.

The file name is important. You will not be able to upload a file with the same name twice. We suggest a strong naming convention. For example, {channel}_{date}_{batch}.csv “direct-mail_20-04-2020_1.csv”

URL

POST: {your-pbj-website}/bulk-sales/files

Header

You will need to pass the access_token fetched as part of the authentication step to authorise this request.

"accept: application/json"
"Content-Type: multipart/form-data"
"Authorization: Bearer {{access_token}}"

Request Body

This request supports “multipart/form-data” as the body of the request with the .CSV file to be uploaded under the “file” field.

file: string($binary)

Response

202 Accepted

If the file is successfully uploaded, you will get a 202 response with the number of “records” accepted in the response body. You can use the “results” value as a final check to confirm that all records have been uploaded.

{
  "result": 34
}

400 Client Error (Already Uploaded)

A file can only be uploaded one time. If the system detects that the file has previously been uploaded, you will get a 400 error with the following message.

{
  "error": {
    "code": 400,
    "message": "This file has already been uploaded"
  }
}

400 Client Error (Invalid File)

If the file has invalid formatting, you will get a 400 error with the following message. Use the error.extended.errors object to debug what the formatting errors may be.

{
  "error": {
    "code": 400,
    "extended": {
      "additional_errors": 0,
      "error_fields": 2,
      "error_lines": 1,
      "errors": [
        {
          "line": 2,
          "messages": [
            "ORDER_ID is not a valid number",
            "DRAW_NO is not a valid number"
          ]
        }
      ]
    },
    "message": "File content contains one or more errors"
  }
}

Example CURL

curl -X POST "{your-pbj-website}/bulk-sales/files" -H "accept: application/json" -H "Content-Type: multipart/form-data" -H 'Authorization: Bearer {{access_token}}' -F "file=@derect-mail_20-04-2020_1.csv;type=text/csv"