[[신규기능]] 디파이너리 Open API

Introduction

본 가이드는 디파이너리 내 저장된 데이터를 다운로드 / 업데이트 or 생성 할 수 있도록 개발된 Open API 가이드입니다.

Open API 사용하기

API Token 발급

Open API 를 사용하기 위해서는 디파이너리 콘솔을 통해 API Token 을 발급받아야 합니다. API Token 은 아래와 같이 급합니다.

디파이너리 콘솔을 로그인 후 좌측 메뉴에 Setting & SDK 메뉴에서 Application 을 선택합니다.
앱 리스트에서 Open API 를 사용할 앱을 확인하고 "관리" 버튼을 클릭합니다.
하단 메뉴에서 Token 메뉴를 클릭합니다.
생성된 Token 이 없으면 + 추가 버튼을 클릭합니다.
생성된 토큰을 확인합니다.

[[인용:안내:보통]] 발급된 토큰이 삭제 혹은 재발행된 경우 기존 토큰은 최대 14일간 사용이 가능합니다.

Rate Limit

[[인용:안내:보통]] Rate Limit 는 기본 1분당 10,000 건입니다. 제한을 늘리고 싶다면 디파이너리 고객성공팀에 문의 부탁드립니다. [디파이너리 고객성공팀 문의하기]

Rate Limit 의 현황을 확인하고 싶으시면 Response Header 의 X-Rate Limit 값을 통해 확인하실 수 있습니다.

Header Name	Type	Description
X-Rate-Limit-Limit	string	제한 기준(기간 - y, M, d, H, m, s)
X-Rate-Limit-Remaining	integer	제한 기준 내, 남은 조회 수
X-Rate-Limit-Reset	integer	Limit 제한 룰이 리셋되는 시간 타임스탬프

Example

Example	X-Rate-Limit-Limit	X-Rate-Limit-Remaining	X-Rate-Limit-Reset
1일 100,000건인 경우	1d	99,999	1682640000000
1시간 10,000건인 경우	1H	9,999	1682593200268
1분 10,000건인 경우	1m	9,999	1682593020036

Open API 리스트

디파이너리 Open API 에서 제공하는 API 목록 및 기본적인 요청 정보입니다.

URL	Host	Method	기능
/api/v1/users/profile/update	https://openapi.dfinery.io	POST	User Profile 설정 및 업데이트
/api/v1/users/profile	https://openapi.dfinery.io	POST	User Profile 조회

User Profile API

[[인용:위험:보통]] Notice
4월 28일 (금) 업데이트 되는 User Profile API 는 알림수신 동의 항목에 한해서만 조회, 및 업데이트가 가능합니다. 나머지 항목은 차후 업데이트 될 예정입니다.

알림 수신 동의 항목

Key	Type	Value	Description
info_flag	String	"Subscribed" / "Unsubscribed"	정보성 알림
mkt_flag	String	"Subscribed" / "Unsubscribed"	광고성 알림
mkt_push_flag	String	"Subscribed" / "Unsubscribed"	광고성 알림(푸시)
mkt_sms_flag	String	"Subscribed" / "Unsubscribed"	광고성 알림(SMS)
mkt_kakao_flag	String	"Subscribed" / "Unsubscribed"	광고성 알림(Kakao)
night_flag	String	"Subscribed" / "Unsubscribed"	야간 광고성 알림
night_push_flag	String	"Subscribed" / "Unsubscribed"	야간 광고성 알림(푸시)
night_sms_flag	String	"Subscribed" / "Unsubscribed"	야간 광고성 알림(SMS)
night_kakao_flag	String	"Subscribed" / "Unsubscribed"	야간 광고성 알림(Kakao)

[[인용:안내:보통]] User Profile 조회시 설정 이력이 없을 경우 "Undefined" 를 Return 합니다.

User Profile 설정하기

사용자 프로필을 설정 혹은 업데이트 하기 위한 API 입니다.

Headers

Key	Value
Authorization	Bearer ${API Token}
Content-Type	application/json

Body

Parameter

Name	Type	Description	Required
user_properties	UserProperty[]	업데이트할 유저ID, 프로퍼티 배열, 최대 20개	O

UserProperty

Name

Type

Description

Required

user_id

String

유저 식별값

properties

{"key": value}

업데이트 할 프로퍼티.

key 는 string 만 사용 가능.

value 는 string, number, boolean 만 사용 가능

Example

