마켓 플레이스 파트너

GitLab은 권한이있는 채널 파트너에게 GitLab 제품의 판매를 처리하는 선택된 유통 마켓 플레이스의 자동화를 지원합니다. 마켓 플레이스 파트너는 GitLab Marketplace API를 사용하여 시스템을 GitLab과 통합하고 그들의 사이트에서 GitLab 구독을 판매할 수 있습니다.

이 문서의 대상 독자는 마켓 플레이스 파트너를위한 타사 개발자입니다.

마켓 플레이스 API 작동 방식

마켓 플레이스 API는 고객 포털에 호스팅됩니다. 고객 포털을 통해 개별 고객이 GitLab 구독을 구매하고 관리할 수 있으며 파트너가 고객을 대신하여 판매하기위한 API를 지원합니다. 고객 포털은 Zuora 및 Salesforce를 포함한 다른 GitLab 서비스와 통합되어 사용자를위한 과제 중심 인터페이스를 제공합니다.

다음 예는 다음 구성 요소 간의 일반적인 구매 흐름을 보여줍니다.

고객
마켓 플레이스 파트너 시스템
고객 포털
Zuora
Salesforce

sequenceDiagram participant 고객 participant 마켓 플레이스 파트너 시스템 participant 고객 포털 participant Zuora participant Salesforce 고객 ->> 마켓 플레이스 파트너 시스템: GitLab 구독을 구매하기 위해 주문 마켓 플레이스 파트너 시스템 ->> 고객 포털: OAuth 토큰 가져오기 고객 포털 ->> 마켓 플레이스 파트너 시스템: 액세스 토큰 마켓 플레이스 파트너 시스템 ->> 고객 포털: 주문 고객 포털 ->> Zuora: Zuora 구독 생성 고객 포털 ->> Salesforce: Salesforce 객체 생성 Zuora ->> 고객 포털: Zuora 구독 데이터와 함께 성공한 응답 고객 포털 ->> 마켓 플레이스 파트너 시스템: 주문 ID와 함께 성공한 응답 Zuora ->> 고객 포털: Zuora 콜아웃 이벤트 고객 포털 ->> 고객: 라이선스 알림 전송 마켓 플레이스 파트너 시스템 ->> 고객 포털: 주문 상태 폴링 고객 포털 ->> 마켓 플레이스 파트너 시스템: 주문 상태와 함께 성공한 응답

마켓 플레이스 API 사양

마켓 플레이스 API의 OpenAPI 사양은 마켓 플레이스 대화 형 API 설명서에서 확인할 수 있습니다.

마켓 플레이스 API 액세스

마켓 플레이스 API에 액세스하려면 다음을 수행해야합니다.

GitLab에서 액세스 요청
OAuth 액세스 토큰 검색

마켓 플레이스 API 엔드 포인트는 OAuth 2.0으로 보호됩니다. OAuth는 제한된 액세스를 허용하는 권한 부여 프레임 워크입니다.

OAuth 2.0은 클라이언트 응용 프로그램이 액세스 토큰 형식의 권한을 얻는 방법을 설명하는 그랜트 유형 (또는 플로우)을 사용합니다. 액세스 토큰은 클라이언트 응용 프로그램이 리소스 서버에 권한이있는 요청을 수행하는 데 사용하는 문자열입니다.

마켓 플레이스 API는 client_credentials 그랜트 유형을 사용합니다. 클라이언트 응용 프로그램은 사용자 대신 자체 리소스에 액세스하는 데 사용합니다.

단계 1 : 액세스 요청

마켓 플레이스 API를 사용하려면 마켓 플레이스 파트너 매니저에게 문의하거나 partnerorderops로 이메일을 보내야합니다. 액세스를 요청 한 후, GitLab은 다음과 같은 계정 및 자격 증명을 구성합니다.

클라이언트 자격 증명. 마켓 플레이스 API는 OAuth 2.0으로 보호됩니다. 클라이언트 자격 증명에는 OAuth 액세스 토큰을 검색하는 데 필요한 클라이언트 ID 및 클라이언트 시크릿이 포함됩니다.
Zuora 시스템의 인보이스 소유자 계정. 인보이스 처리에 필요합니다.
Salesforce 시스템의 유통업자 계정.
Salesforce 시스템의 거래 파트너 계정. GitLab은 검증을 통과하기위한 허용 목록에 거래 파트너 ID를 추가합니다.

