Business - Articles

The Admin interface handles web service calls from the Admin web gui. The base url for this is at:

/api/business-admin

A JSON file with OpenAPI data about all business-related admin APIs can be downloaded here.

Get Article

Gets details about a specific article:

GET /v1/articles/{id}

Gets details about a specific article

Parameters

  • id (integer) – The article to retrieve data for

Status Codes
DELETE /v1/articles/{id}

Marks an article as deleted

Parameters

  • id (integer) – The article to delete

Status Codes
id: Article ID (int)

Returns a plain Json negative message if there was a problem retrieving the data or a Json positive response with the requested details:

{
  "CreatedDate": "2020-09-14T11:46:37Z",                                                            // DateTime
  "BalanceUnit": 1,                                                                                 // Int
  "ExtCommunityFilter": [ "8108adee-4cc9-4d59-bedf-7a69186a41d1", ... ],                            // Guid Array (nullable)
  "SelectedCommunities": "Community 1 name,Community 2 name,...",                                   // String (nullable)
  "Name": "ART01",                                                                                  // String
  "Labels": "{\"en\":\"Article 01\",\"it\":\"Articolo 01\"}",                                       // String
  "DescriptionLabels": "{\"en\":\"Article 01 Description\",\"it\":\"Descrizione Articolo 01\"}",    // String (nullable)
  "WalletAmount": 60,                                                                               // Decimal
  "Price": 15,                                                                                      // Decimal
  "TokenCost": 10,                                                                                  // TokenCost (nullable if BalanceUnit is Tokens)
  "IsSingleToken": true,                                                                            // Boolean
  "ID": 1                                                                                           // Int
}

Value of the BalanceUnit property can be one of the BalanceUnit enumeration.

The properties Labels and DescriptionLabels contain a stringified Json containing pairs “language code”:”localized value”

Get Article list

Gets a list of all articles (it’s a Paged List APIs, as explained in the introduction):

GET /v1/articles/list

Gets a list of all articles

Status Codes

Returns a list of all articles:

[
  {
  "CreatedDate": "2020-09-14T11:46:37Z",                                                            // DateTime
  "BalanceUnit": 1,                                                                                 // Int
  "ExtCommunityFilter": [ "8108adee-4cc9-4d59-bedf-7a69186a41d1", ... ],                            // Guid Array (nullable)
  "SelectedCommunities": "Community 1 name,Community 2 name,...",                                   // String (nullable)
  "Name": "ART01",                                                                                  // String
  "Labels": "{\"en\":\"Article 01\",\"it\":\"Articolo 01\"}",                                       // String
  "DescriptionLabels": "{\"en\":\"Article 01 Description\",\"it\":\"Descrizione Articolo 01\"}",    // String (nullable)
  "WalletAmount": 60,                                                                               // Decimal
  "Price": 15,                                                                                      // Decimal
  "ID": 1                                                                                           // Int
  "TokenCost": 10,                                                                                  // TokenCost (nullable if BalanceUnit is Tokens)
  "IsSingleToken": true                                                                             // Boolean
  },
  ...
]

Value of the BalanceUnit property can be one of the BalanceUnit enumeration.

The properties Labels and DescriptionLabels contain a stringified Json containing pairs “language code”:”localized value”

Add new or edit article

Persists edits about a new or existing article:

POST /v1/articles

Persists edits about a new or existing article

Status Codes

The request body is:

{
  ID: 123,                                                    // Int
  Name: "pitm10",                                             // String
  Labels: "{\"en\":\"60 Minutes Package\",...}",              // String
  DescriptionLabels: "{\"en\":\"60 Minutes Package\",...}",   // String
  BalanceUnit: 3,                                             // Int
  WalletAmount: 1.23,                                        // Decimal
  Price: 1.23,                                                // Decimal
  "TokenCost": 10,                                            // TokenCost (nullable if BalanceUnit is Tokens)
  ExtCommunityFilter: [ Guid Array ]                          // Guid Array
}

If ID (article ID) is not provided or set to 0, then the request will create a new record.

Value of the field BalanceUnit must be one of the BalanceUnit enumeration; it does not accept the Currency value.

The fields Labels and DescriptionLabels contain a stringified Json containing pairs “language code”:”localized value”

A plain Json positive response will be returned if the record was sucessfully added or updated.

Possible errors are:

err_AmountInvalid

The value of WalletAmount is not in a valid format (a decimal positive value)

err_PriceInvalid

The value of Price or TokenCost is not in a valid format (a decimal or integer positive value)

err_InvalidElement

One of the fields BalanceUnit, Price, WalletAmount, Name or Labels are empty or null, or no ExtCommunityFilter has been provided and the user is not a SuperAdmin, BalanceUnit has been set as Currency or a TokenCost has been provided for a token package

err_Duplicatedelement

The provided BalanceUnit and WalletAmount maps to an already existing package

err_MaxArticleAmountReached

The provided WalletAmount is greater than the allowed value of items per package, as specified in the environment variables MAX_TOKENS_PER_ARTICLE, MAX_MINUTES_PER_ARTICLE and MAX_DISTANCE_PER_ARTICLE

Delete article

Marks an article as deleted:

GET /v1/articles/{id}

Gets details about a specific article

Parameters

  • id (integer) – The article to retrieve data for

Status Codes
DELETE /v1/articles/{id}

Marks an article as deleted

Parameters

  • id (integer) – The article to delete

Status Codes
id: Article ID (int)

Returns a plain Json positive response if the article was successfully marked as deleted.

Possible errors are a plain error if the article is the single token pakage, or one of the following error codes:

err_ElementDoesNotExist

There is no article corresponding to the ID specified in the requested

err_ElementAlreadyDeleted

The specified article has already been marked as deleted