1 of 9

Import API

Event

POST: 이벤트 적재

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

이벤트 정보

common

필드명

필수값 여부

타입

설명

필수

Object

유저 식별자

identity

유저 식별자 정보입니다. 아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.

필드명

필수값 여부

타입

설명

external_id

선택

String

외부 ID

phone_no

선택

String

전화 번호

email

선택

String

이메일

kakao_user_id

선택

String

카카오 ID

line_user_id

선택

String

라인 ID

events

필드명

필수값 여부

타입

설명

event_log_id

필수

String

이벤트 식별 ID, UUID Format, xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

event_name

필수

String

이벤트명

event_datetime

필수

Datetime

이벤트 발생 시각

선택

Array of Object

상품 정보

선택

Object

이벤트 속성

event_items

이벤트 아이템 속성입니다. 필드명은 콘솔에서 사전 등록된 아이템(df_item) 의 하위 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다. 이벤트 아이템은 한번에 최대 100개까지 적재 가능합니다.

필드명

필수값 여부

타입

설명

${your-df-item-property-key}

선택

String, Long, Double, Boolean, Datetime, Array

사전 등록된 이벤트 아이템 속성 정보

event_properties

이벤트 속성입니다. 필드명은 아이템(df_item) 을 제외한 콘솔에서 사전 등록된 이벤트 속성의 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다.

이름

필수값 여부

타입

설명

${your-event-property-key}

선택

String, Long, Double, Boolean, Datetime, Array

사전 등록된 이벤트 속성 정보

요청 예시

curl -L \
  -X POST \
  -H 'access_token: ${your-import-api-token}' \
  -H 'Content-Type: application/json' \
  'https://openapi.dfinery.ai/api/v1/events?service_id=${your-service-id}' \
  -d '{
  "common": {
    "identity": {
      "external_id": "dfn-user-123",
      "email": "dfn@gmail.com"
    }
  },
  "events": [
    {
      "event_log_id": "b0c9cf18-f3c0-4879-bb2e-92c65858dabc",
      "event_name": "df_login",
      "event_datetime": "2024-06-24T06:01:48.501Z",
      "event_properties": null,
      "event_items": null
    },
    {
      "event_log_id": "464bc021-9c56-481e-8ee8-3bf06de7c418",
      "event_name": "df_purchase",
      "event_datetime": "2024-06-24T06:42:25.394Z",
      "event_properties": {
        "df_order_id": "dwtfmoe",
        "df_delivery_charge": 1000,
        "df_payment_method": "card",
        "df_total_purchase_amount": 4000
      },
      "event_items": [
        {
          "df_item_id": "1",
          "df_item_name": "item1",
          "df_price": 3000,
          "df_quantity": 1,
          "df_discount": 0
        }
      ]
    }
  ]
}'

응답

정상 응답

Content-Type: application/json
access_token: ${your-api-token}
{
  "status": true,
  "code": "20000",
  "message": "OK",
  "data": true
}

실패 응답

자세한 내용은 상세 응답 참고하시면 됩니다.

40402 TOO_MANY_EVENTS

이벤트 수가 100개를 초과하거나, 이벤트 아이템 수가 100개를 초과한 경우입니다.

Content-Type: application/json
access_token: ${your-api-token}
{
  "status": false,
  "code": "40402",
  "message": "TOO_MANY_EVENTS",
  "data": true
}

Identity

POST: 통합 프로필 생성 및 업데이트

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

identity

유저 식별 정보입니다. 아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.

필드명

필수값 여부

타입

설명

external_id

선택

String

외부 ID

phone_no

선택

String

전화 번호

email

선택

String

이메일

kakao_user_id

선택

String

카카오 ID

line_user_id

선택

String

라인 ID

요청 예시

curl -L \
  -X POST \
  -H 'access_token: ${your-import-api-token}' \
  -H 'Content-Type: application/json' \
  'https://openapi.dfinery.ai/api/v1/identities?service_id=${your-service-id}' \
  -d '{
   "identity":{
      "external_id": "dfn-user-123",
      "email": "dfn@gmail.com",
      "phone_no": "821012345678"
   },
   "request_datetime":"2024-06-24T06:01:48.501Z"
  }
 '

응답

정상 응답

Content-Type: application/json
access_token: text
{
  "status": true,
  "code": "20000",
  "message": "OK",
  "data": true
}

실패 응답

자세한 내용은 상세 응답 참고하시면 됩니다.

Profile

시작하기

Profile API를 통해 유저의 속성을 생성하거나 업데이트 할 수 있습니다. API 연동을 위해서는 먼저 기본 세팅을 완료하여야 합니다. API 연동을 위한 기본 세팅을 아직 하지 못했다면, 시작하기 전에 를 참고해 주시면 됩니다.

유저 속성 생성 및 업데이트 API를 통해 온/오프라인 채널에 대한 유저의 수신 동의 정보 값을 설정할 수 있습니다.

오후 9시 부터 오전 8시 사이에는 별도의 수신 동의를 받아야 광고성 알림을 전송할 수 있습니다.

