Overview:

The API basicly consists of a REST API, where JSON content is transmitted in the body of the requests.

This API was built using the Swagger spec, therefore you can use Swagger's code generating capabilites to generate a basic client that can be used with this API.

For more info on how, please consult Swagger Codegen's project. Do note that when this API gets past it's current DRAFT state, we will make available the generated code from the current spec and it will be listed here.

Authentication

For simplicity reasons, the authentication will currently be done using HTTP Basic user/pass token that should be communicated with every request, through a HTTPS channel (the app is not available in plain text HTTP).

This token(s) can be renewed/invalidated by the client manually on the appropriate interface.

For all the libraries that only have generated code, the authentication hasn't been implemented. Because of that, we add here the Java code snippet that we currently use to take care of the authentication (which we put here so that it can be used as a 'pseudo code' example for other languages):

 public static void setCredentials(String username, String password) {
        ApiInvoker apiInvoker = ApiInvoker.getInstance();
        String userCredentials = username + ":" + password;
        String basicAuth = "Basic " + new String(Base64.encode(userCredentials.getBytes()));
        apiInvoker.addDefaultHeader("Authorization", basicAuth);
    }

Common Objects

In this section we describe some of the common objects/fields of objects that can be found throughout all of the API and are explained in detail here and in the subsequent reference documentation of each API method available.

External References

There are a number of what we call 'external references' throughout the library. These are fields that are usually prefixed with 'ext' and they refer to the Client's system.

ExternalId

All of the artifacts that are present here, usually require a unique id, that should exist on the client side, to be reported.

If such a unique ID does not exist on the client's side, it should be created, persisted and enforced its uniqueness per artifact by the client.

External dates

Some of the dates, mostly referring to creation timestamps, are requested by the library. If the creation or other such dates are not available, the time reliability of the resulting graphs cannot be assured.

Classifiers

Classifiers, as the name implies, are a way to classify each artifact, that can later be used to segment the data by its values. e.g. if you want to know how many clients came from a specific campaign, then you should add to each subscription and client artifact a campaign classifier (a key value pair) that will allow us later to distinguish them amongst the other clients/subscription.

Important notes

Please read the following notes before using the API:

Time fields

All of the time related fields, e.g. *Instant, extCreationInstant, etc. represent internal Joda Time objects and they are serialized/desererialized using jackson-datatype-joda.

Most of those time fields support different alternative formats of representation. In some of the examples we show two different ways to represent the *Instant types (either with a String or a Number). More detailed information about the different types used internally and accepted can be found below:

Field name(s)	Internal representation	Format(s) details
`extCreationInstant` `extLastModifiedInstant` `extActivationDate` `extEndDate` `dateOfChange`	Joda DateTime	a String type or `Number` UTC milliseconds since `1970-01-01T00:00:00Z`
`planInterval` `subsInterval`	Joda Period	a String type with the Period represented by the ISO8601 format (see link) or A `Number` of UTC milliseconds that the period will comprise Note, this version's usage is discouraged, it's preferable to use the String type

Headers

For all of the API's methods, the usage of the Header: Content-type: application/json is mandatory. Without that Header, the server will not recognise the request's body as JSON.

Refunds

Allows you to list and manage all of the refunds for the authenticated account

HTTPS Method:

POST /api/refunds/-subsExtId-

In this method, one can create a refund for an existing Subscription

Parameters:

Description:

The refund representation in JSON of the refund to be created

Required:

true

Type:

RefundBean JSON Object

Example:

{
  "extId": null,
  "amount": 5000,
  "dateOfChange": "2015-05-07T11:57:09.657+0000"
}

Parameter's descriptions:

Field	Description
amount	in cents, *required
dateOfChange	the UTC timestamp when the refund was done *required

Responses:

Code:: 200
Type:: RefundEvent JSON Object
Returns:: OK: The refund that was just created

Code:: 400
Type:: APIError JSON Object
Returns:: Error: If an error occurs. The reason/cause(s) should be stated in the response

Clients

Allows you to list and manage all of the clients for the authenticated account

HTTPS Method:

POST /api/clients

This method creates a new Client

Parameters:

Description:

The client representation in JSON of the client to be created

Required:

true

Type:

Client JSON Object

Example:

{
  "name": "John",
  "email": "jdoe@asd",
  "description": null,
  "classifiers": {
    "utm_name": "April2ndCampaign",
    "utm_source": "facebook"
  },
  "externalId": {
    "externalId": "22faa873-33ae-4d51-b11c-b485a77fb3b0"
  },
  "extCreationInstant": 1426536639795,
  "extLastModifiedInstant": null
}

Parameter's descriptions:

Field	Description
name	optional
email	optional
description	optional
classifiers	optional List of key value pairs to classify this object.
externalId	must be given for future reference *required
extCreationInstant	Timestamp in UTC of the date and time of when the creation of this client took place in the client *optional
extLastModifiedInstant	UTC timestamp of when it was last modified (client's reference) optional

Responses:

Code:: 200
Type:: Client JSON Object
Returns:: OK: The client that was just created

Code:: 400
Type:: APIError JSON Object
Returns:: Error: If an error occurs. The reason/cause(s) should be stated in the response

HTTPS Method:

POST /api/clients/jsonArray

It creates multiple new Clients from a JSON array

Parameters:

Description:

The client representation in JSON of the client to be created

Required:

true

Type:

Array[Client] JSON Object

Example:

[{
     "name": "John",
     "email": "jdoe@asd",
     "description": null,
     "classifiers": {
       "utm_name": "April2ndCampaign",
       "utm_source": "facebook"
     },
     "externalId": {
       "externalId": "client#151512"
     },
     "extCreationInstant": 1426536639795,
     "extLastModifiedInstant": null
   },{
    "name": "Alice",
     "email": "asinjer@nwhr.com",
     "description": null,
     "externalId": {
       "externalId": "client#113010"
     },
     "extCreationInstant": 1426536639795,
     "extLastModifiedInstant": 1426536639995
   }]

Parameter's descriptions:

Field	Description
name	optional
email	optional
description	optional
classifiers	optional List of key value pairs to classify this object.
externalId	must be given for future reference *required
extCreationInstant	Timestamp in UTC of the date and time of when the creation of this client took place in the client *optional
extLastModifiedInstant	UTC timestamp of when it was last modified (client's reference) optional

Responses:

Code:: 200
Type:: List JSON Object
Returns:: OK: The list of clients and their IDs/ExtIDs that was just created

Code:: 400
Type:: APIError JSON Object
Returns:: Error: If an error occurs. The reason/cause(s) should be stated in the response

Plans

Allows you to list and manage all of the plans for the authenticated account

HTTPS Method:

POST /api/plans

This method creates a new Plan

Parameters:

Description:

The plan representation in JSON of the plan to be created

Required:

true

Type:

Plan JSON Object

Example:

{
   "amount": 10000,
   "currency": "BRL",
   "metaDescription": "Premium 100R plan",
   "planInterval": "P1M",
   "state": "ACTIVE",
   "name": "Premium",
   "classifiers": {
     "type": "special pack"
   },
   "externalId": {
     "externalId": "plan#12315"
   },
   "extCreationInstant": 1426536639795,
   "extLastModifiedInstant": "2015-05-04T07:42:43.000+0000"
 }

Parameter's descriptions:

Field	Description
amount	amount in cents, of the default value. e.g. 10USD is represented as 10,00USD therefore this field should have the value of 1000 * required -note- this parameter can be changed individually by each subscription
currency	the ISO 4217 code of the currency, if it's not a valid one, an error will be sent in response - required -note- list of valid ISO 4217 codes can be found here: http://en.wikipedia.org/wiki/ISO_4217
metaDescription	a simple description of this plan * optional
planInterval	The standard ISO8601 format - PyYmMwWdDThHmMsS. Milliseconds are not present. Note that the ISO8601 standard actually indicates weeks should not be shown if any other field is present and vice versa.- the interval of time between the customer being charged
state	either Active or Inactive * optional - if not present, active is assumed an inactive plan shouldn't have any new subscriptions associated with it, if the client reports one, an error will be thrown. * in the future All inactive plans will appear distinctly on the clients' dashboards.
name	a simple name for this plan e.g. 'Basic' * required
classifiers	optional List of key value pairs to classify this object.
externalId	required - the unique and immutable id used by your system, and that can be used to refer in the future to this newly created plan.
extCreationInstant	Timestamp in UTC of the date of when the creation of this plan took place in the client *optional
extLastModifiedInstant	UTC timestamp of when it was last modified (client's reference) optional

Responses:

Code:: 200
Type:: Plan JSON Object
Returns:: OK: The plan that was just created

Code:: 400
Type:: APIError JSON Object
Returns:: Error: If an error occurs. The reason/cause(s) should be stated in the response

HTTPS Method:

POST /api/plans/jsonArray

This method creates multiple new Plans in a batch

Parameters:

Description:

The plan representation in JSON of the plan to be created

Required:

true

Type:

Plan JSON Object

Example:

[ {
         "amount": 10000,
         "currency": "BRL",
         "metaDescription": "Premium 100R plan",
         "planInterval": "P1M",
         "state": "ACTIVE",
         "name": "Premium",
         "classifiers": {
           "type": "special pack"
         },
         "externalId": {
           "externalId": "plan#12315"
         },
         "extCreationInstant": 1426536639795,
         "extLastModifiedInstant": "2015-05-04T07:42:43.000+0000"
       },
       {
         "amount": 5900,
         "currency": "BRL",
         "metaDescription": "Pro 59R plan",
         "planInterval": "P1M",
         "state": "ACTIVE",
         "name": "Pro",
         "classifiers": {
           "type": "regular"
         },
         "externalId": {
           "externalId": "plan#2"
         },
         "extCreationInstant": 1426536689795,
         "extLastModifiedInstant": null
       }]

Parameter's descriptions:

Field	Description
amount	amount in cents, of the default value. e.g. 10USD is represented as 10,00USD therefore this field should have the value of 1000 * required -note- this parameter can be changed individually by each subscription
currency	the ISO 4217 code of the currency, if it's not a valid one, an error will be sent in response - required -note- list of valid ISO 4217 codes can be found here: http://en.wikipedia.org/wiki/ISO_4217
metaDescription	a simple description of this plan * optional
planInterval	Format: number DAY\|WEEK\|MONTH\|YEAR - the interval of time between the customer being charged
state	either Active or Inactive * optional - if not present, active is assumed an inactive plan shouldn't have any new subscriptions associated with it, if the client reports one, an error will be thrown. * in the future All inactive plans will appear distinctly on the clients' dashboards.
name	a simple name for this plan e.g. 'Basic' * required
classifiers	optional List of key value pairs to classify this object.
externalId	required - the unique and immutable id used by your system, and that can be used to refer in the future to this newly created plan.
extCreationInstant	Timestamp in UTC of the date of when the creation of this plan took place in the client *optional
extLastModifiedInstant	UTC timestamp of when it was last modified (client's reference) optional

Responses:

Code:: 200
Type:: Plan JSON Object
Returns:: OK: The plan that was just created

Code:: 400
Type:: APIError JSON Object
Returns:: Error: If an error occurs. The reason/cause(s) should be stated in the response

Subscriptions

Allows you to manage all of the subscriptions for the authenticated account

HTTPS Method:

PUT /api/subscriptions/-extId-

This method changes the status of an already created subscription

Parameters:

Description:

The subscription status representation in JSON of the new status

Required:

true

Type:

SubscriptionStatusChange JSON Object

Example:

{
 "newStatus": "CANCELLED",
 "dateOfChange": "2015-05-07T13:47:31.213+0000",
 "force": false
 }

Parameter's descriptions:

Field	Description
newStatus	the new status - *required
dateOfChange	the UTC timestamp when the refund was done *required
force	boolean - it may force the transition to take place *optional

Responses:

Code:: 200
Type:: Subscription JSON Object
Returns:: OK: The subscription's status changed

Code:: 400
Type:: APIError JSON Object
Returns:: Error: If an error occurs. The reason/cause(s) should be stated in the response

HTTPS Method:

POST /api/subscriptions

This method creates a new Subscription

Parameters:

Description:

The subscription representation in JSON of the subscription to be created

Required:

true

Type:

Subscription JSON Object

Example:

{
  "extActivationDate": "2015-05-07T13:32:30.978+0000",
  "extEndDate": null,
  "name": "Simple subscription",
  "subsInterval": null,
  "amount": null,
  "canceledAt": null,
  "status": "ACTIVE",
  "clientId": "0190a830-2bd5-4381-af26-d12308b82aae",
  "planId": "0c17c408-3013-4967-b453-3d84387dcc4f",
  "classifiers": {
    "campaign": "socialfb"
  },
  "externalId": {
    "externalId": "7c76ba2d-c808-471f-a342-984293a3c2ff"
  },
  "extCreationInstant": "2015-05-07T13:31:30.980+0000",
  "extLastModifiedInstant": null
}

Parameter's descriptions:

Field	Description
extActivationDate	your activation date optional/required depends on state
extEndDate	the UTC timestamp when the subscription ended optional/required depends on state
name	optional name for the subscription (it is not needed and it currently does not show - but it might show in the future) *optional
subsInterval	an optional period that overrides the default period of the given plan, if not given, the plan's default period will be used - The standard ISO8601 format - PyYmMwWdDThHmMsS. Milliseconds are not present. Note that the ISO8601 standard actually indicates weeks should not be shown if any other field is present and vice versa. *optional
amount	overrides the amount defined in the plan, it's optional, if not present, the amount in the plan is assumed *optional
canceledAt	the UTC timestamp when (if) the Subscription was canceled
status	*required one of [ACTIVE - if used, the activationDate must be given ; EXPIRED - if the subscription was once active and now has ended due to regular expiration reason - e.g. a subscription was renewed each month, but expired after a year - required the extEndDate FAILED - if the subscription was once active and now has ended due to a payment failure - e.g. credit card expired - required the extEndDate CANCELLED - if the subscription was once active and now has ended due to cancellation from the user - required the extEndDate INACTIVE - if the subscription was once active and has been inactive and the reasons don't fit in the other states
clientId	the client id (using your reference) *required
planId	the plan id (using your id) *required
classifiers	optional List of key value pairs to classify this object.
externalId	required - the unique and immutable id used by your system, and that can be used to refer in the future to this newly created subscription.
extCreationInstant	Timestamp in UTC of the date and time of when the creation of this subscription took place in the client *optional
extLastModifiedInstant	UTC timestamp of when it was last modified (client's reference) optional

Responses:

Code:: 200
Type:: Subscription JSON Object
Returns:: OK: The subscription that was just created

Code:: 400
Type:: APIError JSON Object
Returns:: Error: If an error occurs. The reason/cause(s) should be stated in the response