디지털 아이템 기능

디지털 아이템 기능은 서비스의 상품을 DOSI 브랜드 스토어에서 거래할 수 있도록 디지털 아이템으로 만들고 관리하는 엔드포인트 묶음입니다.

DOSI SDK에서는 일반 상품을 DOSI 디지털 아이템으로 만드는 작업을 실링(sealing), 디지털 아이템을 다시 일반 상품으로 되돌리는 작업을 언실링(unsealing)이라고 합니다. 서비스에 실링과 언실링 기능을 구현하면, 서비스 사용자가 게임 등의 서비스에서 목적에 따라 간편하게 자신의 상품을 전환할 수 있습니다.

사용자 월렛에 있는 온라인 상품을 실링, 언실링하려면 먼저 프록시(Proxy)를 설정해야 합니다.

연결 정보

개발 환경	DOSI SDK base URI
운영 환경	https://sdk-api.dosi.world

아이템 타입 생성

새 아이템 타입을 생성하고, 이 타입에 속한 디지털 아이템을 DOSI 브랜드 스토어에서 거래할 수 있도록 등록합니다.

POST {DOSI SDK base URI}/v1/item/contracts/{contractId}/issue

Request

Response

Path

Name	Type	Description
contractId	string	아이템 타입을 생성할 서비스의 contract ID. DOSI SDK 사용 신청 후 받을 수 있습니다. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

None

Body

Name	Type	Description	Required
name	string	디지털 아이템(토큰) 타입 이름. 3~20자 사이의 영문이나 숫자만 입력할 수 있습니다. (공백, 특수 문자, 한글, 일어, 중국어, 태국어 등은 사용 불가)
meta	string	핀시아(Finschia)에 기록할 메타 정보. 키-값 쌍으로 이뤄진 객체를 문자열로 작성한 것으로, 최대 1,000자까지 쓸 수 있습니다. 상세한 정보는 메타 정보 입력 가이드를 참고하세요.
partnerId	number	DOSI Biz 온보딩 때 발급받는 파트너 ID
category	string	디지털 아이템 카테고리. 다음 카테고리 중 하나여야 합니다. "Art" "Character" "Game" "Music" "Sports" "Celebrity" "Metaverse" "Generative" "Avatar" "App Membership" "Voucher"
pfp	boolean	DOSI 사용자 프로필 설정 가능 여부 true: 생성한 디지털 아이템을 사용자 프로필로 설정 가능 false: 생성한 디지털 아이템을 사용자 프로필로 설정 불가
description	string	DOSI 브랜드 스토어의 아이템 페이지에 노출되는 디지털 아이템 설명. 최대 3,000자이며, 영문, 한글, 일어, 중국어(번체), 태국어, 숫자, 공백, 일부 특수문자(!, ,, /, @)를 입력할 수 있습니다.
resaleAvailable	boolean	DOSI 브랜드 스토어에서 C2C(customers to customers) 판매 가능 여부. 입력하지 않으면 true로 간주합니다. true: C2C 판매 등록 가능 (기본값) false: C2C 판매 등록 불가

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>
• Request-Id: 중복 확인용으로 임의 생성한 UUID
• Content-Type: application/json

Request-Id가 중복되면 아래와 같은 오류를 반환합니다.

{ 
   "responseCode": "BAD_REQUEST",
   "errorMessage": "Duplicated request has been detected"
}

Request examples

curl

curl --request POST 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/issue' \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Request-Id: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "name":"itemTypeName",
      "meta":"{\"Property A\":\"Value A\"}",
      "partnerId": 100012,
      "category": "Game",
      "pfp": true,
      "description": "Awesome description of your digital item",
      "resaleAvailable": true
  }'

Name	Type	Description
txId	string	요청을 처리할 트랜잭션의 ID

Response status code

200 OK

Response headers

None

Related errors

None

Response examples

{
  "txId":"1234"
}

아이템 타입 미디어 업로드

생성한 아이템 타입의 미디어(이미지, 동영상)를 업로드합니다.