알림 수신 동의 정보에 대한 유저 프로필은 예외적으로 DFINERY에서 서비스 생성 시 이미 자동으로 등록되어 있어 DFINERY 콘솔에서 설정하지 않아도 설정이 가능합니다.

수신 동의 정보는 기본값을 통해 따로 설정하지 않아도 발송될 수 있습니다. 자세한 사항은 이용자 가이드의 를 참고하시면 됩니다.

POST: 유저 속성 생성 및 업데이트

POST /api/v1/user-profile

고객의 유저 속성을 생성 및 업데이트할 수 있는 API입니다.

유저 속성의 생성 및 업데이트 API 호출은 유저의 속성의 변경 시점에만 호출하는 것이 좋습니다. 연동 시에는 항상 을 고려해야 합니다.

쿼리 파라미터

이름

필수값 여부

타입

설명

헤더

필드명

필수값 여부

타입

값

설명

요청 본문

필드명

필수값 여부

타입

설명

identity

유저 식별자 정보입니다. 아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.

필드명

필수값 여부

타입

설명

user_properties

유저 속성입니다. 필드명은 콘솔에서 사전 등록된 유저 속성의 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다.

요청 예시

응답

정상 응답

실패 응답

상세 응답

DFINERY Import API는 HTTP 응답 코드와 상세 응답 코드를 통해 요청의 성공과 실패를 판단합니다. HTTP 응답 코드가 200 이더라도, 요청은 실패할 수 있습니다.

HTTP 응답 코드

응답 코드

설명

200 - OK

서버에서 정상적으로 요청을 받았습니다.

400 - Bad Request

요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 요청 파라미터를 확인해 주세요.

429 - Too Many Requests

비정상적으로 많은 요청을 보냈습니다. 잠시 후 다시 시도해 주세요.

500 - Server Error

서버 내부에서 에러가 발생했습니다

상세 응답 코드

API 호출이 실패한 경우, 상세 응답 코드를 통해 오류에 대해 상세한 정보를 얻을 수 있습니다.

응답 코드

code

message

설명

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

서버 내부 에러 발생

응답 예시

20000 OK

200 OK
{
  "status": true,
  "code": 20000,
  "message": "OK",
  "data": null 
}

40001 VALIDATION_FAILURE

200 OK
{
  "status": false,
  "code": 40001,
  "message": "VALIDATION_FAILURE",
  "data": null 
}

50000 INTERNAL_SERVER_ERROR

200 OK
{
  "status": false,
  "code": 50000,
  "message": "INTERNAL_SERVER_ERROR",
  "data": null 
}

상세 응답

HTTP 응답 코드

응답 코드

설명

200 - OK

서버에서 정상적으로 요청을 받았습니다.

400 - Bad Request

429 - Too Many Requests

비정상적으로 많은 요청을 보냈습니다. 잠시 후 다시 시도해 주세요.

500 - Server Error

서버 내부에서 에러가 발생했습니다

상세 응답 코드

API 호출이 실패한 경우, 상세 응답 코드를 통해 오류에 대해 상세한 정보를 얻을 수 있습니다.

응답 코드

code

message

설명

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

서버 내부 에러 발생

응답 예시

20000 OK

200 OK
{
  "status": true,
  "code": 20000,
  "message": "OK",
  "data": null 
}

40001 VALIDATION_FAILURE

200 OK
{
  "status": false,
  "code": 40001,
  "message": "VALIDATION_FAILURE",
  "data": null 
}

50000 INTERNAL_SERVER_ERROR

200 OK
{
  "status": false,
  "code": 50000,
  "message": "INTERNAL_SERVER_ERROR",
  "data": null 
}

POST: 통합 프로필 생성 및 업데이트

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

identity

유저 식별 정보입니다. 아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.

필드명

필수값 여부

타입

설명

external_id

선택

String

외부 ID

phone_no

선택

String

전화 번호

email

선택

String

이메일

kakao_user_id

선택

String

카카오 ID

line_user_id

선택

String

라인 ID

요청 예시

curl -L \
  -X POST \
  -H 'access_token: ${your-import-api-token}' \
  -H 'Content-Type: application/json' \
  'https://openapi.dfinery.ai/api/v1/identities?service_id=${your-service-id}' \
  -d '{
   "identity":{
      "external_id": "dfn-user-123",
      "email": "dfn@gmail.com",
      "phone_no": "821012345678"
   },
   "request_datetime":"2024-06-24T06:01:48.501Z"
  }
 '

응답

정상 응답

Content-Type: application/json
access_token: text
{
  "status": true,
  "code": "20000",
  "message": "OK",
  "data": true
}

실패 응답

자세한 내용은 상세 응답 참고하시면 됩니다.

POST: 이벤트 적재

POST /api/v1/events

이벤트 적재 API를 통해 하나 혹은 여러 이벤트를 한번에 적재할 수 있습니다. 적재하고자 하는 이벤트는 콘솔에서 사전 등록되어 있어야 합니다.

한번의 요청에서 최대 100개의 이벤트를 적재할 수 있습니다. 또한, 한번의 요청에서 최대 100개의 이벤트 아이템을 적재할 수 있습니다.

