RMS API Credits: Difference between revisions
no edit summary
No edit summary |
No edit summary |
||
(20 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
__TOC__ | __TOC__ | ||
== Introduction == | |||
Using the RMS API allows users to automate tasks and integrate RMS into their own solutions. In this guide, an example will be provided which step-by-step shows a way to apply the RMS API to manage your RMS credit balance, as well as create a credit code used for transferring credits between different accounts. | |||
Such an application of the RMS API could be used in solutions where transferring credits is an automated process, not requiring any manual input. | |||
All documentation of the RMS API can be found here - https://developers.rms.teltonika-networks.com/ | |||
This example only includes using Personal Access Tokens to use the API. The RMS API also allows for Application Authentication, used specifically in applications that can use RMS as an OAuth provider. | |||
===Two-Factor Authentication=== | ===Two-Factor Authentication=== | ||
---- | ---- | ||
Firstly, to create a Personal Access Token, your account must have Two-Factor Authentication enabled. | Firstly, to create a Personal Access Token, your account must have [[Teltonika ID|Two-Factor Authentication]] enabled. | ||
This can be done by going to your RMS Account settings and then the Security page. Any Authentication type (other than None) is viable. | This can be done by going to your RMS Account settings and then the Security page. Any Authentication type (other than None) is viable. | ||
Once Two-Factor authentication is enabled, you can then head over to the API → Access tokens page of your Account settings to begin creating a Personal Access token. | Once Two-Factor authentication is enabled, you can then head over to the API → Access tokens page of your Account settings to begin creating a Personal Access token.<br> | ||
<br> | |||
[[File:RMS Settings Two Factor Authentication.png|none|thumb|950x950px|RMS Settings Two Factor Authentication]] | |||
<br> | |||
===Add new access token=== | ===Add new access token=== | ||
Line 20: | Line 28: | ||
Once there, simply press Add new access token. | Once there, simply press Add new access token. | ||
[[File:RMS API Add new access token.png|none|thumb|850x850px]] | |||
Next, input a name for this access token and select the necessary Scopes. Scopes are basically permissions – what the access token will be capable of doing in your account. For this example, we will be selecting these scopes: | Next, input a name for this access token and select the necessary Scopes. Scopes are basically permissions – what the access token will be capable of doing in your account. For this example, we will be selecting these scopes: | ||
Line 26: | Line 35: | ||
* '''credit_transfer_codes:read''' | * '''credit_transfer_codes:read''' | ||
* '''credit_transfer_codes:write''' | * '''credit_transfer_codes:write''' | ||
<br> | <br> | ||
[[File:RMS_API_Credits_-_read_-_transfer_codes_read_write.png|alt=|none|frame|Selected scopes for RMS API Credits]] | [[File:RMS_API_Credits_-_read_-_transfer_codes_read_write.png|alt=|none|frame|Selected scopes for RMS API Credits]] | ||
Line 31: | Line 41: | ||
These scopes will allow us to read information about our current credits and credit codes, as well as create new credit codes. After selecting the necessary scopes, press Save Personal Access Token – you will be shown a table containing your Personal Access Token. WARNING: This is the only time the created access token will be shown, make sure to copy it, as you will not be able to see it again. | These scopes will allow us to read information about our current credits and credit codes, as well as create new credit codes. After selecting the necessary scopes, press Save Personal Access Token – you will be shown a table containing your Personal Access Token. WARNING: This is the only time the created access token will be shown, make sure to copy it, as you will not be able to see it again. | ||
[[File:RMS API Access Token Example.png|none | <br> | ||
[[File:RMS API Access Token Example.png|none|RMS API Access Token Example|alt=|thumb|500x500px]] | |||
<br> | |||
Now that we have the access token, we can now use the RMS API. All information about each API endpoint can be found in the '''API reference''' | Now that we have the access token, we can now use the RMS API. All information about each API endpoint can be found in the '''API reference''' | ||
Line 39: | Line 51: | ||
==Using the API with Postman to gather information about credit balance== | ==Using the API with Postman to gather information about credit balance== | ||
To get the general information about your current RMS credit balance, we can use the '''GET /credits/summary''' endpoint: | To get the general information about your current RMS credit balance, we can use the '''[https://developers.rms.teltonika-networks.com/pages/api.html#/credits/creditsSummary GET /credits/summary]''' endpoint: | ||
1. Select the GET option and input the endpoint URL into the necessary field - <nowiki>https://rms.teltonika-networks.com/api/credits/summary</nowiki>. | 1. Select the GET option and input the endpoint URL into the necessary field - <nowiki>https://rms.teltonika-networks.com/api/credits/summary</nowiki>. | ||
Line 55: | Line 67: | ||
4. Press Send. | 4. Press Send. | ||
[[File:Rms Api Wiki Credits Part 1.mp4|750px]] | |||
If everything was done correctly, you should get a response containing information about your credit balance. This includes: | If everything was done correctly, you should get a response containing information about your credit balance. This includes: | ||
Line 63: | Line 76: | ||
* Credit coverage – The date provided shows how long your currently owned amount of credits is enough for your current RMS setup. This takes into account the amount of devices and their credit configuration (Service and Auto Extend). The calculation also considers if you have any subsidiary RMS companies that have the “Use parent credits” option enabled. | * Credit coverage – The date provided shows how long your currently owned amount of credits is enough for your current RMS setup. This takes into account the amount of devices and their credit configuration (Service and Auto Extend). The calculation also considers if you have any subsidiary RMS companies that have the “Use parent credits” option enabled. | ||
==Using the API with postman to manage RMS credit codes== | ==Using the API with postman to manage RMS credit codes== | ||
To get general information about your RMS credit codes, you can use the '''GET /credits/codes''' endpoint: | To get general information about your RMS credit codes, you can use the '''[https://developers.rms.teltonika-networks.com/pages/api.html#/credits%20codes/creditsTokensAll GET /credits/codes]''' endpoint: | ||
1. Select the GET option and input the endpoint URL into the necessary field – <nowiki>https://rms.teltonika-networks.com/api/credits/codes</nowiki>; | 1. Select the GET option and input the endpoint URL into the necessary field – <nowiki>https://rms.teltonika-networks.com/api/credits/codes</nowiki>; | ||
Line 82: | Line 94: | ||
4. Press Send. | 4. Press Send. | ||
[[File:Rms Api Wiki Credits Part 2.mp4|750px]] | |||
If everything was done correctly, you should get a response containing a list of your credit codes and general information. This includes information such as the code itself, what company it has been used by (if it has been used), creation date, etc. | If everything was done correctly, you should get a response containing a list of your credit codes and general information. This includes information such as the code itself, what company it has been used by (if it has been used), creation date, etc. | ||
Line 87: | Line 101: | ||
===Generate a new credit code=== | ===Generate a new credit code=== | ||
---- | ---- | ||
To generate a new credit code, you can use the '''POST /credits''/''codes''' endpoint: | To generate a new credit code, you can use the '''[https://developers.rms.teltonika-networks.com/pages/api.html#/credits%20codes/creditsTokensAdd POST /credits''/''codes]''' endpoint: | ||
1. Select the POST option and input the endpoint URL into the necessary field – <nowiki>https://rms.teltonika-networks.com/api/credits/codes</nowiki>; | 1. Select the POST option and input the endpoint URL into the necessary field – <nowiki>https://rms.teltonika-networks.com/api/credits/codes</nowiki>; | ||
Line 101: | Line 115: | ||
3. In the Body tab, input the necessary Request body (many POST requests require request bodies). For example: | 3. In the Body tab, input the necessary Request body (many POST requests require request bodies). For example: | ||
{ | { | ||
''"amount": 4, | |||
''"amount": 4, | "comment": "Some example comment", | ||
"company_id": 458'' | |||
"comment": "Some example comment", | } | ||
"company_id": 458'' | |||
} | |||
* Amount – The number of credits you wish the credit code to contain. This cannot exceed the maximum credits that your RMS company currently owns. | * Amount – The number of credits you wish the credit code to contain. This cannot exceed the maximum credits that your RMS company currently owns. | ||
Line 116: | Line 126: | ||
4. Press Send. | 4. Press Send. | ||
[[File:Rms Api Wiki Credits Part 3.mp4|750px]] | |||
If everything was done correctly, you should receive a response containing the credit code, which can be used by anyone. | If everything was done correctly, you should receive a response containing the credit code, which can be used by anyone. |