{
  "user_properties": [
    {
      "user_id": "User_1",
      "properties": {
        "info_flag": "Subscribed",
        "mkt_flag": "Subscribed"
      }
    },
    {
      "user_id": "User_2",
      "properties": {
        "info_flag": "Subscribed",
        "mkt_flag": "Subscribed"
      }
    }
  ]
}

Response Example

HTTP/1.1 200 OK
{
  "result_code": 2000,
  "result_msg": null,
  "result_data": {
    "successful_user_ids": [
      "User_1",
      "User_2"
    ],
    "failure_details": null
  }
}

일부 유저 업데이트 성공

HTTP/1.1 200 OK
{
  "result_code": 2000,
  "result_msg": null,
  "result_data": {
    "successful_user_ids": ["User_1"],
    "failure_details": [
      {
        "code": 5003,
        "msg": "The server was too busy to handle it. Please try again later.",
        "user_ids": ["User_2"]
      }
    ]
  }
}

업데이트 실패

HTTP/1.1 400 BadRequest 
{
  "result_code": 4002,
  "result_msg": "Too many user ids in request.",
  "result_data": null
}

User Profile 조회하기

사용자 프로필을 조회하기 위한 API 입니다.

Headers

Key	Value
Authorization	Bearer ${API Token}
Content-Type	application/json

Body

Parameter

Name	Type	Description	Required
user_ids	String[]	유저 식별값, 최대 20개	O
property_names	String[]	조회할 프로퍼티명	X

Example

UserID 내 특정 프로퍼티만 조회

{
  "user_ids": ["User_1", "User_2"],
  "property_names": ["info_flag", "mkt_flag"]
}

Response Example

HTTP/1.1 200 OK
{
  "result_code": 2000,
  "result_msg": null,
  "result_data": {
    "successful_user_properties": [
      {
        "user_id": "User_1",
        "properties": {
          "info_flag": "Subscribed",
          "mkt_flag": "Subscribed"
        }
      },
      {
        "user_id": "User_2",
        "properties": {
          "info_flag": "Subscribed",
          "mkt_flag": "Unsubscribed"
        }
      }
    ],
    "failure_details": []
  }
}

조회 실패시

HTTP/1.1 400 BadRequest
{
  "result_code": 4002,
  "result_msg": "Too many user ids in request.",
  "result_data": null
}

Response code

Open API 요청시의 Response Code 입니다.

Code	Message	Description	Http Status
2000		요청 성공	200
4001	"Invalid API Token Error."	Invalid Token	400
4002	"Invalid request format." "Required parameters cannot be empty." "Too many ids in request."	필수 인자가 포함되지 않은 경우나 호출 인자값의 데이타 타입이 적절하지 않거나 허용된 범위를 벗어난 경우 해결 방법: 요청 파라미터 확인	400
4003	"Forbidden account error."	계정이 제재된 경우나 해당 계정에 제재된 행동을 하는 경우	403
4004	"Unauthorized"	해당 API에 대한 요청 권한이 없는 경우해결 방법: 해당 API의 이해하기 문서를 참고하여 검수 진행, 권한 획득 후 재호출	403
4005	"This API is closed."	서비스가 종료된 API를 호출한 경우 해결 방법: 공지 메일 확인 후 업데이트	400
4006	"API RateLimit exceeded."	허용된 요청 수를 초과한 경우 해결 방법: Rate Limit 확인 후 범위 내로 호출 조정, 추가 요청 필요 시 고객센터로 문의	429
4007	"Contains unsupported property {name or value}.",	지원하지 않는 Property Value Type 을 설정한 경우.	400
5001	"Internal Server Error."	서버 내부에서 처리 중에 에러가 발생한 경우 해결 방법: 재시도 및 고객센터 문의	500
5002	"Service is under maintenance. Please try again later."	서비스 점검중	503
5003	"The server was too busy to handle it. Please try again later."	서버로 많은 요청이 몰려 처리할 수 없는 경우 해결 방법 : 재시도 및 고객센터 문의

이 섹션의 문서

Introduction

Open API 사용하기

API Token 발급

Rate Limit

Open API 리스트

User Profile API

User Profile 설정하기

User Profile 조회하기

Response code

클릭하여 고객지원팀에게 문의하기

이 섹션의 문서

Introduction

Open API 사용하기

API Token 발급

Rate Limit

Open API 리스트

User Profile API

User Profile 설정하기

User Profile 조회하기

Response code

관련 문서

클릭하여 고객지원팀에게 문의하기