diff options
Diffstat (limited to 'doc/integration/partner_marketplace.md')
| -rw-r--r-- | doc/integration/partner_marketplace.md | 116 |
1 files changed, 106 insertions, 10 deletions
diff --git a/doc/integration/partner_marketplace.md b/doc/integration/partner_marketplace.md index a15457b5b0c..76988af99b2 100644 --- a/doc/integration/partner_marketplace.md +++ b/doc/integration/partner_marketplace.md @@ -1,13 +1,13 @@ --- stage: Fulfillment -group: Commerce Integrations +group: Provision info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Marketplace partner integration guide +# Marketplace partners GitLab supports automation for selected distribution marketplaces to process sales of GitLab products to authorized -channel partners. Marketplace partners can use the GitLab Marketplace APIs to integrate their systems with GitLab to +channel partners. Marketplace partners can use the GitLab Marketplace APIs to integrate their systems with GitLab to sell GitLab subscriptions on their site. This document's target audience is third-party developers for Marketplace partners. @@ -48,17 +48,113 @@ sequenceDiagram Customers Portal ->> Marketplace partner system: Success response with order status ``` -## Prerequisites +## Marketplace API Specification + +OpenAPI specs for the Marketplace APIs are available at [Marketplace interactive API documentation](https://customers.staging.gitlab.com/openapi_docs/marketplace). + +## Access the Marketplace API + +To access the Marketplace API you need to: + +- Request access from GitLab. +- Retrieve an OAuth access token. + +Marketplace API endpoints are secured with [OAuth 2.0](https://oauth.net/2/). OAuth is an authorization framework +that grants 3rd party or client applications, like a Marketplace partner application, limited access to resources on an +HTTP service, like the Customers Portal. + +OAuth 2.0 uses _grant types_ (or _flows_) that describe how a client application gets authorization in +the form of an _access token_. An access token is a string that the client application uses to make authorized requests to +the resource server. + +The Marketplace API uses the `client_credentials` grant type. The client application uses the access token to access its +own resources, instead of accessing resources on behalf of a user. + +### Step 1: Request access -Before a marketplace partner client can use the Marketplace API, GitLab must set up the following configurations for the client: +Before you can use the Marketplace API, you must contact your Marketplace partner Manager or email [`partnerorderops`](mailto:partnerorderops@gitlab.com) +to request access. After you request access, GitLab configures the following accounts and credentials for you: -1. Client credential. Marketplace APIs are secured with OAuth 2.0. A client credential is required to get the OAuth token. +1. Client credentials. Marketplace APIs are secured with OAuth 2.0. The client credentials include the client ID and client secret + that you need to retrieve the OAuth access token. 1. Invoice owner account in Zuora system. Required for invoice processing. 1. Distributor account in Salesforce system. -1. Trading partner account in Salesforce system. +1. Trading partner account in Salesforce system. GitLab adds the Trading Partner ID to a permitted list to pass the validations. -Interested GitLab Partners should contact their GitLab Partner Manager or email [`partnerorderops`](mailto:partnerorderops@gitlab.com). +### Step 2: Retrieve an access token -## Marketplace API Specification +To retrieve an access token, + +- Make a POST request to the [`/oauth/token`](https://customers.staging.gitlab.com/openapi_docs/marketplace#/marketplace/post_oauth_token) endpoint with the following required parameters: + +| Parameter | Type | Required |Description | +|-----------------|--------|----------|------------------------------------------------------------------------------------------------------------------------------------| +| `client_id` | string | yes |ID of your client application record on the Customers Portal. Received from GitLab. | +| `client_secret` | string | yes |Secret of your client application record on the Customers Portal. Received from GitLab. | +| `grant_type` | string | yes |Specifies the type of credential flow. Use `client_credentials`. | +| `scope` | string | yes |Specifies the level of access. Use `marketplace.order:read` for read-only access. Use `marketplace.order:create` for create access. | + +If the request is successful, the response body includes the access token that you can use in subsequent requests. For an example of a successful +response, see the [Marketplace interactive API documentation](https://customers.staging.gitlab.com/openapi_docs/marketplace) + +If the request is unsuccessful, the response body includes an error and error description. The errors can be: + +| Status | Description | +|--------|----------------------------------------------------------------------------------------------------------------------------------------------| +| 400 | Invalid scope. Ensure the `scope` is `marketplace.order:read` or `marketplace.order:create`. | +| 401 | Invalid client. Ensure that there are no typos or extra spaces on the client specific credentials. Incorrect `client_id` or `client_secret` | + +### Step 3: Use the access token + +To use the access token from a client application: + +1. Set the `Authorization` header of the request to `Bearer <your_access_token>`. +1. Set parameters or data needed for the endpoint and send the request. + +Example request: + +```shell +curl \ + --url "https://customers.staging.gitlab.com/api/v1/marketplace/subscriptions/:external_subscription_id" \ + --header "Authorization: Bearer NHb_VhZhPOnBTSNfBSzmCmt28lLDWb2xtwr_c3DL148" +``` + +## Create a new customer subscription + +To create a new customer subscription from a Marketplace partner client application, + +- Make an authorized POST request to the +[`/api/v1/marketplace/subscriptions`](https://customers.staging.gitlab.com/openapi_docs/marketplace#/marketplace/post_api_v1_marketplace_subscriptions) +endpoint in the Customers Portal with the following parameters in JSON format: + +| Parameter | Type | Required | Description | +|--------------------------|--------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| `externalSubscriptionId` | string | yes | ID of the subscription on the Marketplace partner system. | +| `tradingPartnerId` | string | yes | ID of the Trading Partner account in Salesforce. Received from GitLab. | +| `customer` | object | yes | Information about the customer. Must include company name. Contact must include `firstName`, `lastName` and `email`. Address must include `country`. | +| `orderLines` | array | yes | Specifies the product purchased. Must include `quantity` and `productId`. | + +If the request is successful, the response body includes the newly created subscription number. For an example of a full request body, +see the [Marketplace interactive API documentation](https://customers.staging.gitlab.com/openapi_docs/marketplace). + +If the subscription creation is unsuccessful, the response body includes an error message with details about the cause of the error. + +## Check the status of a subscription + +To get the status of a given subscription, + +- Make an authorized GET request to the +[`/api/v1/marketplace/subscriptions/{external_subscription_id}`](https://customers.staging.gitlab.com/openapi_docs/marketplace#/marketplace/get_api_v1_marketplace_subscriptions__external_subscription_id_) +endpoint in the Customers Portal. + +The request must include the Marketplace partner system ID of the subscription to fetch the status for. + +If the request is successful, the response body contains the status of the subscription provision. The status can be: + +- Creating +- Created +- Failed +- Provisioned -OpenAPI specs for the Marketplace APIs are available upon request. The specs will be made public before the end of Q1 2023. +If the subscription cannot be found using the passed `external_subscription_id`, the response has +a 404 Not Found status. |