SaaShop logo
API docs by Redocly

SaaShop Marketplace Seller API (1.0)

Download OpenAPI specification:Download

SaaShop Developer

Introduction

SaaShop Seller API is created for SaaS-companies that have joined the SaaShop marketplace as Sellers. The Sellers have their SaaS-product listed in the SaaShop Marketplace and available to be purchased by other companies or organizations.

The Seller is able to use the Seller API to get data of purchase events and provisioning actions required for the SaaS-product. This documentation describes how to use the SaaShop Marketplace Seller API.

If you have any questions, comments or feedback regarding the Seller API, please contact us at developer@saashop.com.

Concepts

API includes the following key concepts

  • MarketplaceEvent. Marketplace will provide Seller events, such as new orders. Sellers are also able to post events to the marketplace, such as provisioning status updates.
  • Order. The customer and product details are included in the order. Orders can have one or more order lines. Seller needs to provision the service described in the order. Order contents follow UBL 2.1 standard (Universal Business Language).
  • Service. When Buyer purchases a product the marketplace creates a service for that Buyer. Service is an instance of a purchased product that is invoiced according to the product configuration.
  • Seller supplier party. Seller provides the SaaS services to customers. Seller details are included in the order.
  • Buyer customer party. Buyer can evaluate and purchase SaaS services from the seller. Buyer details are included in the order.

Setup

Product Catalog

The seller needs to have products created, configured and published to the Marketplace. Seller has credentials to Seller Console where they have the ability to manage product catalog, services and buyers. If you are a Seller who needs to finalize product setup reach out to your contact person or partners@saashop.com for guidance.

Create API Clients

You need an API key and secret to be able to authenticate to the Seller API. These are required and managed through the Seller Console. You can have multiple key/secret pairs if needed. There is no development environment available at this moment for the Seller API so all the authentication is to the production environment.

  • Login to Seller Console and navigate to ../integrations/saashop-clients SaaShop client

  • Click Add and fill name for API Client.
    SaaShop client

  • After a few seconds you will get Client Id and Client Secret which are used to create a token.
    SaaShop client
    Save Client Id and Client Secret in a safe place. The Client Secret is only shown in the creation phase.

Check API status

This ping endpoint can be used to check the status of the API without any authentication headers.

curl --location --request GET 'https://api.saashop.com/base/v1/ping'

Status 200 OK

{
  "access": "public",
  "date": "2022-04-29-11:58:13",
  "stage": "prod",
  "version": "v1"
}

Authentication

Send ClientId:ClientSecret in base64 format in the Authorization header in order to create a token. Also provide your own X-Request-ID. Then you can use the token to use other API endpoints.

curl --location --request POST 'https://api.saashop.com/auth/v1/tokens' \
--header 'X-Request-ID: $XRequestID' \
--header 'Authorization: Basic {base64($ClientId:$ClientSecret)}'

Notes

  • Replace $XRequestID with random UUID version 4.
  • Replace $ClientId and $ClientSecret with your Client Id and Secret.

In response you will get jwt accessToken. This token is valid for 30 minutes.

Status: 201 Created

{
    "accessToken": "eyJraWQiOiJ2c0VtUFJuS0JNd3paanh3V08wZmhocHlYTXMrcm1HVGdqTmJVd1ZDSGR3PSIsImFsZyI6IlJTMjU2In0.
    zOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xXzN0c0xiUUJNNCIsImV4cCI6MTY1MTIzNjI3NCw
    iaWF0Ijoc0LCJ2ZXJzaW9uIjoyLCJqdGkiOiI0NTgyMGI3My1mYTEyLTQxNmItYTIxMi04M2FmZTQ4NTQxMmMiLCJjbGllbnRfaWQiOiI1dT
    ZoaW5lMmZqZjhhb2NoMnY0NGNyaDFrNiJ9.9exGs9Wu8Yu98c_ns-iNDJBgBK_fbWPeoluIJeoJELI60k69z2awoPDK21xy6k6YV6A",
    "tokenType": "Bearer"
}

