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

URL	/api/v1/procurement_scorecards/heartbeat
Request Method	GET
Response (Success)	Code	200
	Body	Account name
Response (Failure)	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 Procurement Scorecards

URL	/api/v1/procurement_scorecards
Request Method	GET
Response (Success)	Code	200
	Body	An array of Procurement Scorecard Read Fields
Response (Failure)	N/A

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

URL	/api/v1/procurement_scorecard/[scorecard id]
Request Method	GET
Response (Success)	Code	200
	Body	Procurement Scorecard read fields for requested scorecard
Response (Failure)	Code	404
	Reason	Procurement Scorecard not found

 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

URL	/api/v1/procurement_scorecards
Request Method	POST
Request Body	A JSON schema containing the Procurement Scorecard write fields
Response (Success)	Code	200
	Body	Procurement Scorecard read fields for scorecard
Response (Failure)	Code	400
	Body	Array of errors
	Reason	Missing/invalid field values (see below for examples)

 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

URL	/api/v1/procurement_scorecard/[scorecard id]
Request Method	PUT
Request Body	A JSON schema containing the Procurement Scorecard write fields - only the fields being overwritten need be submitted
Response (Success)	Code	200
	Body	Procurement Scorecard read fields for updated scorecard
Response (Failure)	Code	400
	Body	Array of errors
	Reason	Missing/invalid field values, eg. ["'period' is not included in the list", "'end_date' cannot be before start date"]
	Code	404
	Reason	Procurement Scorecard not found

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

URL	/api/v1/procurement_scorecard/[scorecard id]
Request Method	DELETE
Response (Success)	Code	204
	Body	N/A
Response (Failure)	Code	404
	Body	None
	Reason	Procurement Scorecard not found

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

URL	/api/v1/procurement_scorecard/[scorecard id]/publish
Request Method	PUT
Request Body	N/A
Response (Success)	Code	200
	Body	Procurement Scorecard read fields for updated scorecard
Response (Failure)	Code	404
	Body	None
	Reason	Procurement Scorecard not found

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

URL	/api/v1/procurement_scorecard/[scorecard id]/unpublish
Request Method	PUT
Request Body	N/A
Response (Success)	Code	200
	Body	Procurement Scorecard read fields for updated scorecard
Response (Failure)	Code	404
	Body	None
	Reason	Procurement Scorecard not found

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.

Description	Field Name	Possible/Example Values
Scorecard Period	period	"one_month"
Start Date of Period Covered	start_date	"01/05/2013"(format: dd/mm/yyyy)
End Date of Period Covered	end_date	"01/05/2013"(format: dd/mm/yyyy)
Charter	charter	"rcogp"
Financial Year	financial_year	"2014"
Description	description	"New Scorecard"
Weight black and female owned spending to BEE recognition levels	weight_black_and_black_female_owned_spending	"true"
Include supplier scorecards issues after measurement period	include_later_supplier_scorecards	"true"
Sum TMPS from line items	sum_tmps_from_line_items	"true"
TMPS	total_measured_procurement_spend	"200000"
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)

  

Procurement Scorecard Write Fields 

Description	Field Name	Data Type	Optional	Default	Example Values
Scorecard Period	period	String	No		"month" (See below for other values)
Start Date of Period Covered	start_date	String	No		"01/05/2013"(format: dd/mm/yyyy)
End Date of Period Covered	end_date	String	No		"01/05/2013"(format: dd/mm/yyyy)
Charter	charter	String	No		"rcogp" (see list below for rest of them)
Financial Year	financial_year	Integer	No		"2014"
Description	description	String	Yes	""	"New Scorecard"
Weight black and female owned spending to BEE recognition levels	weight_black_and_black_female_owned_spending	Boolean	Yes	"false"	"true"
Include supplier scorecards issues after measurement period	include_later_supplier_scorecards	Boolean	Yes	"false"	"true"
Sum TMPS from line items	sum_tmps_from_line_items	Boolean	Yes	"false"	"true"
TMPS	total_measured_procurement_spend	Integer	No*		"200000"

* 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"