POST {DOSI SDK base URI}/v1/item/contracts/{contractId}/media/token-type

• 아이템 타입 생성 엔드포인트를 이용해 생성하지 않은 아이템 타입에는 미디어를 업로드할 수 없습니다.
• 미디어 업로드 가이드에서 업로드할 수 있는 파일 유형이나 크기를 반드시 확인하세요.
• 미디어를 업로드할 때 HTTP 클라이언트 라이브러리를 사용한다면 반드시 multipart/form-data로 전송하세요. 라이브러리에 따라 상세 사용법은 다를 수 있으나, 일반적으로 요청 헤더의 Content-Type을 "multipart/form-data"로 설정해야 합니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

None

Body

Name	Type	Description	Required
media	file	업로드할 미디어 파일 (이미지/동영상)
tokenType	string	아이템 타입. 8자리 16진수로, 아이템 타입을 생성할 때 알 수 있습니다.

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>
• Content-Type: multipart/form-data

Request examples

curl

curl --request POST 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/media/token-type' \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Content-Type: multipart/form-data' \
  --form "media=@path/name.png" \
  --form "tokenType=00000001"

None

Response status code

204 No Content

Response headers

None

Related errors

• NOT_FOUND_RESOURCE

아이템 타입 전체 조회

파트너사 contract ID 하위의 모든 아이템 타입을 조회합니다.

GET {DOSI SDK base URI}/v1/item/contracts/{contractId}/item-types

DOSI SDK의 아이템 타입 생성 엔드포인트를 이용하지 않고 생성한 아이템 타입도 조회할 수 있습니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

Name	Type	Description	Required
pageSize	number	한 페이지에 포함할 아이템 타입 수 기본값: 10 최솟값 : 1 최댓값: 100
pageToken	string	페이지 시작 지점 토큰(이전 페이지 조회 응답의 nextPageToken). 입력하지 않으면 첫 번째 페이지를 가져옵니다.

Body

None

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>

Request examples

curl

curl --location --request GET 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/item-types?pageSize=30&pageToken=zz...uu'
  --header 'Authorization: Basic xxxxxxxx'

Name	Type	Description	Included
itemTypes	array	조회한 아이템 타입 목록. 조회할 대상이 없으면 빈 배열을 반환합니다.
nextPageToken	string	다음 페이지 시작 지점 토큰. 다음 페이지가 없으면 null입니다.

Response status code

200 OK

Response headers

None

Related errors

None

Response examples

{
  "itemTypes": [
      {
          "contractId": "f036eaea",
          "itemType": "10000001",
          "name": "CardA",
          "meta": "{\"Color\":\"red\",\"Grade\":\"10\"}"
      },
      {
          "contractId": "f036eaea",
          "itemType": "10000002",
          "name": "CardB",
          "meta": "{\"Color\":\"blue\",\"Grade\":\"20\"}"
      }
  ],
  "nextPageToken": "zz...uu"
}

아이템 타입 개별 조회

파트너사 contract ID 하위의 특정 아이템 타입을 조회합니다.

GET {DOSI SDK base URI}/v1/item/contracts/{contractId}/item-types/{itemType}

DOSI SDK의 아이템 타입 생성 엔드포인트를 이용하지 않고 생성한 아이템 타입도 조회할 수 있습니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.
itemType	string	조회할 아이템 타입의 식별자(16진수 8자리 코드)

Query

None

Body

None

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>

Request examples

curl

curl --location --request GET 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/item-types/yy...tt'
  --header 'Authorization: Basic xxxxxxxx'

Name	Type	Description	Included
contractId	string	아이템 타입이 속한 contract ID
itemType	string	아이템 타입의 식별자(16진수 8자리 코드)
name	string	아이템 타입 이름
meta	string	아이템 타입의 메타 정보

Response status code

200 OK

Response headers

None

Related errors

None

Response examples

{
    "contractId": "f036eaea",
    "itemType": "10000001",
    "name": "CardA",
    "meta": "{\"Color\":\"red\",\"Grade\":\"10\"}"
}

실링

