====== API Documentation: Getting Started ======
===== Welcome =====

The SubscriptionBridge XML APIs were designed to help developers integrate third-party applications with SubscriptionBridge (SB), a [[http://www.earlyimpact.com/subscriptionbridge/|subscription management system]] developed by Early Impact, Inc. 

This guide will provide a knowledgeable programmer with all the information needed to integrate a system with SB. 

The XML APIs will work with any programming language or platform that is capable of sending and receiving XML documents over the HTTPS POST protocol.

If you're a "hands on" type of person feel free to skip on down to the resource section and grab some sample code.


===== Overview ===== 

The SubscriptionBridge APIs are a **set of XML-based web services** that allow third-party developers to integrate seamlessly with the SB system. APIs provide a vehicle for secure, bidirectional communication. Simply put… just about any application with internet access can be modified to work with the XML-based APIs. You can now create powerful, time-saving solutions that will streamline your business' recurring billing operations.

The SubscriptionBridge XML APIs are designed for...

  * [[developer_guide:call_reference:subscriptionrequest|Creating Subscriptions]]
  * [[merchant_guide:notifications_list_callbackurl|Sending/Receiving Notifications]]
  * [[developer_guide:call_reference:eventrequest|Sending/Receiving Events]]
  * [[developer_guide:call_reference:api_management_limitations|Managing Existing Subscriptions]]

===== Hit the Ground Running with Sample Code =====

[[:developer_guide/developer_guide/sample_code|{{:csharpdotnet.png?140|}}]]  [[:developer_guide/developer_guide/sample_code|{{:vbdotnet.png?120|}}]] 
[[:developer_guide/developer_guide/sample_code|{{:javascript_logo.png?100|}}]]  [[:developer_guide/developer_guide/sample_code|{{:php_logo.jpg?100|}}]] 
[[:developer_guide/developer_guide/sample_code|{{:asp.png?90|}}]] 

===== Skill Requirements ===== 

The power of the SubscriptionBridge API is in the ability to have an external application communicate bidirectionally, without human interaction. Skills required:

  * a basic understanding of XML
  * ability to create (or have access to) an application that can send/receive XML communication \\ Most programming languages include methods to send XML over HTTPS, and there is ample information available on the Internet. 

In the following pages we will cover everything you need to know about the APIs. We will discuss the use of the APIs and the formation of the XML messages. You will also find technical information and sample code in this section.

===== Security Standards =====

To ensure that all personal information is handled securely:

  * We enforce Secure Socket Layering (SSL) on the SubscriptionBridge API. All requests must be send over the HTTPS protocol.
  * We ask that you strictly adhere to the [[https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml|PCI Data Security Standards]]. Since your application is "passing" information to SubscriptionBridge, the application (whatever it may be) is considered a "payment application" and must comply with the [[https://www.pcisecuritystandards.org/pdfs/pci_pa_dss.pdf|Payment Application Data Security Standard]].

===== Using the APIs ===== 

==== Your First XML API Call ====

Get started in a snap with our sample code. Contact us for production ready examples in several languages.


The following sections will provide you will all of the knowledge needed to send your first XML Call.  

=== Creating XML ===

All SB XML documents have the same basic elements.  Here is an example of the basic XML structure for all requests/responses.  In the example below "ActivationResponse" is the response container.  "Ack" and "Timestamp" are the response elements.  

<code>
<?xml version="1.0" encoding="utf-8"?>
    <ActivationResponse>	
        <Ack>string</Ack>
	<Timestamp>timestamp</Timestamp>					
    </ActivationResponse>
</code>

=== Standard Request Elements ===

All XML calls will have a container element, such as "<ActivationRequest>" or "<ActivationResponse>".

  * [[:developer_guide:call_reference:start|Call Reference]]

There are two elements that are required for every request transaction, in addition to the container element.

  * [[:developer_guide:field_reference:start#Username|Username]] \\ This is the API username, not your Merchant Center login.
  * [[:developer_guide:field_reference:start#Token|Token]] \\ The token is critical for authentication with the API.  Click the link above for complete instructions.

<note>All required elements must be present in your XML.  The elements must also be sent in the correct order. If the XML request is not formed correctly the API will issue a [[:developer_guide:developer_guide#http-status-code|HTTP Status Code]] of 400 (Bad Request) and send an [[:developer_guide:error-handling-guide|ErrorResponse]] document with additional details. </note>

Example XML:

<code>
<?xml version="1.0" encoding="utf-8"?>
    <Method>	
        <Username>string</Username>
        <Token>string</Token>					
    </Method>
</code>

=== Standard Response Elements ===

The following elements will always be returned with a response, in addition to the container element.

  * [[:developer_guide:field_reference:start#Ack|Ack]]
  * [[:developer_guide:field_reference:start#Timestamp|Timestamp]]

<note>If the XML request is not formed correctly the API will issue a [[:developer_guide:developer_guide#http-status-code|HTTP Status Code]] of 400 (Bad Request) and send an [[:developer_guide:error-handling-guide|ErrorResponse]] document with additional details. In such a case the response elements may be different than the ones described in this section.  For more information read over the [[:developer_guide:error-handling-guide|ErrorResponse]] section.</note>

Example XML:

<code>
<?xml version="1.0" encoding="utf-8"?>
    <Method>	
        <Ack>string</Ack>
        <Timestamp>timestamp</Timestamp>					
    </Method>
</code>

=== Executing the Call ===

== EndPoints ==

To make an API Call you need to find the EndPoint (or address) for the service.  From the [[:developer_guide:call_reference:start|API Call Reference]], click on the method name to find its EndPoint.  A list of all the available EndPoints is listed below.  You will need to replace the text in between the [] with your own.

Notification API:
<code>Endpoint = https://www.subscriptionbridge.com/Notifications/Service1.svc/[method_name]</code>

Subscription API:
<code>Endpoint = https://www.subscriptionbridge.com/Subscriptions/Service2.svc/[method_name]</code>

Management API:
<code>Endpoint = https://www.subscriptionbridge.com/Management/Service3.svc/[method_name]</code>

The following is the EndPoint for an ActivationRequest:

https://www.subscriptionbridge.com/Subscriptions/Service2.svc/ActivationRequest

<note>The EndPoint must be HTTPS.</note>

== Call Guidelines ==

To make an successful call you must follow these rules:

  * [[:developer_guide:call_reference:ActivationRequest|ActivationRequest]] must be completed successfully before any other call can be made
  * **All elements must be in the correct order**
  * Username and Token are always the first elements in the request
  * Send the request over HTTPS
  * You must specify the correct EndPoint. If a call fails with a 500 HTTP Status Code this may be why
  * XML Elements are case sensitive
  * The "Content-Type" must be specified as "text/xml"

== Sending API Requests with HTTPS POST ==

Almost every programming language has its own method for sending XML via HTTPS POST.  There are a number of resources on the internet that will assist you with the requirement.  You may also view our [[:developer_guide:developer_guide:sample_code|Sample Code]] for additional help.

=== Handling the Response ===

The following section outlines the procedure for dealing with SB responses.

After you send your XML Call the first thing you should do is check the response [[:developer_guide:developer_guide#http-status-code|HTTP Status Code]].  View the following section for a chart of possible HTTP Status Codes.

If you get a 200 [[:developer_guide:developer_guide#http-status-code|HTTP Status Code]] you can capture the response XML and check the [[:developer_guide:field_reference:start#Ack|Ack]] element for the results.  The [[:developer_guide:field_reference:start#Ack|Ack]] element is the acknowledgment of your request.  The value will be "Success", "Warning", or "Failure". If you the [[:developer_guide:field_reference:start#Ack|Ack]] is "Success" you can proceed to parse the XML to complete the task.

If you get a 400 or 500 [[:developer_guide:developer_guide#http-status-code|HTTP Status Code]] you should check for an [[:developer_guide:error-handling-guide|ErrorResponse]] with additional details.

==== HTTP Status Code ====

The table below lists the HTTP Status Codes used by the SB system. HTTP Status Codes are used when processing responses.

^ Code ^ Name ^ Meaning ^
| 200 | OK | Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request the response will contain an entity describing or containing the result of the action.  |
| 401 | Unauthorized | The username and/or password were incorrect.  The session could not be authenticated.  |
| 500 | Internal Server Error | A generic error message, given when no more specific message is suitable.  |

==== Error Codes ====

Use the table below to lookup error codes returned by the SB system.

^ Code ^ Type ^ Meaning ^
| 10000 | Authorization | Authentication/Authorization Failed  |
| 10002 | Authorization | Username/Password is incorrect  |
| | | |
| 20000 | Internal Errors | General Failure  |
| | | |
| 90002 | Notification API | Malformed Value  |
| 90004 | Notification API | Unspecified Value  |

==== Troubleshooting ====

  * **HTTP/1.1 411 Length Required** \\ The XML body of your request is not being sent to the API. In other words, your request is empty. The API requires the message to have a content length.  To correct the error make sure you are sending valid XML.
  * **HTTP/1.1 404 Not Found** \\ You did not type the Endpoint address correctly. Please make sure you add the trailing method name (e.g. /ActivationRequest).
  * **HTTP/1.1 502** \\ You must POST your XML with HTTPS, not HTTP.

===== Resources (Sample Code, Links, Call References) =====

About the API:

  * [[:developer_guide:call_reference:start|API Call Reference]]
  * [[:developer_guide:field_reference:start|API Field Reference]]
  * [[:developer_guide:developer_guide:sample_code|Sample Code]]

Recommendations for common integration projects:

  * [[:developer_guide:developer_guide:recommended|Recommended Specifications for Shopping Cart Integration]]
  * [[:developer_guide:developer_guide:terms_widget|Using the Subscription Terms "Widget"]]