Red Cross API Phase 3 Scope
1
Red Cross API Phase 3 Scope
Prepared by: Springload - 25 October 2012
RED CROSS API PHASE 3 SCOPE
POST orders updates
Example updated POST order
getCorporateContracts
Data requirements
Example GET data
getLocations
POST Order updates to allow donations
www.springload.co.nz • 04 801 8205
1
3
3
6
6
6
8
11
Red Cross API Phase 3 Scope
2
The following are our requirements for phase 3 of API development in priority
order.

Updated POST order method to include capturing more fields

Method to GET corporate contract entities from XRM

Method to GET all the different types of RedCross locations

Updated POST method to add ability to send through a “Donation” financial
transaction separately to a customer cart.
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
3
POST orders updates
We need the method “PostCart” updated to accept the following fields:
dob: Date (yyyy-mm-dd) (Optional) // A course attendee’s date of birth
nzqa_number : String (Optional) // A course attendee’s NZQA number
gateway_transaction_id: String // The transaction ID from the payment gateway
gateway_return_receipt_number: String // The return receipt number for the transaction
transaction_time: DateTime (yyyy-mm-dd hh:mm:ss) // The time of the transaction
payment_type: String // Whether it’s a CC payment or an invoice payment
corporate_entity: String (optional) // XRM id to identify the corporate who has boo ked this
course
corporate_workgroup: String (optional) // XRM id to identify the corporate workgroup this
corporate customer belongs to
mobile_number: String – (optional) // The mobile number for the bill to person
mailing_list: bool // Whether or not to sign the customer up to mailing list
donation: array of donation information if the customer chooses to make a donation when
booking a first aid course or purchasing a product:
Donation: {
Value: Float, // The amount of money donated
Campaign: String, // A string identifying the donation campaign donated t
}
Example updated POST order
New fields are bolded.
[
{
"purchase_order_number": "678910",
"order_total": 1500.5,
"shipping_cost": 0.0,
“gateway_transaction_id”: “0135AB840”,
“gateway_return_receipt_number”: “1281305”,
“transaction_time: “2012-12-01 17:00:16”,
“payment_type”: “cc”,
“corporate_entity”: “ 2539418e-7b03-e211-9fab-00155d040a2b”,
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
4
“corporate_workgroup”: “2139418e-7b03-e211-9fab-00155d040a2b”,
“mailing_list”: false,
"bill_to": {
"first_name": "Slurpy",
"last_name": "Jones",
"street1": "Building 14",
"street2": "181 Queen St",
"suburb": "Auckland CBD",
"city": "Auckland",
"country": "New Zealand",
"postal_code": "1000",
"contact_number": "888 9999",
“mobile_number”: “021 025 27104”,
"email_address": "slurpy@magnetism.co.nz",
"reference": "XXYY"
},
"deliver_to": null,
"products": null,
“donation”: [
value: 29.00,
campaign: “Where the need is greatest”
]
"first_aid_courses": [
{
"offering_xrm_id": "f1aaf7ec-831c-e111-a661-00155d006501",
"course_purchase_amount": 195.0,
"attendees": [
{
"first_name": "Roshan",
"last_name": "Mehta",
"contact_number": "021 123 4567",
"email_address": roshan@magnetism.co.nz,
“dob”: “1981-08-19”,
“nzqa_number”: “01235356”
}]
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
5
}]
}
]
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
6
getCorporateContracts
A new method to get available corporate contracts from XRM and their associated course and
product pricing.
Data requirements
For each corporate contract entity we require the following fields:
xrm_guid:
String – A unique GUID for matching a corporate entity in XRM
company_title:
String – A web friendly title for the company
company_intro:
String – Introductory text to show on the booking page for the company
company_workgroups: Array of workgroups for the organisation that the corporate customer
can select when purchasing a course of product:
xrm_guid:
String – A unique GUID for matching the workgroup in XRM
workgroup_title:
String – A web friendly title for the workgroup
course_pricings: Array of courses and the prices for the courses for this company
course_xrm_guid:
String – A unique GUID for matching the course in XRM
course_cost:
Float – The discounted price for the company for the course
product_pricings: Array of products and the prices for the products for th is company
product_xrm_guid:
String – A unique GUID for matching the product in XRM
product_cost:
Float – The discounted price for the company for the product
Example GET data
[
{
xrm_guid: "6e0f9d88-c805-e211-b176-00155d040a2b",
company_title: “Department of Labour”,
company_intro: “New Zealand Red Cross is please to welcome the Department
of Labour as a First Aid Client”,
company_workgroups: [
{
workgroup_xrm_guid: “3a39418e-7b03-e211-9fab-00155d040a2b",
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
7
workgroup_title: “Immigration group”
},
{
workgroup_xrm_guid: “3a39418e-7b18-e211-9fab-00155d040a2b”,
workgroup_title: “Executive group”
}
],
course_pricings:[
{
course_xrm_guid: “1a39418e-7b18-e211-9fab-00155d040a2b”,
course_cost: 100
},
{
course_xrm_guid: “1’p39418e-7b18-e211-9fab-00155d040a2b”,
course_cost: 299
}
],
product_pricings:[
{
product_xrm_guid: “9939418e-7b18-e211-9fab-00155d040a2b”,
product_cost: 80
},
{
product_xrm_guid : “10p39418e-7b18-e211-9fab-00155d040a2b”,
product_cost: 25
}
]
}
]
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
8
getLocations
This method will retrieve all locations of a particular type from XRM that can be published
online:
@param – String – The type of location (i.e. service centre, branches, groups and area councils
etc) – or empty param for ALL locations
Available types include: “national”, “service centre”, “branch”, “group”, “area council”
Not every type will have all the fields below available. Where the fields aren’t available please
just return null.
{
xrm_id: "dfd96e1b-3e24-e011-a3d0-00155d006501",
name: "Wellington Red Cross store",
type: “Branch”,
toll_free_phone: “0800 123 456”,
contact_email: “wellington@redcross.org.nz”,
contact_number: “04 471 4331”,
contact_person: [
name: “Marie Johnston”,
position: “Chair”
// If this is one field in XRM then just provide the
// one field
]
meeting_address: [
meeting_address1: “17 Waitohu Road”,
meeting_address2: “York Bay”,
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
9
meeting_city: “Lower Hutt”,
etc.. any other meeting address fields available
],
meeting_date: “5:30pm, 2nd Tuesday each month”,
mailing_address: [
mailing_address1: “17 Waitohu Road”,
etc.. any other mailing address fields available
],
address1: "26 Glover Street",
address2: "Ngauranga",
suburb: "",
city: "Wellington",
region: "",
postcode: "",
latitude: 0,
longitude: 0,
sunday_hours: "",
monday_hours: "",
tuesday_hours: "",
wednesday_hours: "",
thursday_hours: "",
friday_hours: "",
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
10
saturday_hours: "",
parking: ""
}
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
11
POST Order updates to allow donations
This is an update to the POST orders method to allow sending donation information separately
from CARTS to XRM in the form of a “financial transaction”. For each successfully completed
donation we will send through as part of the POST. Note that this is in addition to being able to
send donation information as part of the customer CART, when a customer has also purchased a
product or booked a first aid course.
Donations: Array of donations made on the site [
Donation: {
Value: Float, // The amount of money donated
Gateway_transaction_id: String, // The payment gateway id for this transaction,
gateway_return_receipt_number: String, // The return receipt number for the
transaction
transaction_time: DateTime, (yyyy-mm-dd hh:mm:ss) // The time of the
transaction
Email: String, // The customer’s email address
Mailing_list: Bool, //True if the user agreed to mailing list signup, false for not
Campaign: String, // A string identifying the donation campaign donated t o,
},
Donation: {
Etc…
}
]
www.springload.co.nz • 04 801 8205
Red Cross API Phase 3 Scope
12
www.springload.co.nz • 04 801 8205