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 procurement scorecards to automatically update their Preferential Procurement scoring. The meat of procurement scorecards is the line items - the actual spending per supplier but the reading and writing of those is handled separately. The reads and writes below pertain to the procurement scorecard only.

The following actions are available:

Heart Beat

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 Procurement Scorecards

Typical JSON response:

[{

    period: "year",

    start_date: "01/01/2010",

    end_date: "31/12/2010",

    charter: "Forestry",

    financial_year: "2010",

    description: "December 2010",

    weight_black_and_black_female_owned_spending: "false",

    include_later_supplier_scorecards: "false",

    sum_tmps_from_line_items: "true",

    total_measured_procurement_spend: "300000.0",

    id: "1",

    created_at: "04/03/2011 13:31:48",

    updated_at: "02/10/2014 12:00:51",

    published: "false"

  }, {

    start_date: "01/10/2011",

    end_date: "30/09/2012",

    charter: "CoGP (Generic)",

    financial_year: "2012",

    description: "YTD 2012",

    weight_black_and_black_female_owned_spending: "false",

    include_later_supplier_scorecards: "false",

    sum_tmps_from_line_items: "false",

    total_measured_procurement_spend: "1000000.0",

    id: "2",

    created_at: "05/07/2012 13:19:47",

    updated_at: "17/09/2013 11:39:07",

    published: "false"

}]

Typical XML response:

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

<objects type="array">

<object>

<period>year</period>

<start-date>01/01/2010</start-date>

<end-date>31/12/2010</end-date>

<charter>Forestry</charter>

<financial-year>2010</financial-year>

<description>December 2010</description>

<weight-black-and-black-female-owned-spending>false</weight-black-and-black-female-owned-spending>

<include-later-supplier-scorecards>false</include-later-supplier-scorecards>

<sum-tmps-from-line-items>true</sum-tmps-from-line-items>

<total-measured-procurement-spend>300000.0</total-measured-procurement-spend>

<id>1</id>

<created-at>04/03/2011 13:31:48</created-at>

<updated-at>02/10/2014 12:00:51</updated-at>

<published>false</published>

</object>

<object>

<period>year</period>

<start-date>01/10/2011</start-date>

<end-date>30/09/2012</end-date>

<charter>CoGP (Generic)</charter>

<financial-year>2012</financial-year>

<description>YTD 2012</description>

<weight-black-and-black-female-owned-spending>false</weight-black-and-black-female-owned-spending>

<include-later-supplier-scorecards>false</include-later-supplier-scorecards>

<sum-tmps-from-line-items>false</sum-tmps-from-line-items>

<total-measured-procurement-spend>1000000.0</total-measured-procurement-spend>

<id>2</id>

<created-at>05/07/2012 13:19:47</created-at>

<updated-at>17/09/2013 11:39:07</updated-at>

<published>false</published>

</object>

</objects>

View Procurement Scorecard

 Typical successful JSON response:

[{

    period: "year",

    start_date: "01/01/2010",

    end_date: "31/12/2010",

    charter: "Forestry",

    financial_year: "2011",

    description: "December 2010",

    weight_black_and_black_female_owned_spending: "false",

    include_later_supplier_scorecards: "false",

    sum_tmps_from_line_items: "true",

    total_measured_procurement_spend: "300000.0",

    id: "1",

    created_at: "04/03/2011 13:31:48",

    updated_at: "02/10/2014 12:00:51",

    published: "false"

  }]

Typical failed JSON response:

{errors: "Scorecard not found"} 

Typical successful XML response:

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

<hash>

<period>year</period>

<start-date>01/01/2010</start-date>

<end-date>31/12/2010</end-date>

<charter>Forestry</charter>

<financial-year>2010</financial-year>

<description>December 2010</description>

<weight-black-and-black-female-owned-spending>false</weight-black-and-black-female-owned-spending>

<include-later-supplier-scorecards>false</include-later-supplier-scorecards>

<sum-tmps-from-line-items>true</sum-tmps-from-line-items>

<total-measured-procurement-spend>300000.0</total-measured-procurement-spend>

<id>1</id>

<created-at>04/03/2011 13:31:48</created-at>

<updated-at>02/10/2014 12:00:51</updated-at>

<published>false</published>

</hash>

 Typical failed XML response:

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

<hash>

<errors>Scorecard not found</errors>

</hash>