MarketplaceEvent

MarketplaceEvent provides status updates about order provisioning.

Retrieve new marketplaceEvents

MarketplaceEvents includes links to orders. Order details can be fetched based on order identifier.

Authorizations:
bearerAuth
query Parameters
offset
integer
Default: 0

The number of items to skip before starting to collect the result set

limit
integer
Default: 50

The numbers of items to return

header Parameters
X-Request-ID
required
string <uuid>
Example: cf2ebcc1-45db-4833-9a52-35cd0c537a5e

Unique identifier of the call, as determined by the initiating party.

Responses

Response samples

Content type
application/json
{
  • "hasMore": false,
  • "marketplaceEvents": [
    ]
}

Send a MarketplaceEvent

You can send a MarketplaceEvent. MarketplaceEvent is sent to inform the progress of the service provisioning.

Authorizations:
bearerAuth
header Parameters
X-Request-ID
required
string <uuid>
Example: cf2ebcc1-45db-4833-9a52-35cd0c537a5e

Unique identifier of the call, as determined by the initiating party.

Request Body schema: application/json

MarketplaceEvent describing provisioning status.

eventId
string

Unique event identifier in UUID format.

sellerId
integer

An identifier for seller who is owner of MarketplaceEvent.

eventTypeCode
required
string
Enum: "ServicePurchased" "Evaluation" "Trial" "UpgradeToTrial" "UpgradeToPurchase"

Event type. Currently supported types: ServicePurchased

statusCode
required
string
Enum: "ProvisioningStarted" "ProvisioningInProgress" "ProvisioningCompleted" "ProvisioningFailed"

Status code to indicate the provisioning status.

eventTime
string

Time of the event.

description
required
string

Description of the event.

detailedDescription
string

Detailed description of the event.

seenTime
string

Time of the event seen.

Array of objects

An array of additional details as key-value pair.

Responses

Request samples

Content type
application/json
{
  • "eventTypeCode": "ServicePurchased",
  • "statusCode": "ProvisioningCompleted",
  • "description": "Provisioning has been completed",
  • "detailedDescription": "Provisioning has been completed 2019-06-25 13:02 GMT",
  • "additionalProperties": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": "BadRequest",
  • "description": "Invalid request parameters.",
  • "detailedDescription": "Mandatory request parameter is missing"
}

Retrieve all marketplaceEvents

MarketplaceEvents includes links to orders. Order details can be fetched based on order identifier.

Authorizations:
bearerAuth
query Parameters
offset
integer
Default: 0

The number of items to skip before starting to collect the result set

limit
integer
Default: 50

The numbers of items to return

header Parameters
X-Request-ID
required
string <uuid>
Example: cf2ebcc1-45db-4833-9a52-35cd0c537a5e

Unique identifier of the call, as determined by the initiating party.

Responses

Response samples

Content type
application/json
{
  • "hasMore": false,
  • "marketplaceEvents": [
    ]
}

Order

Order includes details about customer and product.

Retrieve orders

List of Orders.

Authorizations:
bearerAuth
query Parameters
offset
integer
Default: 0

The number of items to skip before starting to collect the result set

limit
integer
Default: 50

The numbers of items to return

header Parameters
X-Request-ID
required
string <uuid>
Example: cf2ebcc1-45db-4833-9a52-35cd0c537a5e

Unique identifier of the call, as determined by the initiating party.

Responses

Response samples

Content type
application/json
{
  • "hasMore": false,
  • "orders": [
    ]
}

Retrieve an order

Order includes details about the buyer and the purchased product. Each order is identified by an identifier orderId.

Authorizations:
bearerAuth
path Parameters
orderId
required
string <uuid>
Example: 21bb0ed5-7d89-45d5-a85b-3aa3d058b4ed

