Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
POST
/api/v1/identities
고객의 통합 프로필을 생성 및 업데이트 할 수 있는 API 입니다.
service_id
String
서비스 ID
Content-Type
String
application/json
-
access_token
String
your-api-token-key
API 인증 토큰
identity
Object
이벤트 적재를 위한 공통 속성
request_datetime
Datetime
요청 시각, ISODate 8601 Format,
2024-06-24T06:42:25.394Z
유저 식별 정보입니다. 아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.
external_id
String
외부 ID
phone_no
String
전화 번호
email
String
이메일
kakao_user_id
String
카카오 ID
line_user_id
String
라인 ID
자세한 내용은 상세 응답 참고하시면 됩니다.
POST
/api/v1/events
이벤트 적재 API를 통해 하나 혹은 여러 이벤트를 한번에 적재할 수 있습니다. 적재하고자 하는 이벤트는 콘솔에서 사전 등록되어 있어야 합니다.
한번의 요청에서 최대 100개의 이벤트를 적재할 수 있습니다. 또한, 한번의 요청에서 최대 100개의 이벤트 아이템을 적재할 수 있습니다.
많은 이벤트를 적재 해야 한다면, 개별로 이벤트 적재 API를 호출하는 것 보다 여러 이벤트를 모아두었다가 한번에 이벤트 적재 API를 호출하는 것이 속도 및 요청 제한 측면에서 좋습니다. 연동 시에는 항상 요청 제한을 고려해야 합니다.
service_id
String
서비스 ID
Content-Type
String
application/json
-
access_token
String
your-api-token-key
API 인증 토큰
Object
이벤트 적재를 위한 공통 속성
Array of Object
이벤트 정보
Object
유저 식별자
유저 식별자 정보입니다. 아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.
external_id
String
외부 ID
phone_no
String
전화 번호
email
String
이메일
kakao_user_id
String
카카오 ID
line_user_id
String
라인 ID
event_log_id
String
이벤트 식별 ID, UUID Format,
xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
event_name
String
이벤트명
event_datetime
Datetime
이벤트 발생 시각
Array of Object
상품 정보
Object
이벤트 속성
이벤트 아이템 속성입니다. 필드명은 콘솔에서 사전 등록된 아이템(df_item
) 의 하위 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다. 이벤트 아이템은 한번에 최대 100개까지 적재 가능합니다.
${your-df-item-property-key}
String, Long, Double, Boolean, Datetime, Array
사전 등록된 이벤트 아이템 속성 정보
이벤트 속성입니다. 필드명은 아이템(df_item
) 을 제외한 콘솔에서 사전 등록된 이벤트 속성의 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다.
${your-event-property-key}
String, Long, Double, Boolean, Datetime, Array
사전 등록된 이벤트 속성 정보
자세한 내용은 상세 응답 참고하시면 됩니다.
이벤트 수가 100개를 초과하거나, 이벤트 아이템 수가 100개를 초과한 경우입니다.
Profile API를 통해 유저의 속성을 생성하거나 업데이트 할 수 있습니다. API 연동을 위해서는 먼저 기본 세팅을 완료하여야 합니다. API 연동을 위한 기본 세팅을 아직 하지 못했다면, 시작하기 전에 를 참고해 주시면 됩니다.
유저 속성 생성 및 업데이트 API를 통해 온/오프라인 채널에 대한 유저의 수신 동의 정보 값을 설정할 수 있습니다.
오후 9시 부터 오전 8시 사이에는 별도의 수신 동의를 받아야 광고성 알림을 전송할 수 있습니다.
알림 수신 동의 정보에 대한 유저 프로필은 예외적으로 DFINERY에서 서비스 생성 시 이미 자동으로 등록되어 있어 DFINERY 콘솔에서 설정하지 않아도 설정이 가능합니다.
수신 동의 정보는 기본값을 통해 따로 설정하지 않아도 발송될 수 있습니다. 자세한 사항은 이용자 가이드의 를 참고하시면 됩니다.
DFINERY의 API는 아래의 데이터 타입을 사용합니다. 사용자가 API를 연동할 때에는 API에서 요구하는 데이터 타입에 맞춰 요청하여야 합니다.
DFINERY의 API를 통해 온/오프라인 유저의 이벤트 및 속성을 전송하고, 데이터를 추출할 수 있습니다.
DFINERY의 API를 사용하기 전에, 아래 사항이 사전에 준비되어 있어야 합니다.
회원가입 및 조직, 서비스 생성 : API를 사용하기 위해서는 회원가입 후, 조직과 서비스가 생성되어 있어야 합니다. 자세한 사항은 이용자 가이드의 를 참고하시면 됩니다.
이벤트 및 유저 속성 등록 : DFINERY는 사전 등록된 이벤트와 유저 속성 데이터만을 적재합니다. 적재하고자 하는 이벤트와 유저 속성 데이터가 있다면 미리 콘솔에서 등록하여야 합니다. 자세한 사항은 이용자 가이드의 를 참고하시면 됩니다.
API 토큰 발급 : DFINERY는 API 토큰을 통해 사용자가 보낸 요청이 인증된 요청인지 판단합니다. API 토큰은 디파이너리 콘솔을 통해 발급 받을 수 있습니다. 자세한 사항은 을 참고하시면 됩니다.
API 요청 제한 고려 : DFINERY는 서비스별로 시간당 API 호출 횟수를 제한합니다. API 요청 시에는 API 요청 제한을 고려하여 요청하도록 설계해야 합니다. 자세한 사항은 을 참고하시면 됩니다.
DFINERY API는 아래 한개의 도메인을 사용합니다.
DFINERY는 아래와 같은 종류의 API를 제공합니다.
DFINERY API에서는 일관된 데이터 타입과 포맷을 사용합니다. 사용자가 API를 연동할 때에는 API에서 요구하는 데이터 타입에 맞춰 요청하여야 합니다.
DFINERY는 API 토큰을 통해 사용자가 보낸 요청이 인증된 요청인지 판단합니다. 모든 API 요청의 헤더에는 API 토큰이 필수로 포함되어야 합니다. API 토큰은 디파이너리 콘솔을 통해 발급 받을 수 있습니다.
DFINERY의 API 토큰은 Import API, Export API 토큰으로 나뉘어 있습니다. Import API 토큰은 디파이너리에 고객사의 데이터를 전송할 때 사용합니다 (Event, Identity, Profile API). Export API 토큰은 고객사가 디파이너리에 적재되어 있는 데이터를 추출할 때 사용합니다 (Export API).
POST
/api/v1/user-profile
고객의 유저 속성을 생성 및 업데이트할 수 있는 API입니다.
유저 속성의 생성 및 업데이트 API 호출은 유저의 속성의 변경 시점에만 호출하는 것이 좋습니다. 연동 시에는 항상 을 고려해야 합니다.
유저 식별자 정보입니다. 아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.
유저 속성입니다. 필드명은 콘솔에서 사전 등록된 유저 속성의 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다.
이벤트 정보입니다. 적재하고자 하는 이벤트는 콘솔에서 사전 등록되어 있어야 합니다. 표준 이벤트와 이벤트 속성에 대한 자세한 내용은 사용자 가이드의 를 참고해 주시면 됩니다.
성공 시 헤더를 포함한 csv포맷의 데이터를 응답으로 받게 됩니다. 자세한 사항은 각 를 참고하시면 됩니다.
자세한 사항은 을 참고하시면 됩니다.
자세한 사항은 을 참고하시면 됩니다.
DFINERY는 안정적인 서비스 운영을 위해 서비스별로 시간당 API 요청 횟수를 제한합니다. API 요청 제한을 초과하면 이후의 모든 요청은 실패하고, 제한 시간이 지나 요청 제한이 초기화된 후 요청이 성공합니다. API 요청 제한에 대한 자세한 내용은 을 참고하시면 됩니다.
이벤트 속성에 대한 자세한 내용은 를 참고하시면 됩니다.
자세한 내용은 참고하시면 됩니다.
자세한 내용은 참고하시면 됩니다.
String
-
"foo"
Long
-
1
Double
-
1.0
Boolean
-
true
Array of String
-
["foo", "bar"]
Array of Long
-
[0, 1]
Array of Double
-
[0.0, 1.0]
Datetime
yyyy-MM-dd'T'HH:mm:ss(.SSS)Z
2023-08-15T12:30:00.000Z, 2023-08-15T12:30:00Z,
Date
yyyy-MM-dd
2023-08-15
200 - OK
서버에서 정상적으로 요청을 받았습니다.
400 - Bad Request
요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 요청 파라미터를 확인해 주세요.
429 - Too Many Requests
비정상적으로 많은 요청을 보냈습니다. 잠시 후 다시 시도해 주세요.
500 - Server Error
서버 내부에서 에러가 발생했습니다
200
fail
client_connection_closed
클라이언트 연결이 종료되었습니다.
400
fail
invalid_parameter
제공된 요청 파라미터가 잘못되었거나 형식이 맞지 않습니다.
400
fail
exceed_date_range_limit
요청한 시작일이 허용된 범위를 초과하였습니다.
401
fail
unauthorized_token
유효하지 않은 Export 토큰입니다.
429
fail
too_many_api_requests
요청한 API 호출 수가 한도를 초과했습니다.
500
fail
unknown_error
시스템 내부에서 예기치 않은 오류가 발생했습니다.
500
fail
query_error
요청된 데이터베이스 쿼리가 실행되지 않고, 실패하였습니다.
${your-standard-event-property-key}
표준 이벤트 속성
표준 이벤트 속성
${your-custom-event-property-key}
커스텀 이벤트 속성
커스텀 이벤트 속성
${your-df-item-property-key}
표준, 커스텀 이벤트 속성
이벤트 아이템 (표준, 커스텀) 속성
df_api_version
시스템 이벤트 속성
이벤트 API 버전
event_name
시스템 이벤트 속성
이벤트명
df_server_datetime
시스템 이벤트 속성
이벤트 로그 서버 도달 시각
df_correction_datetime
시스템 이벤트 속성
이벤트 발생 시각
df_event_detail_log_id
시스템 이벤트 속성
이벤트 로그 ID, 구매 이벤트에서 여러 아이템이 포함되어 있는 경우,
${df_event_log_id}:${n}
의 형태입니다.
df_event_log_id
시스템 이벤트 속성
이벤트 로그 ID
200 - OK
서버에서 정상적으로 요청을 받았습니다.
400 - Bad Request
요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 요청 파라미터를 확인해 주세요.
429 - Too Many Requests
비정상적으로 많은 요청을 보냈습니다. 잠시 후 다시 시도해 주세요.
500 - Server Error
서버 내부에서 에러가 발생했습니다
200
20000
OK
요청 성공
200
40000
BAD_REQUEST
잘못된 요청
200
40001
VALIDATION_FAILURE
검증 실패
200
40101
INVALID_SERVICE_ID
잘못된 서비스 ID
200
40201
INVALID_TOKEN
잘못된 토큰 제공
200
40401
TOO_MANY_REQUEST
API 사용 한도 초과
200
40402
TOO_MANY_EVENTS
요청 내 이벤트 수 초과
200
40403
TOO_MANY_USER_PROFILES
단일 요청 내 유저 프로필 수 초과
200
50000
INTERNAL_SERVER_ERROR
서버 내부 에러 발생
${your-user-property-key}
String, Long, Double, Boolean, Datetime, Array
사전 등록된 유저 속성 정보
service_id
String
서비스 ID
Content-Type
String
application/json
-
access_token
String
your-api-token-key
API 인증 토큰
Object
유저 식별자
Object
유저 속성
request_datetime
Datetime
요청 시각, ISODate 8601 Format,
2024-06-24T06:42:25.394Z
external_id
String
외부 ID
phone_no
String
전화 번호
email
String
이메일
kakao_user_id
String
카카오 ID
line_user_id
String
라인 ID
service_id
String
서비스 ID
Content-Type
String
application/json
-
Authorization
String
Bearer your-auth-token
API 인증 토큰
events
List of String
필터링 대상 이벤트명 리스트, 값이 존재하지 않을 경우 모든 이벤트 추출
events_condition_type
String
필터링 연산자, 아래 값을 지원합니다.
all
: 전체 이벤트,
include
: events
의 이벤트만 포함,
exclude
: events
의 이벤트 제외
from_date
Date
이벤트 조회 시작일, yyyy-MM-dd,
2024-12-05
to_date
Date
이벤트 조회 종료일, yyyy-MM-dd,
2024-12-05
아래의 모범 사례는 API 연동을 위한 기본 세팅을 완료하였다고 가정합니다. API 연동을 위한 기본 세팅을 아직 하지 못했다면, 시작하기 전에 를 참고해 주시면 됩니다.
DFINERY Import API를 사용하여 다양한 오프라인 데이터를 DFINERY 서버로 전송할 수 있습니다.
유저가 오프라인 매장을 통해 가입한 이후 마케팅 수신동의를 하였습니다. 해당 유저는 이후 오프라인 매장에서 구매를 하였습니다.
오프라인 매장을 통해 가입 시, 통합 프로필 생성 및 업데이트 API 를 통해 신규 유저의 프로필을 생성합니다.
가입 이후 마케팅 수신동의 시, 유저 속성 생성 및 업데이트 API 를 통해 해당 유저의 마케팅 수신동의 속성을 업데이트합니다.
이후 오프라인 매장에서 구매 시, 이벤트 적재 API 를 통해 해당 유저의 구매 이벤트를 적재합니다.
일반적으로 통합 프로필 생성 > 유저 프로필 생성 > 이벤트 적재 API 순으로 호출하는 것이 좋습니다.
POST
api/v1/export/userprofile
적재되어있는 유저 프로필을 추출할 수 있는 API 입니다.
service_id
String
서비스 ID
Content-Type
String
application/json
-
Authorization
String
Bearer your-auth-token
API 인증 토큰
properties
List of String
필터링 대상 유저 속성명 리스트, 값이 존재하지 않을 경우 모든 유저 속성 추출
properties_condition_type
String
필터링 연산자, 아래 값을 지원합니다.
all
: 전체 유저 속성,
include
: properties
의 유저 속성만 포함,
exclude
: properties
의 유저 속성 제외
audience
String
추출하고자 하는 유저가 포함된 오디언스ID, 값이 존재하지 않을 경우 모든 유저에 대해 추출
유저 프로필 추출의 응답은 ,
로 구분되는 헤더가 포함된 csv 포맷입니다. 첫번째 줄이 헤더이고, 두번째 줄부터 추출된 데이터입니다. 아래의 표는 주요 헤더에 대한 설명입니다.
유저 프로필 속성에 대한 자세한 내용은 표준 유저 프로필 속성 목록 을 참고하시면 됩니다.
${your-standard-user-property-key}
표준 유저 프로필 속성
표준 유저 프로필 속성
${your-custom-user-property-key}
커스텀유저 프로필 속성
커스텀유저 프로필 속성
자세한 내용은 상세 응답 참고하시면 됩니다.
https://openapi.dfinery.ai
DFINERY API 도메인
유저의 이벤트 데이터를 적재할 수 있습니다.
유저 식별정보를 업데이트합니다. 이를 통해 유저를 식별하고, 통합할 수 있습니다.
유저의 속성을 업데이트 할 수 있습니다.
DFINERY에 적재되어 있는 유저의 이벤트 및 행동 데이터를 추출할 수 있습니다.
DFINERY는 API 토큰을 통해 사용자가 보낸 요청이 인증된 요청인지 판단합니다. 모든 API 요청의 헤더에는 API 토큰이 필수로 포함되어야 합니다. API 토큰은 디파이너리 콘솔을 통해 발급 받을 수 있습니다.
DFINERY의 API 토큰은 Import API, Export API 토큰으로 나뉘어 있습니다. Import API 토큰은 주로 디파이너리에 고객사의 데이터를 전송할 때 사용합니다 (Event, Identity, Profile API). Export API 토큰은 주로 고객사가 디파이너리에 적재되어 있는 데이터를 추출할 때 사용합니다 (Export API).
디파이너리 콘솔에 로그인 후 좌측 메뉴의 서비스 관리
에 들어가시면 Key 정보
에서 API 토큰
을 확인할 수 있습니다 (서비스 관리
> Key 정보
> API 토큰
).
토큰 발급 / 재발급 / 삭제는 서비스 관리자만이 가능합니다.
API 토큰은 서비스 생성 시 자동 발급되며 재발급만이 가능합니다.
Import API 토큰은 요청 헤더에 access_token
값을 추가하여 사용할 수 있습니다.
Emport API 토큰은 요청 헤더에 Authorization
값을 추가하여 사용할 수 있습니다.
DFINERY에서는 서비스 별 1개의 API 토큰만 발급이 가능합니다. 만약 토큰을 변경하고 싶을 때는 재발급 버튼을 통해 변경이 가능합니다 (서비스 관리
> Key 정보
> API 토큰
> 재발급
).
재발급 시 기존 토큰은 2주 동안만 사용이 가능합니다. 2주 내에 재발급한 토큰으로 변경해 주세요.
토큰 관련 응답 코드 및 공통 에러 및 코드는 Response 탭을 참고해 주시면 됩니다.
요청 제한은 시간 단위당 API 호출 횟수 제한을 의미합니다. DFINERY는 안정적인 서비스 운영을 위해 제공하는 모든 Open API에 요청 제한 정책을 적용합니다.
1분당 1,000,000건
1분당 10,000건
1분당 10,000건
1시간당 100건, 동시간 5건
요청 제한을 초과하면 이후의 API 요청은 모두 실패합니다. 제한 시간이 지나 요청 제한이 초기화된 후 정상 응답을 받을 수 있습니다. API 연동 시 요청 제한을 고려하여 연동하는 것이 좋습니다.
기본으로 제공되는 요청 제한보다 많은 호출이 필요하다면 고객 성공팀에 문의 부탁드립니다.
요청 제한 현황은 응답 헤더의 값을 통해 확인할 수 있습니다.
X-Rate-Limit-Limit
초기화 주기
X-Rate-Limit-Remaining
남은 요청 횟수
X-Rate-Limit-Reset
발송 속도가 초기화되는 시간
X-Rate-Limit-Limit 은 1y: 1년, 1M: 1개월, 1d: 1일, 1H: 1시간, 1m: 1분, 1s: 1초
로 구성됩니다.
X-Rate-Limit-Rest 은 Timestamp 형식입니다. 1719397769