Create Procurement Scorecard

 Typical JSON request:

{

  "procurement_scorecard": {

    "period": "ytd",

    "start_date": "01/03/2010",

    "end_date": "30/06/2010",

    "financial_year": 2011,

    "description": "YTD Scorecard",

    "charter": "ICT",

    "weight_black_and_black_female_owned_spending": "true",

    "include_later_supplier_scorecards": "true",

    "sum_tmps_from_line_items": "true"

  }

}

Typical successful JSON response:

{

  period: "ytd",

  start_date: "01/03/2010",

  end_date: "30/06/2010",

  charter: "ICT",

  financial_year: "2011",

  description: "YTD Scorecard",

  weight_black_and_black_female_owned_spending: "true",

  include_later_supplier_scorecards: "true",

  sum_tmps_from_line_items: "true",

  total_measured_procurement_spend: "",

  id: "3",

  created_at: "03/10/2014 05:24:46",

  updated_at: "03/10/2014 05:24:46",

  published: "false"

}

Typical failed JSON response:

{

    "'period' is not included in the list",

    "'end_date' cannot be before start date",

    "'financial_year' can't be blank"
  ]

}

Typical XML request:

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

<procurement_scorecard>

<period>ytd<period>

<start_date>01/03/2010<start_date>

<end_date>30/06/2010<end_date>

<financial_year>2011<financial_year>

<description>YTD Scorecard<description>

<charter>ICT<charter>

<weight_black_and_black_female_owned_spending>true<weight_black_and_black_female_owned_spending>

<include_later_supplier_scorecards>true<include_later_supplier_scorecards>

<sum_tmps_from_line_items>true<sum_tmps_from_line_items>

</procurement_scorecard>

Typical successful XML response:

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

<hash>

<period>ytd</period>

<start-date>01/03/2010</start-date>

<end-date>30/06/2010</end-date>

<charter>ICT</charter>

<financial-year>2011</financial-year>

<description>YTD Scorecard</description>

<weight-black-and-black-female-owned-spending>true</weight-black-and-black-female-owned-spending>

<include-later-supplier-scorecards>true</include-later-supplier-scorecards>

<sum-tmps-from-line-items>true</sum-tmps-from-line-items>

<total-measured-procurement-spend></total-measured-procurement-spend>

<id>16246</id>

<created-at>08/10/2014 12:20:24</created-at>

<updated-at>08/10/2014 12:20:24</updated-at>

<published>false</published>

</hash>

Typical failed XML response:

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

<hash>

<errors type="array">

<error>'period' is not included in the list</error>

<error>'end_date' cannot be before start date</error>

<error>'financial_year' can't be blank</error>

</errors>

</hash>

Update Procurement Scorecard

Typical JSON request:

{

  "procurement_scorecard": {

    "period": "year",

    "description": "YTD Scorecard (fixed)",

    "weight_black_and_black_female_owned_spending": "false",

    "sum_tmps_from_line_items": "false",

    "total_measured_procurement_spend": "100000"

  }

}

Typical successful JSON response: 

{

  period: "year",

  start_date: "01/03/2010",

  end_date: "30/06/2010",

  charter: "ICT",

  financial_year: "2011",

  description: "YTD Scorecard (fixed)",

  weight_black_and_black_female_owned_spending: "false",

  include_later_supplier_scorecards: "true",

  sum_tmps_from_line_items: "false",

  total_measured_procurement_spend: "100000.0",

  id: "3",

  created_at: "03/10/2014 05:24:46",

  updated_at: "03/10/2014 05:24:46",

  published: "false"

}

Typical failed JSON response:

{

    "'period' is not included in the list",

    "'end_date' cannot be before start date",

    "'financial_year' can't be blank"
  ]

}

Typical XML request:

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

<procurement_scorecard>

<period>year</period>

<description>YTD Scorecard (fixed)</description>

<weight_black_and_black_female_owned_spending>false</weight_black_and_black_female_owned_spending>

<include_later_supplier_scorecards>false</include_later_supplier_scorecards>

<total_measured_procurement_spend >100000</total_measured_procurement_spend>

</procurement_scorecard> 

Typical successful XML response:

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

<hash>

<period>year</period>

<start-date>01/03/2010</start-date>

<end-date>30/06/2010</end-date>

<charter>ICT</charter>

<financial-year>2011</financial-year>

<description>YTD Scorecard (fixed)</description>