쿼리 파라미터

이름

필수값 여부

타입

설명

service_id

필수

String

서비스 ID

헤더

필드명

필수값 여부

타입

값

설명

Content-Type

필수

String

application/json

access_token

필수

String

your-api-token-key

API 인증 토큰

요청 본문

필드명

필수값 여부

타입

설명

필수

Object

이벤트 적재를 위한 공통 속성

필수

Array of Object

이벤트 정보

common

필드명

필수값 여부

타입

설명

필수

Object

유저 식별자

identity

유저 식별자 정보입니다. 아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.

필드명

필수값 여부

타입

설명

external_id

선택

String

외부 ID

phone_no

선택

String

전화 번호

email

선택

String

이메일

kakao_user_id

선택

String

카카오 ID

line_user_id

선택

String

라인 ID

events

이벤트 정보입니다. 적재하고자 하는 이벤트는 콘솔에서 사전 등록되어 있어야 합니다. 표준 이벤트와 이벤트 속성에 대한 자세한 내용은 사용자 가이드의 를 참고해 주시면 됩니다.

필드명

필수값 여부

타입

설명

event_log_id

필수

String

이벤트 식별 ID, UUID Format, xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

event_name

필수

String

이벤트명

event_datetime

필수

Datetime

이벤트 발생 시각

선택

Array of Object

상품 정보

선택

Object

이벤트 속성

event_items

필드명

필수값 여부

타입

설명

${your-df-item-property-key}

선택

String, Long, Double, Boolean, Datetime, Array

사전 등록된 이벤트 아이템 속성 정보

event_properties

이름

필수값 여부

타입

설명

${your-event-property-key}

선택

String, Long, Double, Boolean, Datetime, Array

사전 등록된 이벤트 속성 정보

요청 예시

curl -L \
  -X POST \
  -H 'access_token: ${your-import-api-token}' \
  -H 'Content-Type: application/json' \
  'https://openapi.dfinery.ai/api/v1/events?service_id=${your-service-id}' \
  -d '{
  "common": {
    "identity": {
      "external_id": "dfn-user-123",
      "email": "dfn@gmail.com"
    }
  },
  "events": [
    {
      "event_log_id": "b0c9cf18-f3c0-4879-bb2e-92c65858dabc",
      "event_name": "df_login",
      "event_datetime": "2024-06-24T06:01:48.501Z",
      "event_properties": null,
      "event_items": null
    },
    {
      "event_log_id": "464bc021-9c56-481e-8ee8-3bf06de7c418",
      "event_name": "df_purchase",
      "event_datetime": "2024-06-24T06:42:25.394Z",
      "event_properties": {
        "df_order_id": "dwtfmoe",
        "df_delivery_charge": 1000,
        "df_payment_method": "card",
        "df_total_purchase_amount": 4000
      },
      "event_items": [
        {
          "df_item_id": "1",
          "df_item_name": "item1",
          "df_price": 3000,
          "df_quantity": 1,
          "df_discount": 0
        }
      ]
    }
  ]
}'

응답

정상 응답

Content-Type: application/json
access_token: ${your-api-token}
{
  "status": true,
  "code": "20000",
  "message": "OK",
  "data": true
}

실패 응답

자세한 내용은 상세 응답 참고하시면 됩니다.

40402 TOO_MANY_EVENTS

이벤트 수가 100개를 초과하거나, 이벤트 아이템 수가 100개를 초과한 경우입니다.

Content-Type: application/json
access_token: ${your-api-token}
{
  "status": false,
  "code": "40402",
  "message": "TOO_MANY_EVENTS",
  "data": true
}

Import API

Event

POST: 이벤트 적재

쿼리 파라미터

헤더

요청 본문

common

identity

events

event_items

event_properties

요청 예시

응답

정상 응답

실패 응답

40402 TOO_MANY_EVENTS

Identity

POST: 통합 프로필 생성 및 업데이트

쿼리 파라미터

헤더

요청 본문

identity

요청 예시

응답

정상 응답

실패 응답

Profile

시작하기

사용 사례

알림 수신 동의 정보 설정하기

POST: 유저 속성 생성 및 업데이트

쿼리 파라미터

헤더

요청 본문

identity

user_properties

요청 예시

응답

정상 응답

실패 응답

상세 응답

HTTP 응답 코드

상세 응답 코드

응답 예시

20000 OK

40001 VALIDATION_FAILURE

50000 INTERNAL_SERVER_ERROR

상세 응답

HTTP 응답 코드

상세 응답 코드

응답 예시

20000 OK

40001 VALIDATION_FAILURE

50000 INTERNAL_SERVER_ERROR

POST: 통합 프로필 생성 및 업데이트

쿼리 파라미터

헤더

요청 본문

identity

요청 예시

응답

정상 응답

실패 응답

Event

POST: 이벤트 적재

쿼리 파라미터

헤더

요청 본문

common

identity

events

event_items

event_properties

요청 예시

응답

정상 응답

실패 응답

40402 TOO_MANY_EVENTS

시작하기

사용 사례