파트너사의 상품을 DOSI 브랜드 스토어용 디지털 아이템으로 만듭니다. 오프체인 상품을 온체인화할 수 있습니다.

POST {DOSI SDK base URI}/v1/item/contracts/{contractId}/sealing

프록시(proxy)를 승인한 사용자 계정에서만 사용할 수 있습니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

None

Body

Name	Type	Description	Required
tokenType	string	디지털 아이템의 아이템 타입. 8자리 16진수로, 아이템 타입을 생성할 때 알 수 있습니다.
toAddress	string	실링한 디지털 아이템을 받을 사용자 월렛 주소
name	string	디지털 아이템 이름. 3~20자 사이의 영문, 한글, 일어, 중국어(번체), 태국어, 숫자, 공백 및 일부 특수 문자(!, ,, /, @)를 쓸 수 있습니다.
meta	string	핀시아(Finschia)에 기록할 메타 정보. 키-값 쌍으로 이뤄진 객체를 문자열로 작성한 것으로, 최대 1,000자까지 쓸 수 있습니다. 상세한 정보는 메타 정보 입력 가이드를 참고하세요.

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>
• Request-Id: 중복 확인용으로 임의 생성한 UUID
• Content-Type: application/json

Request-Id가 중복되면 아래와 같은 오류를 반환합니다.

{ 
   "responseCode": "BAD_REQUEST",
   "errorMessage": "Duplicated request has been detected"
}

Request examples

curl

curl --request POST 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/sealing' \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Request-Id: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "tokenType": "0000001F",
      "toAddress": "link1xxxxxxxxxxzzzzzzzzzzxxxxxxxxxxzzzzzzzz",
      "name":"item1",
      "meta":"{\"Property A\":\"Value A\"}"
  }'

Name	Type	Description
txId	string	요청을 처리할 트랜잭션의 ID

Response status code

200 OK

Response headers

None

Related errors

None

Response examples

{
  "txId":"1234"
}

디지털 아이템 미디어 업로드

생성한 아이템 타입으로 실링한 디지털 아이템의 미디어(이미지, 동영상)을 업로드합니다.

POST {DOSI SDK base URI}/v1/item/contracts/{contractId}/media/item-token

• 아이템 타입 생성 엔드포인트로 생성하지 않은 아이템 타입의 디지털 아이템에는 미디어를 업로드할 수 없습니다.
• 미디어 업로드 가이드에서 업로드할 수 있는 파일 유형이나 크기를 반드시 확인하세요.
• 미디어를 업로드할 때 HTTP 클라이언트 라이브러리를 사용한다면 반드시 multipart/form-data로 전송하세요. 라이브러리에 따라 상세 사용법은 다를 수 있으나, 일반적으로 요청 헤더의 Content-Type을 "multipart/form-data"로 설정해야 합니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

None

Body

Name	Type	Description	Required
media	file	업로드할 미디어 파일 (이미지/동영상)
tokenType	string	디지털 아이템의 아이템 타입. 8자리 16진수로, 아이템 타입을 생성할 때 알 수 있습니다.
tokenIndex	string	디지털 아이템의 아이템 인덱스. 8자리 16진수

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>
• Content-Type: multipart/form-data

Request examples

curl

curl --request POST 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/media/item-token' \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Content-Type: multipart/form-data' \
  --form "media=@path/name.png" \
  --form "tokenType=00000001" \
  --form "tokenIndex=00000002"

None

Response status code

204 No Content

Response headers

None

Related errors

• NOT_FOUND_RESOURCE

디지털 아이템 미디어 교체

디지털 아이템에 등록한 미디어(이미지, 동영상)를 교체합니다. 해당 디지털 아이템을 실링하기 전이나 판매하기 전에 한해, 생성한 아이템 타입 내 디지털 아이템의 미디어를 교체할 수 있습니다.

PUT {DOSI SDK base URI}/v1/item/contracts/{contractId}/media/item-token