단계 2 : 액세스 토큰 검색

액세스 토큰을 검색하려면 다음을 수행하십시오.

다음 필수 매개 변수와 함께 /oauth/token 엔드 포인트로 POST 요청을 수행하십시오.

매개 변수	유형	필수 여부	설명
`client_id`	문자열	예	GitLab에서 받은 고객 포털의 클라이언트 응용 프로그램 레코드 ID.
`client_secret`	문자열	예	GitLab에서 받은 고객 포털의 클라이언트 응용 프로그램 레코드 시크릿.
`grant_type`	문자열	예	자격 증명 플로우의 유형을 지정합니다. `client_credentials`를 사용하십시오.
`scope`	문자열	예	액세스 수준을 지정합니다. 읽기 전용 액세스의 경우 `marketplace.order:read`를 사용하십시오. 생성 액세스의 경우 ‘marketplace.order:create’를 사용하십시오.

요청이 성공하면 응답 본문에는 후속 요청에서 사용할 수있는 액세스 토큰이 포함됩니다. 성공적인 응답 예에 대해서는 마켓 플레이스 대화 형 API 설명서를 참조하십시오.

요청이 실패하면 응답 본문에는 오류 및 오류 설명이 포함됩니다. 오류는 다음과 같을 수 있습니다.

상태	설명
400	유효하지 않은 범위. `scope`가 `marketplace.order:read` 또는 `marketplace.order:create`인지 확인합니다.
401	유효하지 않은 클라이언트. 고객 특정 자격 증명에 철자 오류 또는 추가 공간이없는지 확인하십시오. 올바른 `client_id` 또는`client_secret`

단계 3: 액세스 토큰 사용

클라이언트 애플리케이션에서 액세스 토큰을 사용하려면:

요청의 Authorization 헤더를 Bearer <your_access_token>으로 설정합니다.
엔드포인트에 필요한 매개변수나 데이터를 설정하고 요청을 보냅니다.

예시 요청:

curl \
  --url "https://customers.staging.gitlab.com/api/v1/marketplace/subscriptions/:external_subscription_id" \
  --header "Authorization: Bearer NHb_VhZhPOnBTSNfBSzmCmt28lLDWb2xtwr_c3DL148"

새로운 고객 구독 만들기

마켓플레이스 파트너 클라이언트 애플리케이션에서 새로운 고객 구독을 만들려면,

Customers Portal의 /api/v1/marketplace/subscriptions 엔드포인트로 권한 부여된 POST 요청을 보냅니다. 요청은 다음 매개변수를 JSON 형식으로 포함해야 합니다:

매개변수	타입	필수	설명
`externalSubscriptionId`	string	yes	마켓플레이스 파트너 시스템의 구독 ID입니다.
`tradingPartnerId`	string	yes	Salesforce의 거래 파트너 계정 ID입니다. GitLab에서 받은 것입니다.
`customer`	object	yes	고객 정보입니다. 회사 이름을 반드시 포함해야 합니다. 연락처는 `firstName`, `lastName` 및 `email`을 반드시 포함해야 합니다. 주소는 `country`를 포함해야 합니다.
`orderLines`	array	yes	구매한 제품을 지정합니다. 반드시 `quantity` 및 `productId`를 포함해야 합니다.

요청이 성공하면 응답 본문에는 새로 생성된 구독 번호가 포함됩니다. 전체 요청 본문의 예시는 마켓플레이스 대화형 API 문서를 참조하세요.

구독 생성이 실패하면 응답 본문에는 오류 메시지와 오류 원인에 대한 상세 정보가 포함됩니다.

구독 상태 확인

특정 구독의 상태를 확인하려면,

Customers Portal의 /api/v1/marketplace/subscriptions/{external_subscription_id} 엔드포인트로 권한 부여된 GET 요청을 보냅니다.

요청은 가져올 구독의 마켓플레이스 파트너 시스템 ID를 반드시 포함해야 합니다.

요청이 성공하면 응답 본문에는 구독 프로비저닝의 상태가 포함됩니다. 상태는 다음과 같을 수 있습니다:

생성 중
생성됨
실패
프로비저닝됨

전달된 external_subscription_id를 사용하여 구독을 찾을 수 없으면 응답은 404 Not Found 상태를 가집니다.