<weight-black-and-black-female-owned-spending>false</weight-black-and-black-female-owned-spending>

<include-later-supplier-scorecards>false</include-later-supplier-scorecards>

<sum-tmps-from-line-items>false</sum-tmps-from-line-items>

<total-measured-procurement-spend>100000</total-measured-procurement-spend>

<id>1</id>

<created-at>08/10/2014 12:20:24</created-at>

<updated-at>08/10/2014 12:20:24</updated-at>

<published>false</published>

</hash>

Typical failed XML response:

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

<hash>

<errors type="array">

<error>'period' is not included in the list</error>

<error>'end_date' cannot be before start date</error>

<error>'financial_year' can't be blank</error>

</errors>

</hash>

Delete Procurement Scorecard

Typical successful response: 

No content for a deleted resource

Typical failed JSON response:

{errors: "Scorecard not found"} 

 Typical failed XML response:

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

<hash>

<errors>Scorecard not found</errors>

</hash>

Publish Procurement Scorecard

Typical JSON response (the change is in bold below):

{

  period: "year",

  start_date: "01/03/2010",

  end_date: "30/06/2010",

  charter: "ICT",

  financial_year: "2011",

  description: "YTD Scorecard (fixed)",

  weight_black_and_black_female_owned_spending: "false",

  include_later_supplier_scorecards: "true",

  sum_tmps_from_line_items: "false",

  total_measured_procurement_spend: "100000.0",

  id: "3",

  created_at: "03/10/2014 05:24:46",

  updated_at: "03/10/2014 05:24:46",

  published: "true"

}

Typical XML response (the change is in bold below):

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

<hash>

<period>year</period>

<start-date>01/03/2010</start-date>

<end-date>30/06/2010</end-date>

<charter>ICT</charter>

<financial-year>2011</financial-year>

<description>YTD Scorecard (fixed)</description>

<weight-black-and-black-female-owned-spending>false</weight-black-and-black-female-owned-spending>

<include-later-supplier-scorecards>false</include-later-supplier-scorecards>

<sum-tmps-from-line-items>false</sum-tmps-from-line-items>

<total-measured-procurement-spend>100000</total-measured-procurement-spend>

<id>1</id>

<created-at>08/10/2014 12:20:24</created-at>

<updated-at>08/10/2014 12:20:24</updated-at>

<published>true</published>

</hash>

Unpublish Procurement Scorecard

Typical JSON response (the change is in bold below): 

{

  period: "year",

  start_date: "01/03/2010",

  end_date: "30/06/2010",

  charter: "ICT",

  financial_year: "2011",

  description: "YTD Scorecard (fixed)",

  weight_black_and_black_female_owned_spending: "false",

  include_later_supplier_scorecards: "true",

  sum_tmps_from_line_items: "false",

  total_measured_procurement_spend: "100000.0",

  id: "3",

  created_at: "03/10/2014 05:24:46",

  updated_at: "03/10/2014 05:24:46",

  published: "false"

}

Typical XML response (the change is in bold below):

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

<hash>

<period>year</period>

<start-date>01/03/2010</start-date>

<end-date>30/06/2010</end-date>

<charter>ICT</charter>

<financial-year>2011</financial-year>

<description>YTD Scorecard (fixed)</description>

<weight-black-and-black-female-owned-spending>false</weight-black-and-black-female-owned-spending>

<include-later-supplier-scorecards>false</include-later-supplier-scorecards>

<sum-tmps-from-line-items>false</sum-tmps-from-line-items>

<total-measured-procurement-spend>100000</total-measured-procurement-spend>

<id>1</id>

<created-at>08/10/2014 12:20:24</created-at>

<updated-at>08/10/2014 12:20:24</updated-at>

<published>false</published>

</hash>

Procurement Scorecard Read Fields

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

Procurement Scorecard Write Fields 

* TMPS is optional if "sum_tmps_from_line_items" is set to "true"

Scorecard Period Values

• "month"
• "ytd" (year to date)
• "year"

Charter Values

• "CoGP (Generic)"
• "Revised CoGP"
• "Chartered Accountancy"
• "Construction BEP"
• "Construction Contractors"
• "Financial"
• "Forestry"
• "ICT"
• "Property - Internal Management"
• "Property - Owners"
• "Specialised"
• "Transport - Forwarding & Clearing"
• "Transport - Road Freight"
• "Transport - Public Sector"