SaaShop Marketplace API (1.0)

Download OpenAPI specification:Download

Introduction

Marketplace will provide a new customer to your product when a company or organization would like to buy a service from your offering. An order describes the lead and its action which you need to provision to your system.

Contact

If you have any questions, comments or feedback regarding our APIs, please contact us at developer@saashop.com.

Concepts

API includes the following key concepts:

  • Marketplace event: Marketplace will provide you events about new leads, orders and subscription changes. The marketplace event includes a reference to the order.
  • Order: The customer and product details are included in the order. Order can have one or more order lines. Seller needs to provision the service described in the order.
  • Seller supplier party: Seller provides the SaaS services to customer. 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.

Order contents follow UBL 2.1 standard (Universal Business Language).

The following elements are used in the API:

  • UUID: Universally unique identifier that is used to identify entities. For example, each request must have a unique identifier.

Authentication

bearerAuth

SaaShop API is authenticated with Bearer tokens. This is an application-only authentication method. Before calling SaaShop API endpoints, you first need to request a token with POST /tokens.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Order

Order includes details about customer and product.

Retrieve an order

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

Authorizations:
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

200

OK. Response contains an order.

400

Bad request. The server cannot or will not process the request due to invalid request syntax or content.

401

Unauthorized. Authentication is required and has failed or has not yet been provided.

404

Not found. The requested resource could not be found.

429

Too many requests. The rate limit for the caller has been exceeded.

5XX

Technical error. Unexpected technical error.

get /orders/{orderId}

Sandbox for testing

https://test-api.saashop.com/v1/orders/{orderId}

Production

https://api.saashop.com/v1/orders/{orderId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "orderId": "4b7d7cbd-c5f6-4698-8e34-b1a3210cee43",
  • "issueDate": "2019-06-21",
  • "issueTime": "09:32:12+02:00",
  • "orderTypeCode": "Purchase",
  • "note": "New purchase order for SaaS service",
  • "documentCurrencyCode": "USD",
  • "validityPeriod":
    {
    },
  • "buyerCustomerParty":
    {
    },
  • "sellerSupplierParty":
    {
    },
  • "anticipatedMonetaryTotal":
    {
    },
  • "documentLines":
    [
    ]
}

MarketplaceEvent

Marketplace event provides status updates about order provisioning.

Retrieve marketplace events

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

Authorizations:
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

200

OK. Response contains an array of marketplace events.

400

Bad request. The server cannot or will not process the request due to invalid request syntax or content.

401

Unauthorized. Authentication is required and has failed or has not yet been provided.

404

Not found. The requested resource could not be found.

429

Too many requests. The rate limit for the caller has been exceeded.

5XX

Technical error. Unexpected technical error.

get /marketplaceEvents

Sandbox for testing

https://test-api.saashop.com/v1/marketplaceEvents

Production

https://api.saashop.com/v1/marketplaceEvents

Response samples

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

Send a marketplace event

You can send a marketplace event. Marketplace event is sent to inform the progress of the service provisioning.

Authorizations:
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

Marketplace event describing provisioning status.

eventId
required
string

Unique event identifier in UUID format.

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
integer

Time of the event. The format is Epoch Unix timestamp in seconds.

description
required
string

Description of the event.

detailedDescription
string

Detailed description of the event.

additionalProperties
Array of objects

An array of additional details as key-value pair.

Responses

201

OK. Event was successfully created.

400

Bad request. The server cannot or will not process the request due to invalid request syntax or content.

401

Unauthorized. Authentication is required and has failed or has not yet been provided.

404

Not found. The requested resource could not be found.

415

Unsupported media type. The payload includes an unsupported format.

429

Too many requests. The rate limit for the caller has been exceeded.

5XX

Technical error. Unexpected technical error.

post /marketplaceEvents

Sandbox for testing

https://test-api.saashop.com/v1/marketplaceEvents

Production

https://api.saashop.com/v1/marketplaceEvents

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "eventId": "6ed6ca4f-f64a-4fef-a0fe-6d012eb269c3",
  • "eventTypeCode": "ServicePurchased",
  • "statusCode": "ProvisioningCompleted",
  • "eventTime": 1561492900,
  • "description": "Provisioning has been completed",
  • "detailedDescription": "Provisioning has been completed 2019-06-25 13:02 GMT",
  • "additionalProperties":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "errorCode": "InvalidRequest",
  • "description": "Invalid request parameters",
  • "detailedDescription": "Mandatory request parameter is missing"
}

Order Model

orderId
required
string <uuid>

Unique order identifier in UUID format.

issueDate
required
string

The date, assigned by the sender, on which this order was issued. Date is is ISO 8601 format as in YYYY-MM-DD.

issueTime
string

The time, assigned by the sender, on 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.

validityPeriod
required
object (TimePeriod)

Time period with start and end date.

buyerCustomerParty
required
object (BuyerCustomerParty)

Buyer customer party.

sellerSupplierParty
required
object (SellerSupplierParty)

Seller supplier party.

anticipatedMonetaryTotal
object (MonetaryAmount)

The monetary amount of the transaction.

documentLines
required
Array of objects (DocumentLine)

An array of document lines.

Copy
Expand all Collapse all
{
  • "orderId": "21bb0ed5-7d89-45d5-a85b-3aa3d058b4ed",
  • "issueDate": "2019-02-25",
  • "issueTime": "09:30Z",
  • "orderTypeCode": "Purchase",
  • "note": "New purchase order for SaaS service",
  • "documentCurrencyCode": "USD",
  • "validityPeriod":
    {
    },
  • "buyerCustomerParty":
    {
    },
  • "sellerSupplierParty":
    {
    },
  • "anticipatedMonetaryTotal":
    {
    },
  • "documentLines":
    [
    ]
}

MarketplaceEvents Model

hasMore
required
boolean

Indicates whether there are more items to fetch.

marketplaceEvents
required
Array of objects

An array of marketplace events.

Copy
Expand all Collapse all
{
  • "hasMore": false,
  • "marketplaceEvents":
    [
    ]
}