{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"48077ca6-1f50-48c0-a2cb-c85965295744","name":"DEXMA Public API","description":"# API Usage\n\nWe **strongly encourage you to have some patience and read this page before starting to use the API**, it will save you lots of time, we guarantee.\n\nThe following sections define the conventions that we use for the syntax of our API, the **Authorization** and **Authentication** methods, the **Rate Limits** and how to use them and one of the most important ones, the **Pagination**.\n\n# Handshake process\n\nThis section explains the Market apps handshaking mechanism. This process will generate a permanent token aka \"`x-dexcell-token`\". The handshake is always started by DEXMA platform upon installing an application via the market app. DEXMA will make call to a given endpoint.  \nNotice: The token returned from DEXMA Platform APIv3 should be stored in the app, and be used it in every request. If the token is lost, the user should reinstall the app to generate another.\n\n<img src=\"https://storage.googleapis.com/dexma/images/AppInstallationWhite.png\">\n\n## Steps:\n\n1. DEXMA makes a GET request to the URL given in the app creation process with the following query parameters:\n    \n    - **dep_id**: Unique identifier for a given deployment\n        \n    - **temp_token**: Temporary token generated by DEXMA to be able to make the handshake\n        \n    - **callback**: legacy parameter, this could be ignored.\n        \n2. App makes a POST request to APIv3 to generate the permanent token with the following query parameters:\n    \n    - **app_id**: Identifier provided when the app is created in the platform\n        \n    - **secret**: hash provided when the app is created in the platform\n        \n    - **temp_token**: This token is provided when DEXMA calls the app to do the handshake (See step 1)\n        \n3. The APIv3 returns **201 CREATED**, with the permanent token as body\n    \n4. The app returns **200 OK** to DEXMA letting it know that the app is installed correctly  \n    For information on how to create the app in the platform check [here](https://support.dexma.com/hc/en-gb/articles/360017221059).\n    \n\n## Usage example:\n\nA new app is created in DEXMA platform with the installation URL: `app.domain.com/setup` and DEXMA shows that the created app id is `63` and secret is `0100fb25d3daa10c9d9b`.  \nThe APIv3 URL is `https://api.dexma.com/v3`  \nThe current deployment id is `demoDEXMA-e2db4391`  \nWhen the user clicks the install button in platform app market:\n\n1. DEXMA makes a GET request to the URL `app.domain.com/setup?dep_id=demoDEXMA-e2db4391&temp_token=022a02b27ee5ca5d1c42&callback=www.dexma.com`\n    \n2. The app receives the request and makes a [POST](https://documenter.getpostman.com/view/5735561/SzRuXXFd?version=latest#ede4d154-f75c-4465-9115-2f409f1ca532) request to the URL: `https://api.dexma.com/v3/oauth/access-token?app_id=63&secret=0100fb25d3daa10c9d9b&temp_token=022a02b27ee5ca5d1c42`\n    \n3. The APIv3 returns the `Status Code 201 CREATED`, with body: `5b36281ac7034f9a65cd`\n    \n4. The app stores the given permanent token and returns `Status Code 200 OK`\n    \n\n# Security\n\nSecurity is composed in two steps, authentication (who you are) and authorization (what you are allowed to do) .\n\n## Authentication\n\nOur process of authentication verifies if you can enter to the system. This process are performed using tokens:\n\n`x-dexcell-token`\n\nThis token should be added as an especial header in HTTP requests.  \n**Tokens are related to applications**, and those will be provided during the OAUTH \"handshake\" process using DEXCell Developer Portal. You can request your Developer portal activation at [support@dexma.com](https://mailto:support@dexma.com). Check the \"Getting Started\" page to know how to obtain the tokens.\n\n## Authorization\n\nAuthorization is the process of allowing an authenticated HTTP requests to access to our resources. Authorization deny or grant access to a specific resource checking the rules that determine who is allowed to do what. It is associated with **an application is directly bound to a deployment (customer account)**.\n\nAuthorization is divided into two concepts:\n\n- **Scope**: Determines if an application has read/write rights to access to specific scopes (zones) of our API. For example, an Application could have privileges to read locations but not to modify. Scopes are defined in the application installation process, through DEXCell.com\n    \n- **ACL (Access Control List)**: This process is the last step before you access, read or write, to a specific resource. Each resource in  \n    our system has an identifier, this identifier is used as a security attribute that identifies if you can access it.\n    \n\n# Rate Limiting\n\nTo make the API fast for everybody, rate limits apply. We only allow a certain number of requests per hour, and a certain number of requests per day. We reserve the right to adjust the rate limit for given endpoints in order to provide a high quality of service for all customers. As an API consumer, you should expect to be able to make at least a certain requests per hour or day.\n\nIf the rate limit is exceeded, DEXCell API will respond with 429 Too Many Requests response code, and a body details the reason for the rate limiter kicking in. You should anticipate this in your API client for the smoothest possible ride.\n\n1. Rate limits are defined per **Application**, for example:\n    \n    - Application A may have: 1000 calls/hour 10.000 calls/day\n        \n    - Application B may have: 2000 calls/hour 30.000 calls/day\n        \n2. Rate limits are applied per **Token**, and there is a token for each relation of Application with Account where it is installed, for example:\n    \n    - Application A installed in Account 1 (token A1) can have remaining 600 calls/hour and 8.000 calls/day (already used 400/h and 2.000/d).\n        \n    - Application B installed in Account 1 (token B1) can have remaining 1200 calls/hour and 20.000 calls/day (already used 800/h and 10 .000/d).\n        \n    - Application A installed in Account 2 (token A2) can have remaining 1000 calls/hour and 10.000 calls/day (nothing used).\n        \n\nSo Application A installed in 4 accounts has 4.000 calls/hour total (1.000 to access each account).\n\nEach request to the API **informs** the Application of the Rate-limit status with the following **Response Headers**. The following example is after having made only 1 today to the API using one token:\n\n```\n    X-Ratelimit-Day-Limit →10000 (total number of calls allowed per Day)\n    X-Ratelimit-Day-Remaining →9999  (number of calls remaining for today)\n    X-Ratelimit-Day-Reset →36296 (seconds until the next interval when the 10.000 daily calls are available again)\n    X-Ratelimit-Hour-Limit →1000  (total number of calls allowed per Hour)\n    X-Ratelimit-Hour-Remaining →999 (number of calls remaining for this Hour)\n    X-Ratelimit-Hour-Reset →296 (seconds until the next interval when the 1.000 hourly calls are available again)\n\n ```\n\n# Session filtering\n\nTo make the API scalable and avoid returning a lot of information for a given endpoint, We allow the option to add the `X-dexcell-session`. The session id is given by Dexcell when an app is loaded.\n\nSession filter cases:\n\n1. The header is not present, the filtering is ignored and returns all the information available.\n    \n2. The header is present and is invalid returns HTTP 403 Forbidden.\n    \n3. The header is present and valid, returns the result filtered by the current user, current location and currently active tags.\n    \n\nDisclaimer: This feature is new and currently works for some endpoints, each endpoint will inform is managing this filter or not.\n\n# Pagination\n\nBy default, all list calls will return **20 items per page**. You can change the number of items to show by passing `start` and `limit`  \nparameters in the request URL. Example:\n\n`http:.../devices?start=50&limit=200`\n\nHowever, you can't exceed **500 records** per page. When the response exceeds the per-page maximum, you will get an Error code:\n\n\\->> REVIEW\n\n``` json\n   {\n     \"status\": 422,\n     \"code\": \"E422\",\n     \"message\": \"Entity validation error\",\n     \"errors\": [\n       1\n     ],\n     \"0\": {\n       \"message\": \"must be less than or equal to 500\",\n       \"field\": \"limit\"\n     }\n   }\n\n ```\n\n# Common Response Structures\n\nWe respond to successful requests with HTTP status code in the **200 range**. When you create or update a resource, we will render the  \nresulting JSON representation in the response body, e.g:\n\n``` json\n    {\n      \"id\": 3473,\n      \"name\": \"General\",\n      \"local_id\": \"1\",\n      \"datasource\": {\n        \"id\": 260\n      },\n      \"status\": \"ACCEPTED\",\n      \"datapoints\": [\n        2\n      ],\n      \"0\": {\n        \"parameter\": 411,\n        \"status\": \"ACCEPTED\"\n      },\n      \"1\": {\n        \"parameter\": 414,\n        \"status\": \"ACCEPTED\"\n      }\n    }\n\n ```\n\n# Model Exposed\n\nHere is explained the basics of DEXCell Energy Manager and how are related.\n\n- **Deployment**: This represents the customer account. Is identified by an account_id.\n    \n- **Datasource**: gateway or datalogger capable to send all the information to DEXCell EM. It includes N devices.\n    \n- **Device**: Each one of the meters and sensors installed. It is possible to get all the devices under deployment or under a location.\n    \n- **Parameter**: identifier of each datapoint sent. For example: Active Energy, Reactive Energy, Temperature, etc.\n    \n- **Readings**: all the readings for a specific device and parameter. It can be filtered by frequency (hourly, daily, monthly, etc)\n    \n- **Location**: Each one of the locations configured in the platform. Location information includes address, reference devices, assigned - devices, configured kpi, supplies and prices associated, etc.\n    \n- **Supplies**: it contains the information about the contract and the prices used to calculate all the Cost information.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"5735561","team":394388,"collectionId":"48077ca6-1f50-48c0-a2cb-c85965295744","publishedId":"SzRuXXFd","public":true,"publicUrl":"https://developers.dexma.com","privateUrl":"https://go.postman.co/documentation/5735561-48077ca6-1f50-48c0-a2cb-c85965295744","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.0","publishDate":"2020-08-28T05:29:07.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://dexma.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://developers.dexma.com/view/metadata/SzRuXXFd"}