Below you will find the documentation needed to integrate your agency's registration systems with the SBRS. With this integration, we hope to bring a seemless registration system to businesses and citizens throughout Oklahoma.
The API is designed to be utilized by any system capable of reading and parsing XML formatted responses. Each agency is required to contact the Dept of Commerce to request proper access authorization. Once you receive your credentials, the following API, and code example, will help you get started with the SBRS API.
Used by third-party agencies to validate a user. This method is invoked when a user comes from the SBRS and the access_token is in the URL query string. This ensures both the third-party agency and the user that the request is a valid request from SBRS and not an outside, unauthorized source. The Access Token is a randomly generated token that is unique to the user and the license/registration/premit they are required to have with the third-party agency. A separate Auth Token is required to continue connection with SBRS.
The Access Token is set to expire within 90 seconds from it's initial generation.
This information can be used to populate data fields within their own systems. The data is returned in an open XML format.
http://domain.com/validate_user
<?xml version='1.0'?> <response> <from>SBRS</from> <status>true</status> <user_id>1</user_id> <business_id>1</business_id> </response>
Used by third-party agencies to validate a connection with SBRS. Each time a request is made to the SBRS, an Auth Token must be supplied. This Auth Token is a unique, random token set to expire every 90 seconds. The third-party must request a token before any user information can be retrieved. Each request must include the auth token and access token. If the user sits idles for too long, or the third-party agency app fails to validate the token within 90 seconds, a failure message will be returned.
The Auth Token is set to expire within 90 seconds from it's initial generation.
This information can be used to populate data fields within their own systems. The data is returned in an open XML format.
http://domain.com/request_token
<?xml version='1.0'?> <response> <from>SBRS</from> <stat>ok</stat> <method>Commerce.SBRS.auth_token</method> <agency_id>1</agency_id> <auth_token>299b2d62e9ad20f837350467b5b5bc52f830b555</auth_token> </response>
Used by third-party agencies to retrieve information about a registered SBRS user. This is the basic information about the user and the business they are registering.
This information can be used to populate data fields within their own systems. The data is returned in an open XML format.
http://domain.com/request_user
<?xml version='1.0'?> <response> <from>SBRS</from> <stat>ok</stat> <method>Commerce.SBRS.user_info</method> <id>1</id> <email>jane.doe@example.com</email> <name>Jane Doe</name> <business_id>1</business_id> <business_name>Jane Doe's Karate Dojo</business_name> <business_address>12345 S. Some St.</business_address> <business_address2></business_address2> <business_city>Tulsa</business_city> <business_state>OK</business_state> <business_zip>74106</business_zip> <business_phone>9185551212</business_phone> <business_type>Consumer Leasing/Rent-to-Own</business_type> </response>
Used by third-party agencies to retrieve information about a registered SBRS user's answers given to questions regarding business type. The matrix lists all questions returned to the user upon registration within SBRS. It also includes the answers they supplied.
This information can be used to populate data fields within their own systems. The data is returned in an open XML format.
http://domain.com/request_matrix
<?xml version='1.0'?> <response> <from>SBRS</from> <stat>ok</stat> <method>Commerce.SBRS.user_matrix</method> <question_answer id="22759"> <question id="1158">Select the legal structure of your business.</question> <answer id="369">Domestic Limited Liability Company</answer> </question_answer> <question_answer id="10905"> <question id="1006">Does this business need to register its Trade Name?</question> <answer id="15">Yes</answer> </question_answer> <question_answer id="10117"> <question id="1160">Are there, or will there be employees other than the owner?</question> <answer id="15">Yes</answer> </question_answer> <question_answer id="6177"> <question id="1160">Are there, or will there be employees other than the owner?</question> <answer id="15">Yes</answer> </question_answer> <question_answer id="461"> <question id="1349">Will you be renting merchandise for personal or family use with an agreement to obtain ownership when paid in full? </question> <answer id="15">Yes</answer> </question_answer> <question_answer id="8541"> <question id="1159">Will the business be constructed from the ground up, on a location affecting 5 acres or more?</question> <answer id="15">Yes</answer> </question_answer> <question_answer id="6965"> <question id="1157">Will your business occupy a building or structure that will require construction or alteration to its current construction?</question> <answer id="15">Yes</answer> </question_answer> </response>
Used by third-party agencies to retrieve information about a registered SBRS user's answers given to questions regarding business type. The matrix lists all questions returned to the user upon registration within SBRS. It also includes the answers they supplied.
This information can be used to populate data fields within their own systems. The data is returned in an open XML format.
http://domain.com/step_complete
<?xml version='1.0'?> <response> <from>SBRS</from> <status>ok</status> </response>
Used by third-party agencies to retrieve agency specific information. This will allow each agency to view the agency's contact information stored in the SBRS database to verify it's validity.
This information can be used to populate data fields within their own systems. The data is returned in an open XML format.
http://domain.com/get_agency_info
<?xml version='1.0'?> <response> <from>SBRS</from> <stat>ok</stat> <method>Commerce.SBRS.agency_info</method> <id>1</id> <name>Agency ABC</name> <address1>700 N Greenwood Ave Ste 1400</address1> <address2></address2> <city>Tulsa</city> <state>OK</state> <zip>74106</zip> <phone>918-555-1212</phone> <fax>918-555-12121</fax> <website>okcommerce.gov</website> <contact_name>John Doe</contact_name> <contact_email>918-555-1212</contact_email> </response>
To demonstrate the use of the API, please review the PHP code below. This is useable code if you are currently running PHP 5+.
<?php
class sbrsRequest {
var $urls;
var $sbrs_url = 'http://dev3.okcommerce.gov/oauth';
var $url_request_token = '/request_token';
var $url_validate_user = '/validate_user';
var $url_request_user = '/request_user';
var $url_request_matrix = '/request_matrix';
var $url_get_agency_info= '/get_agency_info';
var $key = "ea6432a402016f9e8ba18a8c51d64912b96cdb1d";
var $secret = "dbc2e7269b6634646a90d148d1441323c5c9c579";
var $auth_token;
var $xml_response;
var $post_vals;
var $user;
function sbrsRequest() {
global $config;
$this->urls = array(
'request_token' => $this->sbrs_url . $this->url_request_token,
'validate_user' => $this->sbrs_url . $this->url_validate_user,
'request_user' => $this->sbrs_url . $this->url_request_user,
'request_matrix' => $this->sbrs_url . $this->url_request_matrix,
'step_complete' => $this->sbrs_url . $this->url_step_complete,
'get_agency_info'=> $this->sbrs_url . $this->url_get_agency_info
);
$this->post_vars = array(
'validate_user' => array('key'=>'','secret'=>'','access_token'=>''),
'request_token' => array('key'=>'','secret'=>'','access_token'=>''),
'get_agency_info'=> array('key'=>'','secret'=>'','access_token'=>'','auth_token'=>''),
'request_user' => array('key'=>'','secret'=>'','access_token'=>'','auth_token'=>''),
'request_matrix' => array('key'=>'','secret'=>'','access_token'=>'','auth_token'=>''),
'step_complete' => array('key'=>'','secret'=>'','access_token'=>'','auth_token'=>'')
);
require($config->path->app . '/API/sbrs.agency.class.php');
$this->agency = new sbrsAgency();
}
####
#
#
# Get The Auth Token
function post_values($array) {
// Generate the POST string
$ret = '';
foreach($this->post_vars[$array] as $key=>$val) :
if ( empty($this->$key) ) :
else :
$ret .= $key.'='.urlencode($this->$key).'&';
endif;
endforeach;
// Chop of the trailing ampersand
$ret = rtrim($ret, '&');
return $ret;
}
####
#
#
# Get The Auth Token
function validate_user() {
$auth_token = '';
parse_str($_SERVER['QUERY_STRING']);
$this->access_token = $access_token;
if ( !empty($this->access_token) ) :
$ret = $this->post_values('validate_user');
// make the request to the server
$ch = curl_init( $this->urls['validate_user'] );
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $ret);
$response = curl_exec($ch);
curl_close ($ch);
// parse the XML returned
$this->xml = simplexml_load_string($response);
// set the application variables
$this->valid_user = $this->xml->status;
$this->user_id = $this->xml->user_id;
$this->business_id = $this->xml->business_id;
return $this->valid_user;
else :
return false;
endif;
}
####
#
#
# Get The Auth Token
function get_token() {
$ret = $this->post_values('request_token');
// make the request to the server
$ch = curl_init( $this->urls['request_token'] );
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $ret);
$response = curl_exec($ch);
curl_close ($ch);
// parse the XML returned
$this->auth_token_xml = simplexml_load_string($response);
// set the application variables
$this->auth_token = $this->auth_token_xml->auth_token;
}
####
#
#
# Get the User Info
function get_user_info() {
global $app;
$ret = $this->post_values('request_user');
// make the request to the server
$ch = curl_init( $this->urls['request_user'] );
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $ret);
$response = curl_exec($ch);
curl_close ($ch);
// parse the XML returned
$this->user_info_xml = $response;
$this->xml_parsed = simplexml_load_string($response);
// return the parsed XML
return $this->xml_parsed;
}
####
#
#
# Get the User Info
function step_complete() {
global $app;
$ret = $this->post_values('step_complete');
// make the request to the server
$ch = curl_init( $this->urls['step_complete'] );
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $ret);
$response = curl_exec($ch);
curl_close ($ch);
// parse the XML returned
$this->step_complete_xml = $response;
$this->xml_parsed = simplexml_load_string($response);
// return the parsed XML
return $this->xml_parsed;
}
####
#
#
# Get the User Info
function get_user_matrix() {
global $app;
$ret = $this->post_values('request_matrix');
// make the request to the server
$ch = curl_init( $this->urls['request_matrix'] );
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $ret);
$response = curl_exec($ch);
curl_close ($ch);
// parse the XML returned
$this->user_matrix_xml = $response;
$this->xml_parsed = simplexml_load_string($response);
// return the parsed XML
return $this->xml_parsed;
}
####
}
$sbrs = new sbrsRequest();
/* *************************************************************************************
* code for the sbrs.agency.class.php file included in the sbrsRequest() method
************************************************************************************* */
/*
*
*
* This class is built simply for pulling agency details
* All information is read-only
*
*/
class sbrsAgency {
function sbrsAgency() {
global $auth;
if (isset($_POST['auth_token']) && isset($_POST['user_id'])) :
$this->id = $_POST['user_id'];
$this->registration_id = $_POST['business_id'];
return true;
endif;
return true;
}
// get the details of the agency stored in the SBRS database
function get_info() {
global $sbrs;
// Set the Query POST parameters
$sbrs->post_vars['get_agency_info']['key'] = $sbrs->key;
$sbrs->post_vars['get_agency_info']['secret'] = $sbrs->secret;
$sbrs->post_vars['get_agency_info']['auth_token'] = $sbrs->auth_token;
// Generate the POST string
$ret = '';
foreach($sbrs->post_vars['get_agency_info'] as $key => $value) :
$ret .= $key.'='.urlencode($value).'&';
endforeach;
// Chop of the trailing ampersand
$ret = rtrim($ret, '&');
// make the request to the server
$ch = curl_init( $sbrs->urls['get_agency_info'] );
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $ret);
$response = curl_exec($ch);
curl_close ($ch);
// parse the XML returned
$this->xml = $response;
$this->xml_parsed = simplexml_load_string($response);
// return the parese XML
return $this->xml;
}
}
?>