{"__v":19,"_id":"543d1e5f5276641a00a593d1","api":{"auth":"never","basic_auth":false,"params":[],"results":{"codes":[]},"settings":"","try":true,"url":""},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Before You Begin\"\n}\n[/block]\nBefore you can start using the API you need to get your hands on an API key.\nTo get an API key, head over to [the developers page](https://business.shopgun.com/developers),\nclick on \"Manage Apps\" and create a new App.\n\nPlease take the time to write a few lines in the \"description\" field, about the intent and purpose of your app.\n\nIf you are going to use the API key in a website, you need to add the list of domains you will be using. If you develop on a local web server you'll want to add \"localhost\" to the list of valid domains.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Rate Limit\",\n  \"body\": \"Apps will be rate limited by default.\\nYou can see your remaining limit in the `X-RateLimit-*` response header.\\nIf you need more requests per hour than what you currently have available, please contact support with your with your API key, and a request to increase the limit.\\n\\nThe default limit should be more than enough for development and small applications.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What is this \\\"key\\\" and \\\"secret\\\"\"\n}\n[/block]\nThe API key is used every time you need to create a new session.\nThis is true for all platforms.\n\nThe API secret is used only when you need to sign your sessions. You need to sign your sessions when requesting from any other platform than a web page (e.g. an Android or iPhone app).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"NOTE\",\n  \"body\": \"Your API secret is - well - secret. You should treat it as your app's password to the API.\"\n}\n[/block]\nWhen you request from a web page, you do not need to sign your requests. Instead; we use the origin of the request (the domain the request is comming from) to check if we should allow it trough. We check this against the list of allowed domains you added when you created the app.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Started\"\n}\n[/block]\nOnce you got yourself an API key, you can begin to do API requests.\n\nThe eTilbudsavis API is designed around API sessions. API sessions are kind of like request \"channels\". They allow you to keep state across different request, so you don't have to send login information for every single request.\n\nLuckily, getting a session token is easy.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Session\"\n}\n[/block]\nAPI sessions are managed via the Session endpoints.\n\nTo create an API Session, you send a `POST` request to `/v2/sessions` with your API key.\nThis will return you a new API Session Token. You can read more about addional arguments\nto the session endpoints on the [Session Create](doc:session-create) docs.\n \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /v2/sessions HTTP/1.1\\nHost: api.etilbudsavis.dk\\nContent-Type: application/json\\nAccept: application/json\\n\\n{\\n\\t\\\"api_key\\\": \\\"[[app:key]]\\\"\\n}\",\n      \"language\": \"http\",\n      \"name\": \"HTTP Request\"\n    }\n  ]\n}\n[/block]\nIf successful, the above request will return the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/1.1 201 Created\\nAccess-Control-Allow-Methods: HEAD,POST,GET,PUT,DELETE,OPTIONS\\nAccess-Control-Allow-Origin: *\\nAccess-Control-Expose-Headers: X-Token, X-Token-Expires, Retry-After\\nAccess-Control-Max-Age: 1800\\nContent-Type: application/json\\nX-Token: 00i1m74tht1p4391\\nX-Token-Expires: 2014-10-30T14:19:34+0000\\nContent-Length: 224\\n\\n{\\n    \\\"token\\\": \\\"00i1m74tht1p4391\\\",\\n    \\\"reference\\\": \\\"Ri1n74thtuc\\\",\\n    \\\"expires\\\": \\\"2014-10-30T14:19:34+0000\\\",\\n    \\\"user\\\": null,\\n    \\\"permissions\\\": {\\n        \\\"guest\\\": [\\\"api.public\\\", \\\"api.users.create\\\"]\\n    },\\n    \\\"provider\\\": null,\\n    \\\"client_id\\\": \\\"00i1m74thtzd84czv848f4c1zezztolj\\\"\\n}\",\n      \"language\": \"http\",\n      \"name\": \"HTTP Response\"\n    }\n  ]\n}\n[/block]\nHere we get the session information as the response payload.\nWe also get the token and it's TTL in the HTTP headers.\n\nEvery request to the API containing a token, will return your currently active session token and it's expiry time.\n\n## Congratulations!\n\nYou now have an active eTilbudsavis API session token.\n\nIf your eTilbudsavis app is a website, you can skip the next section on getting session signatures. Websites don't need to worry about signatures.\n\nIf your **eTilbudsavis app isn't executed by javascript in a browser**, you need to sign your token, before you can start sending requests.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"NOTE\",\n  \"body\": \"> If your **eTilbudsavis app isn't executed by javascript in a browser**, you need to sign your token, before you can start sending requests.\\n> **Do not** simply add an Origin header!\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Session Signatures\"\n}\n[/block]\nYou need to sign your API token session if you are sending requests from outside a modern browser.\n\nThis is where you need your eTilbudsavis app secret key. You got this together with your API key.\n\nYou generate the session signature by concatenating your API secret with your API session token, and hash it as a sha256 hash.\nThe signature is the hex encoded version of the hash.\n\nHere is a few examples:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n$signature = hash(\\\"sha256\\\", $secret.$token);\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"import hashlib\\nsignature = hashlib.sha256(secret+token).hexdigest()\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var crypto = require('crypto');\\nvar signature = crypto.createHash('sha256').update(secret+token).digest('hex');\",\n      \"language\": \"javascript\",\n      \"name\": \"Node.js\"\n    },\n    {\n      \"code\": \"public static String generateSHA256(String string) {\\n    MessageDigest digest=null;\\n    String hash = \\\"\\\";\\n    try {\\n        digest = MessageDigest.getInstance(\\\"SHA-256\\\");\\n        digest.update(string.getBytes());\\n        byte[] bytes = digest.digest();\\n        \\n        StringBuffer sb = new StringBuffer();\\n        for (int i = 0; i < bytes.length; i++) {\\n            String hex = Integer.toHexString(0xFF & bytes[i]);\\n            if (hex.length() == 1) {\\n                sb.append('0');\\n            }\\n            sb.append(hex);\\n        }\\n        hash = sb.toString();\\n    } catch (NoSuchAlgorithmException e1) {\\n        e1.printStackTrace();\\n    }\\n    return hash;\\n}\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Our SDKs will handle the request signing for you.\",\n  \"body\": \"- iOS SDK https://github.com/eTilbudsavis/native-ios-eta-sdk\\n- Android SDK https://github.com/eTilbudsavis/native-android-sdk\\n- Javascript SDK https://github.com/eTilbudsavis/eta-javascript-sdk\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Session Tokens\"\n}\n[/block]\nNow that you have a token (and a signature, if you are building a mobile app), you need to know how to use the token.\n\nThe token must be sent on every request that is not a `POST` to `/v2/sessions`\n\nYou can send the token in two ways:\n\n### As a Header\n\nYou can set the token in your request headers. The token header is called `X-Token`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/sessions HTTP/1.1\\nHost: api.etilbudsavis.dk\\nContent-Type: application/json\\nAccept: application/json\\nX-Token: <your token here>\\n\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nIf you are building a mobile app, you need to set your signature in the same way. The signature request header is called `X-Signature`.\n\n\n\n### In the Query String\n\nAlternatively, you can add the token to the query string. The parameter is in this case named `_token`. This is in some cases more convenient than using a header.\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/sessions?_token=<your token here> HTTP/1.1\\nHost: api.etilbudsavis.dk\\nContent-Type: application/json\\nAccept: application/json\\n\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n(If you aren't building a javascript-in-the-browser app, you need to set your signature in the same way. The signature query string parameter is called `_signature`)\n\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Congratulations!\"\n}\n[/block]\nYou now know everything you need to start using the API.","category":"543d1e5f5276641a00a593d0","createdAt":"2014-10-14T12:59:18.394Z","excerpt":"This page will help you get started with eTilbudsavis API. You'll be up and running in a jiffy!","githubsync":"","hidden":false,"is_link":false,"link_external":false,"link_url":"","order":1,"parentDoc":null,"project":"543d1e263a300f20000d31fb","slug":"getting-started","sync_unique":"","title":"Getting Started with eTilbudsavis API","type":"basic","updates":[],"user":"54352decadf50e0800b89024","version":"543d1e5e5276641a00a593cf","childrenPages":[]}

