Suppliers

Overview

Suppliers on the SMS represent organisations that you can allocate spending to in the Procurement Scorecards. To make it super-easy to work with suppliers using the API, you will be able to use your own unique supplier codes when creating, updating or reading a suppliers details and even when doing other activities via the API such as loading procurement scorecards.

The **following** actions are available for the Supplier API:

Heart Beat

URL	/api/v1/suppliers/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 Supplier

URL	/api/v1/suppliers/[vendor code]
Request Method	GET
Response (Success)	Code	200
	Body	Supplier Read Fields for requested supplier
Response (Failure)	Code	404
	Body	None
	Reason	Vendor Code not found

Typical response:

{

black_person_with_disability: "false",

cost_centre: "",

custom_1: "",

custom_2: "",

custom_3: "",

custom_4: "",

designated_group_supplier: "false",

primary_email: "",

empowering_supplier: "false",

enterprise_development_recipient: "false",

exclude_from_procurement_calculations: "false",

fax_number: "",

first_time_supplier: "false",

greater_than_five_percent_equity_by_black_individuals: "false",

minimum_three_year_contract: "false",

postal_address: "",

property_service_provider: "false",

province: "",

recipient_of_supplier_development_contributions: "false",

registered_name: "",

registration_number: "",

street_address: "",

telephone_number: "",

town: "Cape Town",

trading_name: "African Widgets - Cape Town",

vat_number: "1234567890",

vendor_code: "BEE001",

website: "",

created_at: "04/03/2011 13:24:00",

updated_at: "11/07/2011 09:11:31"

}

Create Supplier

URL	/api/v1/suppliers
Request Method	POST
Request Body	A hash containing the Supplier write fields
Response (Success)	Code	200
	Body	Supplier Read Fields for created supplier
Response (Failure)	Code	400
	Body	Array of errors
	Reason	Missing/invalid field values, eg. ["'trading_name' can't be blank", "'vendor_code' can't be blank"]

Typical JSON request:

{

"supplier": {

"trading_name": "African Widgets - Durban",

"vendor_code": "BEE003",

"registered_name": "African Widgets Durban (Pty) Ltd",

"registration_number": "12345678",

"vat_number": "1234567890",

"cost_centre": "Durban North",

"website": "www.african-widgets.com",

"primary_email": "test-person@example.com",

"street_address": "1 Aloe Way",

"postal_address": "1 Aloe Way",

"town": "Durban",

"telephone_number": "",

"fax_number": "",

"exclude_from_procurement_calculations": "true",

"enterprise_development_recipient": "true",

"black_person_with_disability": "true",

"property_service_provider": "true",

"greater_than_five_percent_equity_by_black_individuals": "true",

"empowering_supplier": "true",

"minimum_three_year_contract": "true",

"recipient_of_supplier_development_contributions": "true",

"first_time_supplier": "true",

"designated_group_supplier": "true",

"custom_1": "African Custom 1",

"custom_2": "",

"custom_3": "",

"custom_4": ""

}

Typical successful JSON response:

{

black_person_with_disability: "true",

cost_centre: "Durban North",

custom_1: "African Custom 1",

custom_2: "",

custom_3: "",

custom_4: "",

designated_group_supplier: "true",

primary_email: "test-person@example.com",

empowering_supplier: "true",

enterprise_development_recipient: "true",

exclude_from_procurement_calculations: "true",

fax_number: "",

first_time_supplier: "true",

greater_than_five_percent_equity_by_black_individuals: "true",

minimum_three_year_contract: "true",

postal_address: "1 Aloe Way",

property_service_provider: "true",

province: "",

recipient_of_supplier_development_contributions: "true",

registered_name: "African Widgets Durban (Pty) Ltd",

registration_number: "12345678",

street_address: "1 Aloe Way",

telephone_number: "",

town: "Durban",

trading_name: "African Widgets - Durban",

vat_number: "1234567890",

vendor_code: "BEE003",

website: "www.african-widgets.com",

created_at: "03/10/2014 09:21:12",

updated_at: "03/10/2014 09:21:12"

}

Typical failed JSON response:

{

errors: [

"'trading_name' can't be blank"

"'vat_number' must be a valid vat number"

]

}

Typical XML request:

<?xml version="1.0"?>

<trading_name>African Widgets - Durban</trading_name>

<vendor_code>BEE004</vendor_code>

<registered_name>African Widgets Durban (Pty) Ltd</registered_name>

<registration_number>12345678</registration_number>

<vat_number>1234567890</vat_number>

<cost_centre>Durban North</cost_centre>

<website>www.african-widgets.com</website>

<primary_email>test-person@example.com</primary_email>

<street_address>1 Aloe Way</street_address>

<postal_address>1 Aloe Way</postal_address>

<town>Durban</town>

<telephone_number></telephone_number>

<fax_number></fax_number>

<exclude_from_procurement_calculations>true</exclude_from_procurement_calculations>

<enterprise_development_recipient>true</enterprise_development_recipient>

<black_person_with_disability>true</black_person_with_disability>

<property_service_provider>true</property_service_provider>

<greater_than_five_percent_equity_by_black_individuals>true

</greater_than_five_percent_equity_by_black_individuals>

<empowering_supplier>true</empowering_supplier>

<minimum_three_year_contract>true</minimum_three_year_contract>

<recipient_of_supplier_development_contributions>true

</recipient_of_supplier_development_contributions>

<first_time_supplier>true</first_time_supplier>

<designated_group_supplier>true</designated_group_supplier>

<custom_1>African Custom 1</custom_1>

<custom_2></custom_2>

<custom_3></custom_3>

<custom_4></custom_4>

</supplier>

Typical successful XML response

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

<hash>

<black-person-with-disability>true</black-person-with-disability>

<cost-centre>Durban North</cost-centre>

<custom-1>African Custom 1</custom-1>

<custom-2></custom-2>

<custom-3></custom-3>

<custom-4></custom-4>

<designated-group-supplier>true</designated-group-supplier>

<primary-email>test-person@example.com</primary-email>

<empowering-supplier>true</empowering-supplier>

<enterprise-development-recipient>true</enterprise-development-recipient>

<exclude-from-procurement-calculations>true</exclude-from-procurement-calculations>

<fax-number></fax-number>

<first-time-supplier>true</first-time-supplier>

<greater-than-five-percent-equity-by-black-individuals>true</greater-than-five-percent-equity-by-black-individuals>

<minimum-three-year-contract>true</minimum-three-year-contract>

<postal-address>1 Aloe Way</postal-address>

<property-service-provider>true</property-service-provider>

<recipient-of-supplier-development-contributions>true</recipient-of-supplier-development-contributions>

<registered-name>African Widgets Durban (Pty) Ltd</registered-name>

<registration-number>12345678</registration-number>

<street-address>1 Aloe Way</street-address>

<telephone-number></telephone-number>

<town>Durban</town>

<trading-name>African Widgets - Durban</trading-name>

<vat-number>1234567890</vat-number>

<vendor-code>BEE004</vendor-code>

<website>www.african-widgets.com</website>

<created-at>08/10/2014 10:42:03</created-at>

<updated-at>08/10/2014 10:42:03</updated-at>

</hash>

Typical failed XML response:

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

<hash>

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

<error>'vat_number' must be a valid vat number</error>

</errors>

</hash>

Update Supplier

URL	/api/v1/suppliers/[vendor code]
Request Method	PUT
Request Body	A hash containing the Supplier write fields - only the fields being overwritten need be submitted
Response (Success)	Code	200
	Body	Supplier Read Fields for updated supplier
Response (Failure)	Code	400
	Body	Array of errors
	Reason	Missing/invalid field values, eg. ["'primary_email' is not an email"]
	Code	404
	Body	None
	Reason	Vendor Code not found

Typical JSON request:

{

"supplier": {

"postal_address": "PO Box 555",

"exclude_from_procurement_calculations": "false",

"enterprise_development_recipient": "false",

"custom_2": "Johnnys client"

}

Typical successful JSON response:

{

black_person_with_disability: "true",

cost_centre: "Durban North",

custom_1: "African Custom 1",

custom_2: "Johnnys client",

custom_3: "",

custom_4: "",

designated_group_supplier: "true",

primary_email: "test-person@example.com",

empowering_supplier: "true",

enterprise_development_recipient: "false",

exclude_from_procurement_calculations: "false",

fax_number: "",

first_time_supplier: "true",

greater_than_five_percent_equity_by_black_individuals: "true",

minimum_three_year_contract: "true",

postal_address: "PO Box 555",

property_service_provider: "true",

province: "",

recipient_of_supplier_development_contributions: "true",

registered_name: "African Widgets Durban (Pty) Ltd",

registration_number: "12345678",

street_address: "1 Aloe Way",

telephone_number: "",

town: "Durban",

trading_name: "African Widgets - Durban",

vat_number: "1234567890",

vendor_code: "BEE003",

website: "www.african-widgets.com",

created_at: "03/10/2014 09:21:12",

updated_at: "03/10/2014 09:21:12"

}

Typical failed JSON response:

{

errors: [

"'trading_name' can't be blank"

"'vat_number' must be a valid vat number"

]

}

Typical XML request:

<?xml version="1.0"?>

<postal_address>PO Box 555</postal_address>

<exclude_from_procurement_calculations>false</exclude_from_procurement_calculations>

<enterprise_development_recipient>false</enterprise_development_recipient>

<custom_2>Johnnys client</custom_2>

</supplier>

Typical successful XML response:

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

<hash>

<black-person-with-disability>false</black-person-with-disability>

<cost-centre>Durban North</cost-centre>

<custom-1>African Custom 1</custom-1>

<custom-2>Johnnys client</custom-2>

<custom-3></custom-3>

<custom-4></custom-4>

<designated-group-supplier>false</designated-group-supplier>

<primary-email>test-person@example.com</primary-email>

<empowering-supplier>false</empowering-supplier>

<enterprise-development-recipient>false</enterprise-development-recipient>

<exclude-from-procurement-calculations>false</exclude-from-procurement-calculations>

<fax-number></fax-number>

<first-time-supplier>false</first-time-supplier>

<greater-than-five-percent-equity-by-black-individuals>false</greater-than-five-percent-equity-by-black-individuals>

<minimum-three-year-contract>false</minimum-three-year-contract>

<postal-address>PO Box 555</postal-address>

<property-service-provider>false</property-service-provider>

<recipient-of-supplier-development-contributions>false</recipient-of-supplier-development-contributions>

<registered-name>African Widgets Durban (Pty) Ltd</registered-name>

<registration-number>12345678</registration-number>

<street-address>1 Aloe Way</street-address>

<telephone-number></telephone-number>

<town>Durban</town>

<trading-name>African Widgets - Durban</trading-name>

<vat-number>1234567890</vat-number>

<vendor-code>BEE004</vendor-code>

<website>www.african-widgets.com</website>

<created-at>08/10/2014 10:42:03</created-at>

<updated-at>08/10/2014 11:10:31</updated-at>

</hash>

Typical failed XML response:

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

<hash>

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

<error>'vat_number' must be a valid vat number</error>

</errors>

</hash>

Delete Supplier

URL	/api/v1/suppliers/[vendor code]
Request Method	DELETE
Response (Success)	Code	204
	Body	N/A
Response (Failure)	Code	404
	Body	None
	Reason	Vendor Code not found

Typical successful response:

No content for a deleted resource

Typical failed JSON response:

{

errors: "Supplier not found"

}

Typical failed XML response:

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

<hash>

<errors>Supplier not found</errors>

</hash>

Supplier 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
Trading Name	trading_name	Widgets for Africa (Pty) Ltd
Vendor Code	vendor_code	GLO001
Registered Name	registered_name	Widgets Widgets Africa
Registration Number	registration_number	1245363829/012
VAT Number	vat_number	1234567890
Cost Centre	cost_centre	Cape Town
Website	website	www.widgets.co.za
Primary Email	primary_email	contact@widgets.co.za
Street Address	street_address	21 Gadget Street, WidgetVille, 8000
Postal Address	postal_address	21 Gadget Street, WidgetVille, 8000
Town	town	Cape Town
Telephone Number	telephone_number	021 876 4526
Fax Number	fax_number	021 876 4526
Exclude from procurement calculations?	exclude_from_procurement_calculations	"true", "false"
Enterprise Development recipient?	enterprise_development_recipient	"true", "false"
Black person living with a disability?	black_person_with_disability	"true", "false"
Property Service Provider?	property_service_provider	"true", "false"
Greater than 5% equity participation by black individuals?	greater_than_five_percent_ equity_by_black_individuals	"true", "false"
Empowering supplier?	empowering_supplier	"true", "false"
Has a minimum 3-year contract?	minimum_three_year_contract	"true", "false"
Recipient of Supplier Development Contributions	recipient_of_supplier_development_contributions	"true", "false"
First time supplier?	first_time_supplier	"true", "false"
Designated Group Supplier?	designated_group_supplier	"true", "false"
Custom 1	custom_1	Whatever you'd like to add to this supplier
Custom 2	custom_2	John
Custom 3	custom_3	Account Manager: John
Custom 4	custom_4	John's Team
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)

Supplier Write Fields

Description	Field Name	Data Type	Optional	Default	Possible Values	Notes
Trading Name	trading_name	String	No		Widgets for Africa (Pty) Ltd	Will generate error if trading name taken or invalid
Vendor Code	vendor_code	String	No		GLO001
Registered Name	registered_name	String	Yes	""	Widgets Widgets Africa
Registration Number	registration_number	String	Yes	""	1245363829/012
VAT Number	vat_number	String	Yes	""	1234567890
Cost Centre	cost_centre	String	Yes	""	Cape Town
Website	website	String	Yes	""	www.widgets.co.za
Primary Email	primary_email	String	Yes	""	contact@widgets.co.za
Street Address	street_address	String	Yes	""	21 Gadget Street, WidgetVille, 8000
Postal Address	postal_address	String	Yes	""	21 Gadget Street, WidgetVille, 8000
Town	town	String	Yes	""	Cape Town
Telephone Number	telephone_number	String	Yes	""	021 876 4526
Fax Number	fax_number	String	Yes	""	021 876 4526
Exclude from procurement calculations?	exclude_from_procurement_calculations	Boolean	Yes	"false"	"true", "false"
Enterprise Development recipient?	enterprise_development_recipient	Boolean	Yes	"false"	"true", "false"
Black person living with a disability?	black_person_with_disability	Boolean	Yes	"false"	"true", "false"
Property Service Provider?	property_service_provider	Boolean	Yes	"false"	"true", "false"
Greater than 5% equity participation by black individuals?	greater_than_five_percent_ equity_by_black_individuals	Boolean	Yes	"false"	"true", "false"
Empowering supplier?	empowering_supplier	Boolean	Yes	"false"	"true", "false"	May be overridden by empowering supplier status supplied by Beagle Database
Has a minimum 3-year contract?	minimum_three_year_contract	Boolean	Yes	"false"	"true", "false"
Recipient of Supplier Development Contributions	recipient_of_supplier_development_contributions	Boolean	Yes	"false"	"true", "false"
First time supplier?	first_time_supplier	Boolean	Yes	"false"	"true", "false"
Designated Group Supplier?	designated_group_supplier	Boolean	Yes	"false"	"true", "false"
Custom 1	custom_1	String	Yes	""	Whatever you'd like to add to this supplier
Custom 2	custom_2	String	Yes	""	John
Custom 3	custom_3	String	Yes	""	Account Manager: John
Custom 4	custom_4	String	Yes	""	John's Team

Articles in this section

Comments

Articles in this section

Related articles