Here's a short introduction to the Tehden API. The API follows the OAuth 2.0 specification. Text encoding is always UTF-8. Requests and responses are in JSON format.
Tehden API restrictions are per IP address 15 queries/s and 30 burst. If the request falls within the rate limit, the HTTP status code is 429.
Remember to always use API version 1. We maintain one version of the API, and we notify the integration's implementer and the company using it of any changes by email.
The API documentation follows the OpenAPI 3.0.3 standard. You can access Tehden API documentation here: apidoc.tehden.com
We also maintain a change log on the API: Tehden API documentation's Changelog
Accessing Tehden API
To use Tehden API, the company's Tehden order must contain a valid interface module. The company can acquire the module from the sales team (myynti@tehden.com). For API calls, we create a client ID which can be obtained from the API team (api.support@tehden.com).
Getting an access token
- The password method uses API client specific user credentials.
- The authorization code method has two steps and requires an end-user's approval for the request.
Password method: Requesting an access token
Client must authenticate either by
- Authorization header "Authorization: Basic HASH_DIGEST" where HASH_DIGEST is base64 encoded string of "client_id:client_secret"
- Adding client_id and client_secret as GET/POST parameters
GET/POST https://somecompany.tehden.com/oauth/oaclient/token
Parameters
- grant_type: Tehden supports "password" which is used for API client specific users
- username: The username of the API client user. Obtained when an API user is created with client id in the company's Tehden.
- password: The password of the API client user. Obtained when an API user is created with client id in the company's Tehden.
- redirect_uri: Must be identical with the redirect_uri given in the "Authorization code: Asking for authorization" part
- + client credentials (client_id and client_secret) if authenticating using GET/POST parameters
Result
JSON object with the following fields
- access_token: Access token used to access the API
- expires_in: Time in seconds after which the access token expires
- token_type: "Bearer" supported by Tehden
- scope: List of scopes allowed, string delimited by spaces
- refresh_token: A token that can be used to get a new access token after it expires
Refreshing access token
Client must authenticate either by
- Authorization header "Authorization: Basic HASH_DIGEST" where HASH_DIGEST is a base64 encoded string of "client_id:client_secret"
- Adding client_id and client_secret as GET/POST parameters
GET https://somecompany.tehden.com/oauth/oaclient/token
Parameters in URL
Parameters
- grant_type: String "refresh_token"
- refresh_token: The refresh token acquired earlier
- (optional) scope: If asking for an additional scope
- + client credentials (client_id and client_secret) if authenticating using GET/POST parameters
Result
JSON object with the following fields:
- access_token: access token used to access the API
- expires_in: time in seconds after which the access token expires
- token_type: "Bearer" supported by Tehden
- scope: list of scopes allowed, string delimited by spaces
- refresh_token: a token that can be used to get a new access token after it expires
Authorization code: Asking for authorization
The client redirects the user to
GET https://somecompany.tehden.com/oauth/oauser/authorize
Parameters in URL (because it's a redirect).
Parameters
- client_id: client to be authorized
- response_type: defines authorization type, currently Tehden only supports "code" (Authorization code).
- (optional) redirect_uri: must be in the same domain as what is stored in the database during registering
- (optional) scope: space delimited list of requested scopes
- (optional) state: a string that is always returned the same to the client, for state handling on client side
Result
- If allowed, the user is redirected to the URL in the database (or parameters) with response parameters
- redirect_uri?state=WHAT_WAS_GIVEN&code=AUTHORIZATION_CODE
Authorization code: Getting access token with authorization code
Client must authenticate either by
- Authorization header "Authorization: Basic HASH_DIGEST" where HASH_DIGEST is a base64 encoded string of "client_id:client_secret"
- Adding client_id and client_secret as GET/POST parameters
GET/POST https://somecompany.tehden.com/oauth/oaclient/token
Parameters
- grant_type: Tehden supports "authorization_code" which is used to verify user's approval
- code: the authorization code
- redirect_uri: must be identical with the redirect_uri given in the "Authorization code: Asking for authorization" part
- + client credentials (client_id and client_secret) if authenticating using GET/POST parameters
Result
JSON object with the following fields:
- access_token: access token used to access the API
- expires_in: time in seconds after which the access token expires
- token_type: "Bearer" supported by Tehden
- scope: list of scopes allowed, string delimited by spaces
- refresh_token: a token that can be used to get a new access token after it expires
After the response the authorization code is unusable.
Making API calls
GET/POST https://somecompany.tehden.com/api/module/method
where "module" can be e.g. company, customer and "method" is the function name.
Authorization header "Authorization: Bearer HASH_DIGEST" where HASH_DIGEST is a base64 encoded string of the access token.
API version must be defined either as a GET parameter (e.g. "version=1") or as an Accept header (e.g. "Accept: application/vnd.tehden.api-v1+json").
Language code must be set either as a GET parameter (e.g. "language=fi") or as an Accept-Language header (e.g. "Accept-Language: fi"). Valid values at the moment are "fi" and "en".
Errors
Possible error codes
- Bad request 400: Bad syntax or something missing
- Too many requests 429: Too many requests
- Internal error 500: Server side problems
- Not implemented 501: Resource not implemented
Example
The following example tries to do everything the easiest way possible. We will only use the GET method here to keep things simple. Normally you should always use the POST method.
After the application has been registered to Tehden, you will have a client id (e.g. "MyApiClient") and a client secret (e.g. "MySecret"). The application also has to have a redirect URI (e.g. "https://www.example.com/apicallback") where the client browser will be redirected after the user allows the application to access Tehden.
Let's start by authorizing the application "MyApiClient" to use Tehden as the current user in company "Some Company". You need to be logged in to a company as a Tehden user in order for this to work.
GET https://somecompany.tehden.com/oauth/oauser/authorize?client_id=MyApiClient&response_type=code
Once you allow access you are redirected to the redirect uri which was defined during the client application registration. In this example the redirect looks like this
The code is the authorization code which will be used to get the access token.
We get the following response in JSON.
{"access_token":"1v3da014885cad15ca57b506112a51771b1ac870b9dbc85947a02e483966",
"expires_in":3600,
"token_type":"bearer",
"scope":"",
"refresh_token":"1vb3c273bad35e9cfc6dcc97f02631cca7bbcd2f25fcb19b321a2c855d84"}
From now on we can make API calls using the access_token. In this example it will expire after an hour. The API will also respond by giving an "invalid_grant" error if you try to use an expired access token. You can get a new access token using the refresh_token.
{"access_token":"1v98951702e28f9e4795c31c949131da627049221000315df8079ecefecc",
"expires_in":3600,
"token_type":"bearer",
"scope":"",
"refresh_token":"1vf41d4aaf2dddf85c5fe5fdc27f599da48374fa96b5d9eb729ca2183e11"}
An example API call to get all product groups:
GET https://somecompany.tehden.com/api/product/getProductGroups?version=1
Remember to add the Authorization header. In this case it will be (using the latest access token encoded in base64, everything written on one line):
Authorization: Bearer MXY5ODk1MTcwMmUyOGY5ZTQ3OTVjMzFjOTQ5MTMxZGE2MjcwNDkyMjEwMDAzMTVkZjgwNzllY2VmZWNj
Same request in curl
curl \
-H "Accept: application/vnd.tehden.api-v1+json" \
-H "Accept-Language: fi" \
-H "Authorization: Bearer MXY5ODk1MTcwMmUyOGY5ZTQ3OTVjMzFjOTQ5MTMxZGE2MjcwNDkyMjEwMDAzMTVkZjgwNzllY2VmZWNj" \
https://somecompany.tehden.com/api/product/getProductGroups
Minimal PHP example
<?php
header('Content-Type: text/plain');
// Fill in the access token
$accessToken = '<valid_access_token_here>';
// Change the product_ids
$post = array(
'product_ids' => array(
'8319e522-8a6e-4cdf-a605-075e0c4a8d18',
'db86f94b-de3b-49ab-8bf3-8e3b14bc6b67'
)
);
$headers = array(
'Accept: application/vnd.tehden.api-v1+json',
'Accept-Language: fi',
'Authorization: Bearer ' . base64_encode($accessToken)
);
$ch = curl_init('https://somecompany.tehden.com/api/product/getProducts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post));
$response = curl_exec($ch);
curl_close($ch);
$response = json_decode($response);
var_dump($response);
Kommentit
0 kommenttia
Kommentointi on poistettu käytöstä.