Getting Started with eTilbudsavis API

This page will help you get started with eTilbudsavis API. You'll be up and running in a jiffy!

[block:api-header] { "type": "basic", "title": "Before You Begin" } [/block] Before you can start using the API you need to get your hands on an API key. To get an API key, head over to [the developers page](https://business.shopgun.com/developers), click on "Manage Apps" and create a new App. Please take the time to write a few lines in the "description" field, about the intent and purpose of your app. If you are going to use the API key in a website, you need to add the list of domains you will be using. If you develop on a local web server you'll want to add "localhost" to the list of valid domains. [block:callout] { "type": "info", "title": "Rate Limit", "body": "Apps will be rate limited by default.\nYou can see your remaining limit in the `X-RateLimit-*` response header.\nIf you need more requests per hour than what you currently have available, please contact support with your with your API key, and a request to increase the limit.\n\nThe default limit should be more than enough for development and small applications." } [/block] [block:api-header] { "type": "basic", "title": "What is this \"key\" and \"secret\"" } [/block] The API key is used every time you need to create a new session. This is true for all platforms. The API secret is used only when you need to sign your sessions. You need to sign your sessions when requesting from any other platform than a web page (e.g. an Android or iPhone app). [block:callout] { "type": "info", "title": "NOTE", "body": "Your API secret is - well - secret. You should treat it as your app's password to the API." } [/block] When you request from a web page, you do not need to sign your requests. Instead; we use the origin of the request (the domain the request is comming from) to check if we should allow it trough. We check this against the list of allowed domains you added when you created the app. [block:api-header] { "type": "basic", "title": "Getting Started" } [/block] Once you got yourself an API key, you can begin to do API requests. The eTilbudsavis API is designed around API sessions. API sessions are kind of like request "channels". They allow you to keep state across different request, so you don't have to send login information for every single request. Luckily, getting a session token is easy. [block:api-header] { "type": "basic", "title": "API Session" } [/block] API sessions are managed via the Session endpoints. To create an API Session, you send a `POST` request to `/v2/sessions` with your API key. This will return you a new API Session Token. You can read more about addional arguments to the session endpoints on the [Session Create](doc:session-create) docs. [block:code] { "codes": [ { "code": "POST /v2/sessions HTTP/1.1\nHost: api.etilbudsavis.dk\nContent-Type: application/json\nAccept: application/json\n\n{\n\t\"api_key\": \"[[app:key]]\"\n}", "language": "http", "name": "HTTP Request" } ] } [/block] If successful, the above request will return the following: [block:code] { "codes": [ { "code": "HTTP/1.1 201 Created\nAccess-Control-Allow-Methods: HEAD,POST,GET,PUT,DELETE,OPTIONS\nAccess-Control-Allow-Origin: *\nAccess-Control-Expose-Headers: X-Token, X-Token-Expires, Retry-After\nAccess-Control-Max-Age: 1800\nContent-Type: application/json\nX-Token: 00i1m74tht1p4391\nX-Token-Expires: 2014-10-30T14:19:34+0000\nContent-Length: 224\n\n{\n \"token\": \"00i1m74tht1p4391\",\n \"reference\": \"Ri1n74thtuc\",\n \"expires\": \"2014-10-30T14:19:34+0000\",\n \"user\": null,\n \"permissions\": {\n \"guest\": [\"api.public\", \"api.users.create\"]\n },\n \"provider\": null,\n \"client_id\": \"00i1m74thtzd84czv848f4c1zezztolj\"\n}", "language": "http", "name": "HTTP Response" } ] } [/block] Here we get the session information as the response payload. We also get the token and it's TTL in the HTTP headers. Every request to the API containing a token, will return your currently active session token and it's expiry time. ## Congratulations! You now have an active eTilbudsavis API session token. If your eTilbudsavis app is a website, you can skip the next section on getting session signatures. Websites don't need to worry about signatures. If your **eTilbudsavis app isn't executed by javascript in a browser**, you need to sign your token, before you can start sending requests. [block:callout] { "type": "info", "title": "NOTE", "body": "> If your **eTilbudsavis app isn't executed by javascript in a browser**, you need to sign your token, before you can start sending requests.\n> **Do not** simply add an Origin header!" } [/block] [block:api-header] { "type": "basic", "title": "API Session Signatures" } [/block] You need to sign your API token session if you are sending requests from outside a modern browser. This is where you need your eTilbudsavis app secret key. You got this together with your API key. You generate the session signature by concatenating your API secret with your API session token, and hash it as a sha256 hash. The signature is the hex encoded version of the hash. Here is a few examples: [block:code] { "codes": [ { "code": "<?php\n$signature = hash(\"sha256\", $secret.$token);", "language": "php" }, { "code": "import hashlib\nsignature = hashlib.sha256(secret+token).hexdigest()", "language": "python" }, { "code": "var crypto = require('crypto');\nvar signature = crypto.createHash('sha256').update(secret+token).digest('hex');", "language": "javascript", "name": "Node.js" }, { "code": "public static String generateSHA256(String string) {\n MessageDigest digest=null;\n String hash = \"\";\n try {\n digest = MessageDigest.getInstance(\"SHA-256\");\n digest.update(string.getBytes());\n byte[] bytes = digest.digest();\n \n StringBuffer sb = new StringBuffer();\n for (int i = 0; i < bytes.length; i++) {\n String hex = Integer.toHexString(0xFF & bytes[i]);\n if (hex.length() == 1) {\n sb.append('0');\n }\n sb.append(hex);\n }\n hash = sb.toString();\n } catch (NoSuchAlgorithmException e1) {\n e1.printStackTrace();\n }\n return hash;\n}", "language": "java" } ] } [/block] [block:callout] { "type": "success", "title": "Our SDKs will handle the request signing for you.", "body": "- iOS SDK https://github.com/eTilbudsavis/native-ios-eta-sdk\n- Android SDK https://github.com/eTilbudsavis/native-android-sdk\n- Javascript SDK https://github.com/eTilbudsavis/eta-javascript-sdk" } [/block] [block:api-header] { "type": "basic", "title": "Using Session Tokens" } [/block] Now that you have a token (and a signature, if you are building a mobile app), you need to know how to use the token. The token must be sent on every request that is not a `POST` to `/v2/sessions` You can send the token in two ways: ### As a Header You can set the token in your request headers. The token header is called `X-Token`: [block:code] { "codes": [ { "code": "GET /v2/sessions HTTP/1.1\nHost: api.etilbudsavis.dk\nContent-Type: application/json\nAccept: application/json\nX-Token: <your token here>\n", "language": "http" } ] } [/block] If you are building a mobile app, you need to set your signature in the same way. The signature request header is called `X-Signature`. ### In the Query String Alternatively, you can add the token to the query string. The parameter is in this case named `_token`. This is in some cases more convenient than using a header. Example: [block:code] { "codes": [ { "code": "GET /v2/sessions?_token=<your token here> HTTP/1.1\nHost: api.etilbudsavis.dk\nContent-Type: application/json\nAccept: application/json\n", "language": "http" } ] } [/block] (If you aren't building a javascript-in-the-browser app, you need to set your signature in the same way. The signature query string parameter is called `_signature`) [block:api-header] { "type": "basic", "title": "Congratulations!" } [/block] You now know everything you need to start using the API.