Line Items

Line Items

Overview

Line Items form the meat of the Procurement Scorecard data. They record how much was spent on which suppliers. It's only possible to use the API to read and write line item details, not update or delete them, so take care when making changes. To make it easier to process many line items at once, it's possible to create them one-at-a-time or as a bulk transaction.

 

The following actions are available:

Heart Beat

URL /api/v1/procurement_scorecards/[Scorecard ID]/line_items/heartbeat
Request Method GET 
Response (Success) Code 200
  Body Account name
Response (Failure) Code 404
  Reason Procurement Scorecard not found
  Code 401
  Reason Authentication failed

Typical JSON response:

{account: "Widgets Cape Town"}

Typical XML response: 

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<account>Widgets Cape Town</account>

</hash>

 

View All Line Items for a Procurement Scorecard

URL /api/v1/procurement_scorecards/[Scorecard ID]/line_items
Request Method GET 
Response (Success) Code 200
  Body An array of Line Item Read Fields
Response (Failure) Code 404 
  Reason Procurement Scorecard not found

 

Typical successful JSON response:

[{

    "spend":"25897654.32",

    "id":"1",

    "created_at":"04/03/2011 13:32:03",

    "updated_at":"04/03/2011 13:32:03",

    "supplier_vendor_code":"CT001",

    "supplier_trading_name":"Widgets Cape Town"

  }, {

    "spend":"25196888.66",

    "id":"2",

    "created_at":"04/03/2011 13:32:03",

    "updated_at":"04/03/2011 13:32:03",

    "supplier_vendor_code":"INT001",

    "supplier_trading_name":"Widgets International"

}]

 Typical failed JSON response:

{

  errors: "Scorecard not found"

}

 

Typical successful XML response:

<?xml version="1.0" encoding="UTF-8"?>

<objects type="array">

<object>

<spend type="decimal">25897654.32</spend>

<id>1</id>

<created-at>04/03/2011 13:32:03</created-at>

<updated-at>04/03/2011 13:32:03</updated-at>

<supplier-vendor-code>CT001</supplier-vendor-code>

<supplier-trading-name>Widgets Cape Town</supplier-trading-name>

</object>

<object>

<spend type="decimal">25196888.66</spend>

<id>2</id>

<created-at>04/03/2011 13:32:03</created-at>

<updated-at>04/03/2011 13:32:03</updated-at>

<supplier-vendor-code>INT001</supplier-vendor-code>

<supplier-trading-name>Widgets International</supplier-trading-name>

</object>

</objects>

 

Typical failed XML response:

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<errors>Scorecard not found</errors>

</hash>

 

Create Line Items

URL /api/procurement_scorecards/[Scorecard ID]/line_items
Request Method POST 
Request Body

An array containing JSON schemas with the Line Item write fields. There is no minimum or maximum requirement. A single line item can be written this way, just as effectively as many of them at the same time.
Response (Success)  Code 200
  Body An array of JSON schemas containing the Line Item read fields
Response (Failure)  Code 400
  Body

If any of the line items is invalid, the entire batch will be held back. The response body will contain a list of JSON/XML schemas (the original data) for each failed line item, together with an extra value (in each schema) describing the errors in trying to save that line item (see below for an example)
  Reason

Missing/invalid field values
  Code

404
  Reason Procurement Scorecard not found

Typical JSON request:

{

  "line_items": [{

    "supplier_vendor_code": "CB00033",

    "spend": "4000"

  }, {

    "supplier_vendor_code": "CB00035",

    "spend": "8000"

  }]

}

 

Typical successful JSON response:

[{

    "spend":"4000.0",

    "id":"1",

    "created_at":"02/10/2014 10:08:44",

    "updated_at":"02/10/2014 10:08:44",

    "supplier_vendor_code":"BEE001",

    "supplier_trading_name":"BEE Africa - Cape Town"

  }, {

    "spend":"8000.0",

    "id":"2",

    "created_at":"02/10/2014 10:08:44",

    "updated_at":"02/10/2014 10:08:44",

    "supplier_vendor_code":"BEE002",

    "supplier_trading_name":"BEE Africa - Johannesburg"}]

 

Typical failed JSON request (observe that of the 3 line items, only the 2 that failed are included in the response):

{

  "line_items": [{

    "supplier_vendor_code": "WRONG CODE",

    "spend": "4000"

  }, {

    "supplier_vendor_code": "BEE001",

    "spend": "4000"

  }, {

    "supplier_vendor_code": "BEE002",

    "spend": "NAN"

  }]

}

  

Typical failed JSON response:

{

  errors: [{

    supplier_vendor_code: "WRONG_CODE"

    spend: "4000"

    errors: ["'supplier_vendor_code' not found. First create a supplier using this vendor code."]

  }, {

    supplier_vendor_code: "BEE002"

    spend: "NAN"

    errors: ["'spend' is not a number"]

  }]

}

 

Typical XML request:

<?xml version="1.0" encoding="UTF-8"?>

<line_items type="array">

<line_item>

<supplier_vendor_code>CB00033</supplier_vendor_code>

<spend>4000</spend>

</line_item>

<line_item>

<supplier_vendor_code>CB00035</supplier_vendor_code>

<spend>8000</spend>

</line_item>

</line_items>

 

Typical successful XML response:

<?xml version="1.0" encoding="UTF-8"?>

<objects type="array">

<object>

<spend type="decimal">4000.0</spend>

<id>1</id>

<created-at>08/10/2014 13:46:34</created-at>

<updated-at>08/10/2014 13:46:34</updated-at>

<supplier-vendor-code>BEE001</supplier-vendor-code>

<supplier-trading-name>BEE Africa - Cape Town</supplier-trading-name>

</object>

<object>

<spend type="decimal">8000.0</spend>

<id>2</id>

<created-at>08/10/2014 13:46:34</created-at>

<updated-at>08/10/2014 13:46:34</updated-at>

<supplier-vendor-code>BEE002</supplier-vendor-code>

<supplier-trading-name>BEE Africa - Johannesburg</supplier-trading-name>

</object>

</objects>

 

Typical failed XML request (observe that of the 3 line items, only the 2 that failed are included in the response):

<?xml version="1.0" encoding="UTF-8"?>

<line_items type="array">

<line_item>

<supplier_vendor_code>WRONG CODE</supplier_vendor_code>

<spend>4000</spend>

</line_item>

<line_item>

<supplier_vendor_code>BEE001</supplier_vendor_code>

<spend>4000</spend>

</line_item>

<line_item>

<supplier_vendor_code>BEE002</supplier_vendor_code>

<spend>NAN</spend>

</line_item>

</line_items>

 

Typical failed XML response:

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<errors type="array">

<error>

<supplier-vendor-code>WRONG CODE</supplier-vendor-code>

<spend>4000</spend>

<errors type="array">

<error>'supplier_vendor_code' not found. First create a supplier using this vendor code.</error>

</errors>

</error>

<error>

<supplier-vendor-code>BEE002</supplier-vendor-code>

<spend>NAN</spend>

<errors type="array">

<error>'spend' is not a number</error>

</errors>

</error>

</errors>

</hash>

 

Line Item Read Fields

Note that all fields will be returned as strings, even fields of date or boolean data types.

Description Field Name Possible/Example Values

Supplier's Vendor Code

 supplier_vendor_code "BEE001"
Supplier's Trading Name supplier_trading_name "Widgets in Africa"
Spend Amount spend 100000
Line Item ID id 20
Created Date created_at  "01/05/2014 22:23:21" (format: dd/mm/yyyy hh:mm:ss)
Last Modified Date modified_at  "01/05/2014 22:23:21" (format: dd/mm/yyyy hh:mm:ss)

  

Line Item Write Fields 

Description Field Name Data Type Optional Default Example Values

Supplier's Vendor Code

 supplier_vendor_code

String

 No  

"BEE001"
Spend Amount spend

Decimal(9,2)

 No     

 

    • Related Articles

    • Release Notes

      v1 Introduced Suppliers API Introduced Procurement Scorecard API Introduced Line Items API Implemented Digest Authentication

    • Procurement Scorecards

      Overview Procurement Scorecards collate information about what was spent on what suppliers over a certain time period. It is to procurement scorecards that scorecards in the BEEtoolkit can be linked for clients wanting the integration, and for their ...

    • Creating a new Scenario

      Create a new Scenario 1. Select the Scenario Scorecards icon from the dashboard page, as shown below. 2. This action (Step 1) will take you to the screen below. To create a new scenario click on the New Scenario link, as indicated. 3. Complete the ...

    • Authentication

      All requests sent to the API must include a signature and the account identifier to authenticate the request. So add the following headers to all requests: Header Name Header Value Authorization Your account key Mpowered-Signature Calculated ...

    • How to set up commodities and classify purchases accordingly

      Step 1: Setting up your commodities Step 1.1: Log in to the Supplier Management System. On the dashboard, go to the 6th card, namely “User and Account Settings”, and click on “Commodity Classifications”: Step 1.2: This will take you to the following ...