• 아이템 타입 생성 엔드포인트로 생성하지 않은 디지털 아이템의 미디어는 교체할 수 없습니다.
• 실링했거나 판매해서 사용자 월렛에 있는 디지털 아이템의 미디어는 교체할 수 없습니다.
• 미디어 업로드 가이드에서 업로드할 수 있는 파일 유형이나 크기를 반드시 확인하세요.
• 미디어를 업로드할 때 HTTP 클라이언트 라이브러리를 사용한다면 반드시 multipart/form-data로 전송하세요. 라이브러리에 따라 상세 사용법은 다를 수 있으나, 일반적으로 요청 헤더의 Content-Type을 "multipart/form-data"로 설정해야 합니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

None

Body

Name	Type	Description	Required
media	file	교체할 미디어 파일 (이미지/동영상)
tokenType	string	디지털 아이템의 아이템 타입. 8자리 16진수로, 아이템 타입을 생성할 때 알 수 있습니다.
tokenIndex	string	디지털 아이템의 아이템 인덱스. 8자리 16진수

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>
• Content-Type: multipart/form-data

Request examples

curl

curl --request PUT 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/media/item-token' \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Content-Type: multipart/form-data' \
  --form "media=@path/name.png" \
  --form "tokenType=00000001" \
  --form "tokenIndex=00000002"

None

Response status code

204 No Content

Response headers

None

Related errors

• NOT_FOUND_RESOURCE

언실링

실링한 아이템을 오프체인 아이템으로 되돌립니다.

PUT {DOSI SDK base URI}/v1/item/contracts/{contractId}/unsealing

프록시(proxy)를 승인한 사용자의 계정에서만 사용할 수 있습니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

None

Body

Name	Type	Description	Required
tokenType	string	디지털 아이템의 아이템 타입. 8자리 16진수로, 아이템 타입을 생성할 때 알 수 있습니다.
tokenIndex	string	디지털 아이템 인덱스. 8자리 16진수
fromAddress	string	언실링할 아이템이 있는 사용자 월렛 주소

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>
• Content-Type: application/json

Request examples

curl

curl --request PUT 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/unsealing' \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "tokenType": "00000001", 
      "tokenIndex": "0000001F",
      "fromAddress": "link1xxxxxxxxxxzzzzzzzzzzxxxxxxxxxxzzzzzzzz"
  }'

Name	Type	Description
txId	string	요청을 처리할 트랜잭션의 ID

Response status code

200 OK

Response headers

None

Related errors

None

Response examples

{
  "txId":"1234"
}

배치 언실링

한 사용자 월렛에 있는 여러 개 디지털 아이템을 한번에 오프체인 아이템으로 되돌립니다.

PUT {DOSI SDK base URI}/v1/item/contracts/{contractId}/batch-unsealing

프록시(proxy)를 승인한 사용자 계정에서만 사용할 수 있습니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

None

Body

Name	Type	Description	Required
tokenList	array	언실링할 디지털 아이템 목록
fromAddress	string	언실링할 아이템이 있는 사용자 월렛 주소

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>
• Content-Type: application/json

Request examples

curl

curl --request PUT 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/batch-unsealing' \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "tokenList": [
          {
              "tokenType": "00000001",  
              "tokenIndex": "0000001F"
          },
          {
              "tokenType": "00000001",  
              "tokenIndex": "0000001A"
          },
      ], 
      "fromAddress": "link1xxxxxxxxxxzzzzzzzzzzxxxxxxxxxxzzzzzzzz"
  }'

Name	Type	Description
txId	string	요청을 처리할 트랜잭션의 ID

Response status code

200 OK

Response headers

None

Related errors

None

Response examples

{
  "txId":"1234"
}

재실링

한번 실링했다가 언실링한 상품을 다시 실링합니다. 재실링하더라도 핀시아 체인상에 있는 디지털 아이템의 총발행량은 바뀌지 않습니다.

DOSI 브랜드 스토어에서 판매하기 전에 이 엔드포인트를 호출해 name과 meta를 입력하면 디지털 아이템의 기존 이름과 속성을 변경할 수 있습니다.

아이템 타입 생성 엔드포인트로 생성하지 않은 디지털 아이템의 이름과 속성은 변경할 수 없습니다.