Unique order identifier in UUID format.

header Parameters
X-Request-ID
required
string <uuid>
Example: cf2ebcc1-45db-4833-9a52-35cd0c537a5e

Unique identifier of the call, as determined by the initiating party.

Responses

Response samples

Content type
application/json
{
  • "orderId": "4b7d7cbd-c5f6-4698-8e34-b1a3210cee43",
  • "issueTime": "2022-03-29 09:47:51.58881+00",
  • "orderTypeCode": "Purchase",
  • "note": "New purchase order for SaaS service",
  • "documentCurrencyCode": "USD",
  • "validityPeriod": {
    },
  • "buyerCustomerParty": {
    },
  • "sellerSupplierParty": {
    },
  • "anticipatedMonetaryTotal": {
    },
  • "documentLines": [
    ]
}

License

License includes details about license.

Retrieve licenses

License includes links to order. Order details can be fetched based on order identifier.

Authorizations:
bearerAuth
query Parameters
orderId
string <uuid>
Example: orderId=21bb0ed5-7d89-45d5-a85b-3aa3d058b4ed

Unique identifier in uuid format.

header Parameters
X-Request-ID
required
string <uuid>
Example: cf2ebcc1-45db-4833-9a52-35cd0c537a5e

Unique identifier of the call, as determined by the initiating party.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Retrieve a license

License includes details about the buyer and the purchased product. Each license is identified by an identifier licenseId.

Authorizations:
bearerAuth
path Parameters
licenseId
required
string <uuid>
Example: 21bb0ed5-7d89-45d5-a85b-3aa3d058b4ed

Unique license identifier in UUID format.

header Parameters
X-Request-ID
required
string <uuid>
Example: cf2ebcc1-45db-4833-9a52-35cd0c537a5e

Unique identifier of the call, as determined by the initiating party.

Responses

Response samples

Content type
application/json
{
  • "licenseId": "f957cf5e-14b6-40a5-8598-847334085658",
  • "electronicMail": "TEST-USER-1@pilvi.com",
  • "additionalProperties": [
    ]
}

MarketplaceEvents Model

hasMore
required
boolean

Indicates whether there are more items to fetch.

required
Array of objects (MarketplaceEvent)

An array of marketplaceEvents.

{
  • "hasMore": false,
  • "marketplaceEvents": [
    ]
}

Order Model

orderId
string <uuid>

Unique order identifier in UUID format.

issueTime
string

The time, which this document was issued. Time is in ISO 8601 format with UTC time zone.

orderTypeCode
required
string
Enum: "Purchase" "Evaluation" "Trial"

Order type. Currently supported types: Purchase

note
string

Free-form text pertinent to this document, conveying information that is not contained explicitly in other structures.

documentCurrencyCode
required
string (CurrencyCode) [A-Z]{3}

Currency code is ISO 4217 Alpha 3 currency code.

object (TimePeriod)

Time period with start and end date.

required
object (BuyerCustomerParty)

Buyer customer party.

required
object (SellerSupplierParty)

Seller supplier party.

object (MonetaryAmount)

The monetary amount of the transaction.

required
Array of objects (DocumentLine)

An array of document lines.

{
  • "orderId": "21bb0ed5-7d89-45d5-a85b-3aa3d058b4ed",
  • "issueTime": "2022-03-29 09:47:51.58881+00",
  • "orderTypeCode": "Purchase",
  • "note": "New purchase order for SaaS service",
  • "documentCurrencyCode": "USD",
  • "validityPeriod": {
    },
  • "buyerCustomerParty": {
    },
  • "sellerSupplierParty": {
    },
  • "anticipatedMonetaryTotal": {
    },
  • "documentLines": [
    ]
}

Licenses Model

hasMore
required
boolean

Indicates whether there are more items to fetch.

required
Array of objects (License)

An array of Licenses.

{
  • "hasMore": false,
  • "licenses": [
    ]
}