Welcome‎ > ‎

Version 3

Introduction

Welcome to the Group Commerce API.  Here you will find API documentation and snippets related to Version 3 of the Group Commerce API.  Version 3 is a minor upgrade from Version 2. It's recommended that once out of beta all API users upgrade to version 3 as soon as they can.  The key improvements from v2 are support for localization, multiple currency, and data restructuring.

The Group Commerce API consists of the following parts: a Publisher API and a Merchant API.  The Syndication API for v3 has been deprecated and we will be releasing a new process for deal site aggregators to populate their site.  The Publisher API is considerably more powerful, and can be used to perform complex tasks such as automating promotional emails, creating offer widgets, powering a mobile web application, or creating a fully-functional daily deal site that is hosted entirely within your own environment. 

The Merchant API is an endpoint used by merchants to check their offers, mark vouchers as redeemed, and perform data collection on their customers.

Hopefully you will find other uses for the APIs that we haven't even thought of!  For questions, concerns, or feedback about the Group Commerce API please contact us at: apisupport@groupcommerce.com.

To try out some of the code snippets in this documentation you may need to use the following test keys:

ApiKey = "eeb6b959-b854-4ad1-b563-e801c83cf81d"
SecretKey = "826c553a-6dac-4b34-889f-d9a70d38f7ee"
 
Want to become an affiliate of a Group Commerce pub?  Fill out an affiliate request form. We do not provide API keys for affiliates. Once your request has been accepted by the publisher(s) and they entered your contract in our system, you will received an access to our affiliate portal with a link to the publisher's XML feed.
 
Need your own API key?  Fill out an api request form and someone will get back to you soon!
 
Publisher and Merchant APIs

The Publisher and Merchant APIs provide functionality to communicate with the Group Commerce core platform.

The Publisher API allows application developers to create a purchase experience similar to one on a Group Commerce hosted site. Additionally, this api can be used to develop facebook pages, mobile sites, integrate widgets into existing sites or develop line of business applications such as a content management tool for generating promotional emails.

The Merchant API allows application developers to do voucher management for merchants - redeeming and unredeeming vouchers.

For both the Publisher and Merchant APIs, there are two types of modes depending on the level of sensitivity for data: ApiKey Mode and OAuth Mode. These are explained in more detail below.

ApiKey Mode

Read access methods are basic data retrieval methods.  A method name containing "broadcast" indicates that the method is a read access api key method.  For example: Get Broadcast Offers or Get Broadcast Segment List.  ApiKeys used for oAuth are not supported in this mode.  If using an oAuth key, you must sign the request using oAuth signing.  Otherwise a simple querystring value will suffice.  These methods using ApiKey mode will also support jsonp. 

To access the ApiKey Mode methods, you will need to acquire an api key by sending a request to apisupport@groupcommerce.com. 

Sample Request:

GET http://api.groupcommerce.com/api/v3/publisher/broadcast/segments?apiKey=eeb6b959-b854-4ad1-b563-e801c83cf81d&format=xml


oAuthMode

The methods classified as oAuth allow a publisher to create a new application that has the same functionality as the Group Commerce hosted website.  Publishers are able to see offers, post customer service requests, invite and refer a friend, purchase and gift an offer, see past orders, and retrieve consumer voucher information.  Because of the sensitive nature of these methods, additional security is required. The Write Access methods are secured with oAuth authentication using a public and private key. You can acquire api keys by sending a request to apisupport@groupcommerce.com

A great resource for understanding oAuth can be found here.  There are several oauth libraries that can be used to help when connecting to the Write Access methods.  Each of the ones we evaluated had their quirks.  The library with the fewest number of problems in our experience in the .net stack is oauth dot net.

Sample Request:
GET http://api.groupcommerce.com/api/v3/publisher/segments

Authorization: OAuth oauth_signature="mqslYWSWcqmslNAVecl92RXPtkA%3d", oauth_nonce="5576873", oauth_timestamp="1319574320", oauth_consumer_key="eeb6b959-b854-4ad1-b563-e801c83cf81d", oauth_signature_method="HMAC-SHA1", oauth_version="1.0"


Group Commerce is in the process of releasing an SDK for both php and .net. This SDK will simplify access to the Publisher API by wrapping all urls and methods and providing strongly typed return objects.

Response Formats

JSON and XML formats are supported by the API. JSON is the default format and will be used unless the Request.ContentType is set to "application/xml" or a format=xml querystring parameter is passed.  Note: after 3/5/2013, the request's Accept header may also be used to determine the response format.  Set the header to "application/xml" to receive an XML response.

Localization

The "Accept-Language" header is what is used to drive the desired language.  Contrary to web standards, the GroupCommerce api will only support the selection of one language.  Valid examples are: "en-US", "fr", "bg-BG".

Dates & Times

Dates in the XML returned by the API use the ISO 8601 format.  Although the Date object has no support in json, there are some workarounds.  Group Commerce uses the format "\/Date(<ticks>)\/".  More information can be found here. Unless otherwise stated, all datetime values are  provided in UTC.

Currency

Money in the API is provided two decimal places. Pricing information includes a currency field using the ISO 4217 format. The decimal place is indicated by a period('.') regardless of currency or culture. 

Example:
{
    Currency: "USD",
    Price: 5.00
}

ċ
GroupCommerce.SDK.rar
(211k)
Unknown user,
Mar 16, 2012, 10:12 AM
Comments