POST {DOSI SDK base URI}/v1/item/contracts/{contractId}/resealing

프록시(proxy)를 승인한 사용자 계정에서만 사용할 수 있습니다.

Request

Response

Path

Name	Type	Description
contractId	string	DOSI SDK 사용 신청 후 받은 contract ID. 요청 헤더 Authorization에 입력한 DOSI 채널과 연결된 contract ID만 입력해야 합니다.

Query

None

Body

Name	Type	Description	Required
tokenType	string	디지털 아이템의 아이템 타입. 8자리 16진수로, 아이템 타입을 생성할 때 알 수 있습니다.
tokenIndex	string	디지털 아이템의 아이템 인덱스. 8자리 16진수
toAddress	string	재실링한 디지털 아이템을 받을 사용자 월렛 주소
name	string	변경할 이름. 3~20자 사이의 영문, 한글, 일어, 중국어(번체), 태국어, 숫자, 공백 및 일부 특수 문자(!, ,, /, @)를 쓸 수 있습니다. name과 meta는 한 쌍이므로 둘 다 입력하거나 입력하지 말아야 합니다. 하나만 입력하면 BAD_REQUEST 오류를 반환합니다.
meta	string	변경할 메타 정보(속성). 실링할 때 설정한 디지털 아이템의 메타 정보를 변경할 수 있습니다. 상세한 정보는 메타 정보 입력 가이드를 참고하세요. name과 meta는 한 쌍이므로 둘 다 입력하거나 입력하지 말아야 합니다. 하나만 입력하면 BAD_REQUEST 오류를 반환합니다.

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>
• Content-Type: application/json

Request examples

name과 meta를 변경할 때

name과 meta를 변경하지 않을 때

curl --request PUT 'https://sdk-api.dosi.world/v1/item/contracts/xx...ss/unsealing' \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "tokenType": "00000001", 
      "tokenIndex": "0000001F",
      "toAddress": "link1xxxxxxxxxxzzzzzzzzzzxxxxxxxxxxzzzzzzzz",
      "name":"item1",
      "meta":"{\"Property A\":\"Value A\"}"
  }'

Name	Type	Description
txId	string	요청을 처리할 트랜잭션의 ID

Response status code

200 OK

Response headers

None

Related errors

• BAD_REQUEST
• FAILED_PRECONDITION

Response examples

{
  "txId":"1234"
}

트랜잭션 조회

트랜잭션 ID를 이용해 트랜잭션 상태를 조회합니다.

GET {DOSI SDK base URI}/v1/item/transactions/{txId}

Request

Response

Path

Name	Type	Description
txId	string	조회할 트랜잭션 ID. 실링, 언실링, 재실링 등 트랜잭션을 일으키는 요청을 보낸 후 응답으로 받은 값을 입력하세요.

Query

None

Body

None

Headers

• Authorization: Basic <'DOSI 채널 ID:시크릿'을 Base64로 인코딩한 값>

Request examples

curl

curl --location --request GET 'https://sdk-api.dosi.world/v1/item/transactions/{txId}' \
  --header 'Authorization: Basic xxxxxxxx'

Name	Type	Description	Included
type	string	처리 유형. 다음 중 하나입니다. "SEALING" "UNSEALING" "RESEALING" "NONE" "ISSUE" "PROXY_COMMIT"
status	string	처리 상태. 다음 중 하나입니다. "ACCEPTED" "PENDING" "SUCCESS" "FAILURE"
txHash	string	트랜잭션 해시
items	array	트랜잭션에 포함된 디지털 아이템 목록

Response status code

200 OK

Response headers

None

Related errors

None

Response examples

{
  "type":"SEALING|UNSEALING|RESEALING"
  "status":"SUCCESS|FAILURE",
  "txHash":"F229213C417233F6B0B7ABBE298554B2F4B5CF0A3576C1A6C0C8A609C6D8DAA4",
  "items":[
    {
      "tokenType":"abcdabcd",
      "tokenIndex":"0000100f"
    }
  ]
}