Connectors

A Connector is a production-ready integration with Composable Commerce.

After a ConnectorStaged is published, a Connector is created containing all the information from the ConnectorStaged. These are production versions of your Connector that are available for clients to deploy.

Connectors are read-only. If you are a creator and want to make changes to your Connector, you should make the changes to the ConnectorStaged and then use the Publish update action.

Representations

Connector

ConnectorReference

ConnectorSearchPagedQueryResponse

Connector

`id` String	Unique identifier of the Connector.
`version` Int	Current version of the Connector.
`key` String	User-defined unique identifier of the Connector. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`name` String	Name of the Connector.
`description` String	Description of the Connector.
`integrationTypes` Array of IntegrationType	Integration types of the Connector. Can be used to filter search and query results.
`creator` Creator	Owner of the Connector.
`repository` Repository	GitHub repository details of the Connector.
`configurations` Array of ConnectorConfigurationApplication	Configurations needed by Connectors for hosting. Loaded as environment variables in the application.
`apiClient` ConnectorApiClient	Configuration for the API Client used for automatically generating API Client credentials.
`private` Boolean	If `true`, only Composable Commerce Projects specified in `privateProjects` can access the Connector.
`globalConfiguration` ConnectorGlobalConfiguration	Global configuration applied to all applications in the Deployment.
`supportedRegions` Array of Region	If provided, Connectors can only be deployed in these Regions. If not provided, Connectors can be deployed in any supported Region. For faster request processing, we recommend adding only the required Region.
`certified` Boolean	If `true`, the Connector is certified.
`documentationUrl` String	URL to the documentation of the Connector.

ConnectorReference

Reference to a Connector or ConnectorStaged. Either id or key is required.

`id` String	Unique identifier of the referenced Connector.
`version` Int	Version of the referenced Connector.
`key` String	User-defined unique identifier of the referenced Connector.
`staged` Boolean	If `true`, a previewable ConnectorStaged must be referenced in `id` or `key` instead of the published Connector. The `isPreviewable` field of the ConnectorStaged must be `true` to reference a previewable ConnectorStaged. Default: `false`

Example: json

{
  "key": "connector-key",
  "version": 1
}

ConnectorSearchPagedQueryResponse

PagedQueryResult with results containing an array of Connector.

`limit` Int	The maximum number of Connectors returned.
`offset` Int	The offset of the Connectors returned.
`count` Int	The number of Connectors returned.
`total` Int	The total number of Connectors matching the query.
`results` Array of Connector	Connectors matching the query.

Get Connector

Get Connector by ID

GET

https://connect.{region}.commercetools.com/connectors/{id}

OAuth 2.0 Scopes:

manage_project:{projectKey}manage_connectors:{projectKey}view_connectors:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`id` String	`id` of the Connector

Response:

200Connectorasapplication/json

Request Example:cURL

curl --get https://connect.{region}.commercetools.com/connectors/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Connectorjson

{
  "id": "5ab3edcd-9d23-4934-8f48-256805253119",
  "key": "connector-key",
  "version": 1,
  "name": "Connector's name",
  "description": "Connector's description",
  "integrationTypes": ["other"],
  "creator": {
    "title": "Mr",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "company": "commercetools",
    "noOfContributors": 200
  },
  "repository": {
    "url": "git@github.com:commercetools/connect-application-kit.git",
    "tag": "0.0.0"
  },
  "configurations": [
    {
      "applicationName": "app-1",
      "applicationType": "service",
      "standardConfiguration": [
        {
          "key": "CONFIG_KEY",
          "description": "config key description",
          "required": true,
          "default": null
        }
      ],
      "securedConfiguration": [
        {
          "key": "CONFIG_SECRET_KEY",
          "description": "config secret description",
          "required": true
        }
      ]
    }
  ],
  "private": false,
  "supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
  "certified": true
}

Get Connector by Key

GET

https://connect.{region}.commercetools.com/connectors/key={key}

OAuth 2.0 Scopes:

manage_project:{projectKey}manage_connectors:{projectKey}view_connectors:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`key` String	`key` of the Connector

Response:

200Connectorasapplication/json

Request Example:cURL

curl --get https://connect.{region}.commercetools.com/connectors/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Connectorjson

{
  "id": "5ab3edcd-9d23-4934-8f48-256805253119",
  "key": "connector-key",
  "version": 1,
  "name": "Connector's name",
  "description": "Connector's description",
  "integrationTypes": ["other"],
  "creator": {
    "title": "Mr",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "company": "commercetools",
    "noOfContributors": 200
  },
  "repository": {
    "url": "git@github.com:commercetools/connect-application-kit.git",
    "tag": "0.0.0"
  },
  "configurations": [
    {
      "applicationName": "app-1",
      "applicationType": "service",
      "standardConfiguration": [
        {
          "key": "CONFIG_KEY",
          "description": "config key description",
          "required": true,
          "default": null
        }
      ],
      "securedConfiguration": [
        {
          "key": "CONFIG_SECRET_KEY",
          "description": "config secret description",
          "required": true
        }
      ]
    }
  ],
  "private": false,
  "supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
  "certified": true
}

Search Connectors

GET

https://connect.{region}.commercetools.com/connectors/search

Retrieves all available Connectors.

OAuth 2.0 Scopes:

manage_project:{projectKey}manage_connectors:{projectKey}view_connectors:{projectKey}

Path parameters:

region

String

Region in which the Project is hosted.

Query parameters:

`text` String	The text to search for. For example, as supplied by a user through a search input field. Search results are based on matches found in the `name` and `description` fields of a Connector.
`limit` Int	Number of results requested. Default: `20`
`offset` Int	Number of elements skipped. Default: `0`
`sort` String	The parameter can be passed multiple times.
`private` Boolean	If `true` then only Connectors assigned to your Project are retrieved. If `false` then all available Connectors are retrieved.
`creator.company` String	Company name of a creator to search for.
`id` String	`id` of a Connector to search for. The parameter can be passed multiple times.
`key` String	`key` of a Connector to search for. The parameter can be passed multiple times.
`integrationTypes` IntegrationType	Only search for Connectors with a specified `integrationType`. The parameter can be passed multiple times.

Response:

200ConnectorSearchPagedQueryResponseasapplication/json

Request Example:cURL

curl --get https://connect.{region}.commercetools.com/connectors/search -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ConnectorSearchPagedQueryResponsejson

{
  "offset": 0,
  "limit": 20,
  "total": 1,
  "count": 1,
  "results": [
    {
      "id": "5ab3edcd-9d23-4934-8f48-256805253119",
      "key": "connector-key",
      "version": 1,
      "name": "Connector's name",
      "description": "Connector's description",
      "integrationTypes": ["other"],
      "creator": {
        "title": "Mr",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "company": "commercetools",
        "noOfContributors": 200
      },
      "repository": {
        "url": "git@github.com:commercetools/connect-application-kit.git",
        "tag": "0.0.0"
      },
      "configurations": [
        {
          "applicationName": "app-1",
          "applicationType": "service",
          "standardConfiguration": [
            {
              "key": "CONFIG_KEY",
              "description": "config key description",
              "required": true,
              "default": null
            }
          ],
          "securedConfiguration": [
            {
              "key": "CONFIG_SECRET_KEY",
              "description": "config secret description",
              "required": true
            }
          ]
        }
      ],
      "private": false,
      "supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
      "certified": true
    }
  ]
}