{"__v":69,"_id":"544371233a1a031a00db6223","category":{"__v":5,"_id":"5451f421fcaba808000c0f4c","pages":["544371233a1a031a00db6223","5446382482bd7e080027672f","5448bef9c64edd1a00453bc3","5448bfeac64edd1a00453bca","5468a6dac6918f0800445070","54900fb214e2e914004d6462","55c1eb6d291f182b00cb932a","561469ec1a8caf0d006894ba","563720c24f02240d00358f26"],"project":"544371233a1a031a00db621d","version":"544371233a1a031a00db6220","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-30T08:17:37.418Z","from_sync":false,"order":0,"slug":"guideline","title":"Guideline"},"is_link":false,"parentDoc":null,"project":"544371233a1a031a00db621d","user":"544370c53a1a031a00db621c","version":{"__v":19,"_id":"544371233a1a031a00db6220","project":"544371233a1a031a00db621d","createdAt":"2014-10-19T08:06:59.858Z","releaseDate":"2014-10-19T08:06:59.858Z","categories":["544371233a1a031a00db6221","544373693a1a031a00db6224","5443799eeec0081a00075161","544646d182bd7e0800276763","54478af0b96a63140077d670","54479a7eb96a63140077d6a9","5447af97a1024f14005a6e0a","5447c23e8d7af31a00dd408a","5447c6a28d7af31a00dd409b","5447c8fd0319802200fc065b","5447c9020319802200fc065c","544e42acbd51b9080037f837","5451f39514af501a00b50fa0","5451f421fcaba808000c0f4c","546760c2016b480800bc7bd7","549d423f7805690b004a86a5","54a9516a2c8d8d0b00d08d78","54d9e792537ac319002bf90b","561466bb0ab2550d00166dbd"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-19T08:06:59.927Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"settings":"","try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"This page will help you get started with bringg API. You'll be up and running in no time.\n\nThere are two alternatives to connecting to our API. [Services](http://developers.bringg.com/v1.0/docs/services) - which are unique URLs that are created for one specific environment, and API calls - which are specific URLs that need to be [signed and authenticated](http://developers.bringg.com/docs/authentication).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Are services secured?\",\n  \"body\": \"Yes. By using secured networking (SSL) - your uniquely created URLs are basically a type of user and password!\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Feature\",\n    \"h-1\": \"Services\",\n    \"h-2\": \"APIs\",\n    \"0-0\": \"Ease of use\",\n    \"1-0\": \"Includes all possible features\",\n    \"2-0\": \"Includes real time features\",\n    \"h-3\": \"Customer SDK\",\n    \"3-0\": \"Secured\",\n    \"0-1\": \"Best\",\n    \"0-2\": \"Medium\",\n    \"0-3\": \"Best\",\n    \"1-1\": \"No\",\n    \"1-2\": \"Yes\",\n    \"1-3\": \"Yes\",\n    \"2-1\": \"No\",\n    \"2-2\": \"No\",\n    \"2-3\": \"Yes\",\n    \"3-1\": \"Yes\",\n    \"3-2\": \"Yes\",\n    \"3-3\": \"Yes\"\n  },\n  \"cols\": 4,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Join as a Developer\"\n}\n[/block]\nBefore you start, you will have to register as a Developer:\n* Verify your email address via registration email we sent to you. To resend the verification email use [Company Settings](http://app.bringg.com/#/merchant/) and click on *Resend Confirmation Email* button.\n* Go to [Company Settings](http://app.bringg.com/#/merchant/) and click on *Become a developer* button.\n* Fill out the *Become a developer* form.\n* Go to [Developer](http://app.bringg.com/#/merchant/developer) and copy your *access_token* and *secret_key* (you will have one pair for production and one for test).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Z9PqLfaIQNizH6Dnhtgb_dev.png\",\n        \"dev.png\",\n        \"1058\",\n        \"685\",\n        \"#3a588a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Sign your Request\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"In this example, we are making a call to the [Create Customer](doc:create-customer) endpoint which will create your first Customer with the following details:\\n* Name: Rose M. Scudder\\n* Address: 715 Oliverio Drive, Moundridge, KS 67107\\n* Phone: 620-680-9382\\n* E-mail: RoseMScudder:::at:::dayrep.com\",\n  \"title\": \"Example - creating your first customer\"\n}\n[/block]\nGiven an *access token* of \"12345\" and a *secret key* of \"67890\", follow these steps:\n\n* add *access_token* (provided during registration) & *timestamp* (the current time in unix format) to your parameters:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var params = JSON.parse('{\\\"name\\\": \\\"Rose M. Scudder\\\", \\\"address\\\": \\\"715 Oliverio Drive, Moundridge, KS 67107\\\", \\\"phone\\\": \\\"620-680-9382\\\", \\\"email\\\": \\\"RoseMScudder@dayrep.com\\\"}');\\nparams.timestamp = Date.now();\\nparams.access_token = \\\"12345\\\";\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"params = {\\\"name\\\" => \\\"Rose M. Scudder\\\", \\\"address\\\" => \\\"715 Oliverio Drive, Moundridge, KS 67107\\\", \\\"phone\\\" => \\\"620-680-9382\\\", \\\"email\\\" => \\\"RoseMScudder@dayrep.com\\\"}\\nparams[:timestamp] ||= Time.now.to_i\\nparams[:access_token] ||= \\\"12345\\\"\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n* make the parameters into an [URL encoded](http://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters) query string:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var query_params = '';\\nfor (var key in params) {\\n    var value = params[key];\\n    if (query_params.length > 0) {\\n      query_params += '&';\\n    }\\n    query_params += key + '=' + encodeURIComponent(value);\\n}\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"query_params = params.to_query\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n* sign the query string using an [HmacSHA1](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) mechanism with your *secret key* and add the *signature* to your parameters:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"params.signature = CryptoJS.HmacSHA1(query_params, \\\"67890\\\").toString();\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"params.merge(signature: OpenSSL::HMAC.hexdigest(\\\"sha1\\\", \\\"67890\\\", query_params))\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Make sure you have now 3 new parameters: *timestamp*, *access_token* and *signature*. You may want to verify your signature by using our [Signature Tester](doc:test).\",\n  \"title\": \"Authentication is Done\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. Make the API Call\"\n}\n[/block]\nCreate HTTP POST request to an endpoint:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"request.open('POST', 'http://developer-api.bringg.com/partner_api/customers', true);\\nrequest.setRequestHeader('Content-type', 'application/json');\\nrequest.send(JSON.stringify(params));\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"uri = URI(\\\"http://api.bringg.com/partner_api/customers\\\")\\nreq = Net::HTTP::Post.new(uri, initheader = {'Content-Type' =>'application/json'})\\nreq.body = params.to_json\\nres = Net::HTTP.start(uri.hostname, uri.port) do |http|\\n\\t\\thttp.request(req)\\nend\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nHere is an example of the data that would have been returned:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"customer\\\": {\\n        \\\"id\\\": 1,\\n        \\\"name\\\": \\\"Rose M. Scudder\\\",\\n        \\\"address\\\": \\\"715 Oliverio Drive, Moundridge, KS 67107\\\",\\n        \\\"phone\\\": \\\"620-680-9382\\\",\\n        \\\"email\\\": \\\"RoseMScudder@dayrep.com\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"You have just made your first Bringg API call.\",\n  \"title\": \"Congratulations!\"\n}\n[/block]","excerpt":"","slug":"getting-started","type":"basic","title":"Getting Started with Bringg"}

Getting Started with Bringg


This page will help you get started with bringg API. You'll be up and running in no time. There are two alternatives to connecting to our API. [Services](http://developers.bringg.com/v1.0/docs/services) - which are unique URLs that are created for one specific environment, and API calls - which are specific URLs that need to be [signed and authenticated](http://developers.bringg.com/docs/authentication). [block:callout] { "type": "info", "title": "Are services secured?", "body": "Yes. By using secured networking (SSL) - your uniquely created URLs are basically a type of user and password!" } [/block] [block:parameters] { "data": { "h-0": "Feature", "h-1": "Services", "h-2": "APIs", "0-0": "Ease of use", "1-0": "Includes all possible features", "2-0": "Includes real time features", "h-3": "Customer SDK", "3-0": "Secured", "0-1": "Best", "0-2": "Medium", "0-3": "Best", "1-1": "No", "1-2": "Yes", "1-3": "Yes", "2-1": "No", "2-2": "No", "2-3": "Yes", "3-1": "Yes", "3-2": "Yes", "3-3": "Yes" }, "cols": 4, "rows": 4 } [/block] [block:api-header] { "type": "basic", "title": "1. Join as a Developer" } [/block] Before you start, you will have to register as a Developer: * Verify your email address via registration email we sent to you. To resend the verification email use [Company Settings](http://app.bringg.com/#/merchant/) and click on *Resend Confirmation Email* button. * Go to [Company Settings](http://app.bringg.com/#/merchant/) and click on *Become a developer* button. * Fill out the *Become a developer* form. * Go to [Developer](http://app.bringg.com/#/merchant/developer) and copy your *access_token* and *secret_key* (you will have one pair for production and one for test). [block:image] { "images": [ { "image": [ "https://files.readme.io/Z9PqLfaIQNizH6Dnhtgb_dev.png", "dev.png", "1058", "685", "#3a588a", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "2. Sign your Request" } [/block] [block:callout] { "type": "info", "body": "In this example, we are making a call to the [Create Customer](doc:create-customer) endpoint which will create your first Customer with the following details:\n* Name: Rose M. Scudder\n* Address: 715 Oliverio Drive, Moundridge, KS 67107\n* Phone: 620-680-9382\n* E-mail: RoseMScudder@dayrep.com", "title": "Example - creating your first customer" } [/block] Given an *access token* of "12345" and a *secret key* of "67890", follow these steps: * add *access_token* (provided during registration) & *timestamp* (the current time in unix format) to your parameters: [block:code] { "codes": [ { "code": "var params = JSON.parse('{\"name\": \"Rose M. Scudder\", \"address\": \"715 Oliverio Drive, Moundridge, KS 67107\", \"phone\": \"620-680-9382\", \"email\": \"RoseMScudder@dayrep.com\"}');\nparams.timestamp = Date.now();\nparams.access_token = \"12345\";", "language": "javascript" }, { "code": "params = {\"name\" => \"Rose M. Scudder\", \"address\" => \"715 Oliverio Drive, Moundridge, KS 67107\", \"phone\" => \"620-680-9382\", \"email\" => \"RoseMScudder@dayrep.com\"}\nparams[:timestamp] ||= Time.now.to_i\nparams[:access_token] ||= \"12345\"", "language": "ruby" } ] } [/block] * make the parameters into an [URL encoded](http://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters) query string: [block:code] { "codes": [ { "code": "var query_params = '';\nfor (var key in params) {\n var value = params[key];\n if (query_params.length > 0) {\n query_params += '&';\n }\n query_params += key + '=' + encodeURIComponent(value);\n}", "language": "javascript" }, { "code": "query_params = params.to_query", "language": "ruby" } ] } [/block] * sign the query string using an [HmacSHA1](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) mechanism with your *secret key* and add the *signature* to your parameters: [block:code] { "codes": [ { "code": "params.signature = CryptoJS.HmacSHA1(query_params, \"67890\").toString();", "language": "javascript" }, { "code": "params.merge(signature: OpenSSL::HMAC.hexdigest(\"sha1\", \"67890\", query_params))", "language": "ruby" } ] } [/block] [block:callout] { "type": "success", "body": "Make sure you have now 3 new parameters: *timestamp*, *access_token* and *signature*. You may want to verify your signature by using our [Signature Tester](doc:test).", "title": "Authentication is Done" } [/block] [block:api-header] { "type": "basic", "title": "3. Make the API Call" } [/block] Create HTTP POST request to an endpoint: [block:code] { "codes": [ { "code": "request.open('POST', 'http://developer-api.bringg.com/partner_api/customers', true);\nrequest.setRequestHeader('Content-type', 'application/json');\nrequest.send(JSON.stringify(params));", "language": "javascript" }, { "code": "uri = URI(\"http://api.bringg.com/partner_api/customers\")\nreq = Net::HTTP::Post.new(uri, initheader = {'Content-Type' =>'application/json'})\nreq.body = params.to_json\nres = Net::HTTP.start(uri.hostname, uri.port) do |http|\n\t\thttp.request(req)\nend", "language": "ruby" } ] } [/block] Here is an example of the data that would have been returned: [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"customer\": {\n \"id\": 1,\n \"name\": \"Rose M. Scudder\",\n \"address\": \"715 Oliverio Drive, Moundridge, KS 67107\",\n \"phone\": \"620-680-9382\",\n \"email\": \"RoseMScudder@dayrep.com\"\n }\n}", "language": "json" } ] } [/block] [block:callout] { "type": "success", "body": "You have just made your first Bringg API call.", "title": "Congratulations!" } [/block]