Usage

Connection model

Configuration

The api_keyfollowing is provided and configured:

export API_KEY=<AuthToken>
export API_HOST=<base_url>

Instructions for using the commands exportand curlare provided when running in terminal on Linux or Mac operating systems. In case you use another environment, please replace them with equivalent operations.

API Structure

Request

A typical API call looks like this:

curl --location '$BASE_URL.Misc/CurrentAccount \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{}'

All requests use HTTPS protocol, POST method and pass values ​​in body using data format application/json. Required headers are Content-Typeand Authorization.

Response

The response uses the data format application/jsonset in the header Content-Type. If the request is successful, the HTTP status code is 200. If the request fails, the HTTP status code can be . 4xxor . 5xxwith a structure similar to the following:

{
  "code": "invalid_argument",
  "msg": "..."
}

Connect shop account

The connection is done according to the redirect model. The partner needs to prepare a URL to receive the redirect after the shop is successfully created:

export REDIRECT_URL="https://example.com/redirect?token=87209412&shop_id=12414"

Process of connecting to the shop:

1. Send request to .Shop/AuthorizeShop.

2. Redirect to the url provided by auth_url, wait for the shop to verify the account and receive redirect from eTelecom.

3. Resend request with shop_idreceipt.

4. Save shop_idand auth_tokenuse in other APIs

curl $BASE_URL.Shop/AuthorizeShop \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
        "email": "<email_address>",
        "phone": "<phone_number>",
        "name": "<name>",
        "redirect_url": "'$REDIRECT_URL'"
    }'

Request body structure:

Parameters	Data type	Describe
email required	string	The email address of the shop account to be created.
phone required	string	The phone of the shop account to be created.
name required	string	The name address of the shop account to be created.
redirect_url required	string	Redirect after shop successfully logged in

200 OK type=shop_request

{
  "code": "ok",
  "msg": "",
  "type": "shop_request",
  "auth_token": "request:Ut8zhsaQp_kwKi2u2gEch_9R3yiQvpFUnB5mE_MRfks",
  "expires_in": 900,
  "auth_url": "https://partner-auth.etelecom.vn/login?token=request:Ut8zhsaQp_kwKi2u2gEch_9R3yiQvpFUnB5mE_MRfks"
}

This result means that the shop will be asked to log in to verify the account. The returned result will provide a url address with the field auth_urlfor the partner to redirect the shop to and verify the account.

After performing account authentication, eTelecom will redirect to the partner's provided url address with shop_idthe following structure: $REDIRECT_URL?token=<token>&shop_id=<shop_id>.

Retrieve the shop_key information

The shop_id information is returned in the redirect_url when the partner successfully creates a shop during the shop account connection process:

# Use shop_id (required)
curl $BASE_URL.Shop/AuthorizeShop \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
        "shop_id": "<shop id provided by eTelecom>",
        "redirect_url": "'$REDIRECT_URL'"
    }'

Partners still need to provide redirect_urlbecause there may be situations where the shop needs to log in again. This redirect_urlwill be used for eTelecom to redirect after the shop successfully logs in.

Request body structure:

Parameters	Data type	Describe
shop_id required	string	The ID of the shop.
redirect_url required	string	Redirect after shop successfully logged in

200 OKtype=shop_key

{
  "code": "ok",
  "msg": "",
  "type": "shop_key",
  "auth_token": "shop1052570182707778180:KgGTCsQHSzfKBt8la63c7E6NRqqnD5RVRMrb0aJwa8jZCEbGCmJ7Q01aVwyZeGeR",
  "expires_in": -1
}

This result means that the partner can create a switchboard or send zns as a shop. Please save it auth_tokenwith your shop account to continue using it.

Note: It should be noted that even if the shop has been connected to eTelecom, the shop may still be asked to log in again. This situation occurs when the shop has unlinked the partner's account. At this time, the response will be available type=shop_requestand auth_urlreturned, the partner needs to redirect to this address for the shop to log in again.

Return data attribute structure:

Parameters	Data type	Describe
auth_token	string	Authorization code
auth_url	string	Authorization Path
code	string	State of success or failure
expires_in	int	Expiration time
meta	object	Properties if any
msg	string	API Description

Checkshop_key

To check that shop_keythe received information is correct, the partner can send a request to:

CurrentShop

POST$BASE_URL.Shop/CurrentShop

Body

application/json

ktEmpty (object)

Response

200

A successful response

Body

application/json

idstring (int64)

image_urlstring

namestring

typejjAccountType (enum)

unknownpartnershopaffiliatecarrieretop

websitestring

Request

JavaScriptCurlPython

const response = await fetch('$BASE_URL.Shop/CurrentShop', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
});
const data = await response.json();

Response

200

{
  "id": "text",
  "image_url": "text",
  "name": "text",
  "type": "unknown",
  "website": "text"
}

Request:

export API_KEY=<api_key>
curl $BASE_URL.Shop/CurrentShop \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $SHOP_KEY" \
    -d '{}'

Response:

{
    "id": "string",
    "image_url": "string",
    "name": "string",
    "type": "unknown",
    "website": "string"
}

Return data attribute structure:

Parameters	Data type	Describe
id	string	Account ID
name	string	Account Name
type	string	Account Type: Partner Shop

Common errors

400 Bad Request

{
  "code": "invalid_argument",
  "msg": "..."
}

Please double check the provided values.

401 Unauthorized

{
  "code": "unauthenticated",
  "msg": "..."
}

Please double check that the request includes the Authorization: <api_key>correct headers.

403 Forbidden

{
    "code": "permission_denied",
    "msg": "...",
    "meta": {
        "reason": 
    }
}

The shop has never logged intoeTelecom through the partner system. Please try again with a request that does not include shop_id.

Note : In case the shop has logged into eTelecom through the partner's system, then removed the link with the partner, the result is still 200 OKwith the request for the shop to log in and grant permission again. So the error permission_deniedonly occurs when shop_idthe information provided is incorrect.

404 Not Found

{
    "code": "bad_route",
    "msg": "unexpected Content-Type: \"\""
}

Please check the path and header again Content-Type: application/json.