데이터 내보내기

캠페인의 유저 단위 원본 이벤트와 시나리오 일별 성과 요약을 API로 내려받는 방법을 설명합니다. 블럭스 담당 매니저에게 발급받은 secret key를 사용합니다.

개요

블럭스 콘솔의 데이터 다운로드 버튼과 같은 파일을 API로 받을 수 있습니다. 캠페인은 유저별 발송·수신·오픈·전환 등의 원본 이벤트를 CSV로, 시나리오는 일별 성과 요약을 xlsx로 제공합니다.

파일을 내려받는 과정은 세 단계입니다.

생성 API를 호출하여 내보내기 작업을 만듭니다.
응답의 _id로 조회 API를 반복 호출합니다. status가 completed 또는 failed가 될 때까지 5초 이상 간격으로 상태를 확인하세요.
status가 completed이면 응답의 download_url로 파일을 내려받습니다.

파일 생성에는 보통 수십 초에서 수 분이 걸립니다. status가 failed이면 새 작업을 만드세요. 실패가 반복되면 담당 매니저에게 문의하세요.

생성 API

엔드포인트

POST https://api.blux.ai/prod/v2/applications/{APPLICATION_ID}/export-jobs

인증

요청할 때 Authorization 헤더에 발급받은 secret key를 포함하세요. 키 발급과 사용 방법은 인증 키를 참고하세요.

Authorization: {SECRET_KEY}
Content-Type: application/json

요청 본문

type에 따라 다음 두 형식 중 하나를 사용합니다.

캠페인 원본 이벤트

필드	타입	설명
`type`	`string`	(필수) `campaign_event_data`를 지정합니다.
`campaign_id`	`string`	(필수) 데이터를 내보낼 캠페인 ID입니다.
`from`	`string` (ISO 8601)	(선택) 시작 날짜입니다. 애플리케이션의 시간대로 변환한 날짜의 00:00부터 포함합니다. 생략하면 시작 날짜를 제한하지 않습니다.
`to`	`string` (ISO 8601)	(선택) 종료 날짜입니다. 애플리케이션의 시간대로 변환한 날짜 전체를 포함합니다. 생략하면 종료 날짜를 제한하지 않습니다.

from과 to는 애플리케이션에 설정한 시간대(timezone) 기준으로 날짜를 해석합니다. from 날짜의 00:00 이상, to 다음 날의 00:00 미만에 발송 예약된 회차를 선택합니다. 예를 들어 시간대가 Asia/Seoul일 때 from을 2026-09-01T00:00:00+09:00, to를 2026-09-07T00:00:00+09:00으로 지정하면, 9월 1일부터 9월 7일까지의 회차를 포함합니다.

두 필드를 모두 생략하면 캠페인의 모든 회차를 대상으로 합니다. 지정한 범위에서 성과 집계가 끝난 회차만 파일에 담습니다.

기간은 이벤트 발생 시각이 아닌 회차의 발송 예약 시각을 기준으로 적용합니다. 선택한 회차의 오픈·클릭·전환 이벤트는 캠페인에 설정한 전환 기한까지 조회하므로, 이벤트 발생 시각이 to 날짜 이후일 수 있습니다.

시나리오 일별 성과 요약

필드	타입	설명
`type`	`string`	(필수) `scenario_daily_metrics`를 지정합니다.
`scenario_id`	`string`	(필수) 데이터를 내보낼 시나리오 ID입니다.
`from`	`string` (ISO 8601)	(필수) 시작 날짜입니다. 애플리케이션의 시간대로 변환한 날짜의 00:00부터 포함합니다.
`to`	`string` (ISO 8601)	(필수) 종료 날짜입니다. 애플리케이션의 시간대로 변환한 날짜 전체를 포함합니다.

시나리오도 시작 날짜와 종료 날짜를 모두 포함합니다. from 날짜의 00:00부터 to 다음 날의 00:00 직전까지를 일 단위로 집계합니다. 예를 들어 Asia/Seoul 기준으로 9월 1일부터 9월 7일까지 받으려면, 캠페인 예시와 동일하게 from을 2026-09-01T00:00:00+09:00, to를 2026-09-07T00:00:00+09:00으로 지정하세요.

받게 될 xlsx 파일의 시트 구성과 컬럼은 시나리오 xlsx 시트에서 설명합니다.

조회 API

엔드포인트

GET https://api.blux.ai/prod/v2/applications/{APPLICATION_ID}/export-jobs/{EXPORT_JOB_ID}

EXPORT_JOB_ID에는 생성 API가 반환한 _id를 넣습니다. 생성 API와 동일하게 Authorization 헤더에 해당 애플리케이션의 secret key를 포함하세요.

응답

생성 API와 조회 API는 같은 형식의 작업 정보를 반환합니다. 생성 직후에는 status가 triggered이며, 조회 API로 처리 결과를 확인할 수 있습니다.

필드 설명

필드	타입	설명
`_id`	`string`	내보내기 작업 ID입니다. 조회 API의 `EXPORT_JOB_ID`로 사용합니다.
`application_id`	`string`	작업이 속한 애플리케이션 ID입니다.
`type`	`string`	`campaign_event_data` 또는 `scenario_daily_metrics`입니다.
`status`	`string`	`triggered`: 생성 요청을 접수했습니다. `processing`: 파일을 생성합니다. `completed`: 파일 생성이 끝났습니다. `failed`: 파일 생성에 실패했습니다.
`campaign_id`	`string`	캠페인 ID입니다. `type`이 `campaign_event_data`일 때 반환합니다.
`scenario_id`	`string`	시나리오 ID입니다. `type`이 `scenario_daily_metrics`일 때 반환합니다.
`from`	`string` (ISO 8601)	요청한 시작 일시입니다. 캠페인 요청에서 생략했다면 응답에도 포함하지 않습니다.
`to`	`string` (ISO 8601)	요청한 종료 일시입니다. 캠페인 요청에서 생략했다면 응답에도 포함하지 않습니다.
`file_name`	`string`	확장자를 제외한 파일 이름입니다.
`file_ext`	`string`	캠페인은 `csv`, 시나리오는 `xlsx`입니다.
`file_size`	`number`	파일 크기입니다. 단위는 바이트입니다.
`download_url`	`string`	파일을 내려받을 URL입니다. URL 생성 후 24시간 동안 유효합니다.
`download_url_expires_at`	`string` (ISO 8601)	다운로드 URL의 만료 일시입니다.
`created_at`	`string` (ISO 8601)	작업 생성 일시입니다.
`updated_at`	`string` (ISO 8601)	작업 정보의 마지막 갱신 일시입니다.

파일 관련 필드(file_name, file_ext, file_size, download_url, download_url_expires_at)는 status가 completed일 때만 채워집니다. 응답의 일시 필드는 UTC 기준 ISO 8601 문자열로 반환합니다.

다운로드 URL이 만료되면 새 작업을 만드세요. 기존 작업의 상태를 다시 조회해도 URL의 유효 기간은 연장되지 않습니다.

응답 예시

완료된 캠페인 내보내기 작업을 조회한 예시입니다. download_url은 예시용 값입니다.

{
  "_id": "66de9133e2c8a8f0c9a1b2c5",
  "application_id": "664cb3d2e2c8a8f0c9a1b2c1",
  "type": "campaign_event_data",
  "status": "completed",
  "campaign_id": "664cb3d2e2c8a8f0c9a1b2c3",
  "from": "2026-08-31T15:00:00.000Z",
  "to": "2026-09-06T15:00:00.000Z",
  "file_name": "9월 신상 알림 (09.01~09.07)",
  "file_ext": "csv",
  "file_size": 245760,
  "download_url": "https://example.com/export.csv?signature=EXAMPLE",
  "download_url_expires_at": "2026-09-10T01:01:00.000Z",
  "created_at": "2026-09-09T01:00:00.000Z",
  "updated_at": "2026-09-09T01:01:00.000Z"
}

캠페인 CSV 컬럼

한 행은 유저 한 명의 이벤트 하나를 나타냅니다. 회차마다 task_id, scheduled_at, group으로 구분합니다. 발송·수신·실패·대조군 배정 행(이하 발송 기록 행)은 발송 기록(notification)을 바탕으로, 오픈·클릭·전환 행은 이벤트 기록을 바탕으로 만듭니다.

컬럼	설명
`task_id`	발송 회차 ID입니다.
`scheduled_at`	회차의 발송 예약 시각입니다. 애플리케이션의 시간대를 적용한 `YYYY-MM-DD HH:mm:ss` 형식입니다.
`group`	A/B 테스트의 그룹명입니다. 발송군은 `그룹A`, `그룹B` 등으로, 대조군은 `대조군`으로 표시합니다. A/B 테스트가 아니거나 그룹을 확인할 수 없으면 빈 값입니다.
`event_type`	이벤트 타입입니다. 발송 시도는 `message_sent`, 수신 성공은 `message_received`, 발송 실패는 `message_failed`, 대조군 배정은 `control_assigned`입니다. 오픈·클릭·전환 이벤트는 아래 설명의 이벤트 타입을 유지합니다.
`user_id`	고객사가 지정한 유저 ID입니다. 연결된 유저 ID가 없으면 빈 값입니다.
`blux_user_id`	블럭스가 부여한 유저 ID입니다. 발송 기록에 연결된 유저가 없으면 빈 값입니다.
`captured_at`	이벤트 발생 시각입니다. 발송 행과 대조군 배정 행은 발송 기록의 생성 시각, 수신 행은 수신 성공 시각, 실패 행은 실패가 확인된 시각을 사용합니다. 애플리케이션의 시간대를 적용한 `YYYY-MM-DD HH:mm:ss` 형식입니다.
`channel`	발송 채널입니다. `app_push`, `alimtalk`, `friendtalk`, `brand_message`, `sms`, `rcs`, `email` 등이며, 대조군 배정 행은 `control`입니다. 발송 기록 행에만 값이 있습니다.
`error_code`	발송 실패 코드입니다. `message_failed` 행에만 값이 있습니다.
`error_message`	발송 실패 상세 메시지입니다. `message_failed` 행에만 값이 있습니다. 발송사가 전달한 원문이라 형식이 정해져 있지 않고, 길거나 줄바꿈을 포함할 수 있습니다. 자동 처리에는 `error_code`를 사용하세요.
`event_properties`	이벤트의 기본 속성을 JSON 문자열로 담습니다. 발송 기록 행은 `{}`입니다.
`custom_event_properties`	이벤트의 커스텀 속성을 JSON 문자열로 담습니다. 값이 없으면 빈 값이며, 발송 기록 행은 `{}`입니다.
`internal_event_properties`	이벤트의 내부 속성을 JSON 문자열로 담습니다. 값이 없으면 빈 값이며, 발송 기록 행은 `{}`입니다.

발송군의 발송 기록 하나마다 message_sent 행이 하나 있고, 결과가 확정된 기록에는 message_received 또는 message_failed 행이 하나 더 붙습니다. message_sent는 발송 시도이며 수신 성공을 의미하지 않습니다. 결과 행이 없는 기록은 발송 결과가 확정되지 않은 경우입니다. 발송 성공률은 유저별로 message_sent와 message_failed 행을 세어 계산할 수 있습니다.

대조군 유저는 메시지를 받지 않으므로 발송 기록마다 control_assigned 행 하나만 있습니다.

오픈·클릭·전환 행의 이벤트 타입은 다음과 같습니다.

오픈에 해당하는 이벤트 타입은 채널에 따라 push_opened, friendtalk_button_clicked, alimtalk_button_clicked, brandmessage_button_clicked, email_link_clicked, sms_link_clicked, rcs_link_clicked 등입니다.
랜딩 클릭 이벤트 타입은 landing_clicked입니다.
전환 이벤트 타입은 캠페인에 설정한 전환 이벤트 타입입니다. 예를 들어 purchase를 설정했다면, 전환 판정 조건을 통과한 이벤트의 타입을 purchase로 표시합니다.

CSV 파일은 BOM이 없는 UTF-8 형식입니다. 엑셀에서 파일을 바로 열면 한글이 깨질 수 있습니다. 엑셀의 데이터 가져오기 기능으로 CSV를 선택하고 인코딩을 UTF-8로 지정하세요.

시나리오 xlsx 시트

파일은 성과 요약 시트 한 장과, 메시지 노드마다 한 장씩 만드는 일별 성과 시트로 구성합니다. 메시지 노드만 담으므로 분기·대기·조건 노드는 시트에 나타나지 않습니다.

성과 요약 시트

첫 번째 시트입니다. 한 행이 메시지 노드 하나를 나타내고, 요청한 기간 전체를 합산한 값을 담습니다.

컬럼	설명
#	시나리오 흐름 순서대로 매긴 번호입니다. 일별 성과 시트의 이름에 같은 번호를 씁니다.
채널	노드의 발송 채널입니다. 앱푸시·알림톡·친구톡·브랜드 메시지·SMS·RCS·이메일 중 하나입니다.
A/B 테스트 분기	노드가 속한 A/B 테스트 분기입니다. 분기가 중첩되면 `B·A`처럼 상위 분기부터 이어 붙입니다. 분기 밖이거나 분기가 합류한 뒤의 노드는 빈 값입니다.
메시지 노드 ID	노드 ID입니다. 일별 성과 시트의 제목 아래에도 같은 값을 적습니다.

다섯 번째 열부터는 아래 성과 지표를 같은 순서로 이어 붙입니다.

일별 성과 시트

메시지 노드마다 한 장씩 만듭니다. 시트 이름은 #1 알림톡처럼 요약 시트의 번호·채널·분기를 붙여 짓습니다. 한 행이 하루를 나타냅니다.

컬럼	설명
날짜	애플리케이션의 시간대를 적용한 `YYYY-MM-DD` 형식입니다.

두 번째 열부터는 아래 성과 지표를 같은 순서로 이어 붙입니다. 발송이 없던 날은 행을 만들지 않으므로, 기간 안의 모든 날짜가 나오지는 않습니다.

성과 지표

두 시트가 공통으로 쓰는 열입니다. 건 단위는 중복을 포함한 횟수이고, 명 단위는 유저 기준으로 중복을 제거한 수입니다.

컬럼	설명
발송 수(건), 발송 수(명)	수신에 성공한 횟수와 유저 수입니다. 발송을 시도한 수가 아니라 수신 성공을 센 값이므로, 실패한 발송은 빠집니다.
오픈 수(건), 오픈 수(명)	메시지를 열거나 메시지 안 링크·버튼을 누른 횟수와 유저 수입니다.
오픈율(건), 오픈율(명)	오픈 수를 발송 수로 나눈 비율입니다. 건은 건끼리, 명은 명끼리 나눕니다.
전환 수(건), 전환 수(명)	오픈한 유저가 전환 기한 안에 전환 이벤트를 일으킨 횟수와 유저 수입니다.
전환율(건), 전환율(명)	전환 수를 오픈 수로 나눈 비율입니다. 발송 수로 나눈 값이 아닙니다.
전환 수익	전환 이벤트에 담긴 결제 금액의 합입니다. 원화(KRW) 결제만 더합니다.
집행 비용	해당 노드의 발송에 든 비용입니다.
ROAS	전환 수익을 집행 비용으로 나눈 비율입니다.
객단가	전환 수익을 전환 수(건)로 나눈 값입니다.
CAC	집행 비용을 전환 수(건)로 나눈 값입니다.

전환은 오픈에 기여한 것으로 판정한 건만 셉니다. 메시지를 받았지만 열지 않은 유저의 구매는 전환 수에 들어가지 않습니다. 비율과 나눗셈 열은 분모가 0이면 0으로 채웁니다.

제한 사항

생성 API는 애플리케이션당 10분에 10회까지 호출할 수 있습니다. 한도를 초과하면 429 Too Many Requests와 Retry-After 헤더를 반환합니다. 헤더에 표시한 초 단위 대기 시간이 지난 뒤 다시 요청하세요.
캠페인의 선택 범위에서 성과 집계가 끝난 회차의 발송 합이 2,000,000건을 넘거나 회차 수가 120개를 넘으면 400 Bad Request를 반환합니다. 오류 코드는 LimitExceeded입니다. 기간을 좁혀 여러 작업으로 나누어 요청하세요. A/B 테스트는 그룹마다 회차를 별도로 셉니다.
캠페인의 선택 범위에 성과 집계가 끝난 회차가 없으면 400 Bad Request를 반환합니다. 오류 코드는 ResourceNotReady입니다. 집계가 끝난 후 다시 요청하세요.
작업 상태가 failed이면 새 작업을 만드세요. 실패가 반복되면 작업 ID와 함께 담당 매니저에게 문의하세요.

상태 코드

코드	설명
`200 OK`	작업 생성 또는 조회에 성공했습니다. 파일 생성 완료 여부는 `status`로 확인하세요.
`400 Bad Request`	필수 파라미터 누락이나 요청 형식 오류입니다.
`400 Bad Request`	인증 실패입니다. secret key가 없거나 올바르지 않거나 다른 애플리케이션의 키를 사용했습니다. 오류 코드는 `UnAuthorized`입니다.
`400 Bad Request`	애플리케이션, 캠페인, 시나리오 또는 내보내기 작업을 찾을 수 없습니다. 오류 코드는 `ResourceNotFound`입니다.
`400 Bad Request`	캠페인 내보내기 범위의 발송 합 또는 회차 수가 한도를 초과했습니다. 오류 코드는 `LimitExceeded`입니다.
`400 Bad Request`	캠페인 내보내기 범위에 성과 집계가 끝난 회차가 없습니다. 오류 코드는 `ResourceNotReady`입니다.
`429 Too Many Requests`	생성 API의 호출 한도를 초과했습니다. `Retry-After` 헤더를 확인하세요.
`500 Internal Server Error`	서버 내부 오류입니다.

테스트 예시

캠페인 전체 기간의 작업 생성

curl -X POST "https://api.blux.ai/prod/v2/applications/{APPLICATION_ID}/export-jobs" \
  -H "Authorization: {SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "campaign_event_data",
    "campaign_id": "664cb3d2e2c8a8f0c9a1b2c3"
  }'

캠페인 기간을 지정한 작업 생성

다음 예시는 애플리케이션의 시간대가 Asia/Seoul인 경우입니다.

curl -X POST "https://api.blux.ai/prod/v2/applications/{APPLICATION_ID}/export-jobs" \
  -H "Authorization: {SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "campaign_event_data",
    "campaign_id": "664cb3d2e2c8a8f0c9a1b2c3",
    "from": "2026-09-01T00:00:00+09:00",
    "to": "2026-09-07T00:00:00+09:00"
  }'

시나리오 작업 생성

시나리오는 from과 to를 모두 지정해야 합니다.

curl -X POST "https://api.blux.ai/prod/v2/applications/{APPLICATION_ID}/export-jobs" \
  -H "Authorization: {SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "scenario_daily_metrics",
    "scenario_id": "664cb3d2e2c8a8f0c9a1b2c4",
    "from": "2026-09-01T00:00:00+09:00",
    "to": "2026-09-07T00:00:00+09:00"
  }'

작업 상태 조회

curl "https://api.blux.ai/prod/v2/applications/{APPLICATION_ID}/export-jobs/{EXPORT_JOB_ID}" \
  -H "Authorization: {SECRET_KEY}"

자주 묻는 질문 (FAQ)

Q. 인앱 메시지도 내보낼 수 있나요? A. 이 API는 캠페인 원본 이벤트와 시나리오 일별 성과 요약을 제공합니다. 인앱 메시지 내보내기는 제공하지 않습니다.

Q. 완료된 작업의 파일을 다시 내려받을 수 있나요? A. 다운로드 URL 생성 후 24시간 이내에는 같은 URL로 다시 내려받을 수 있습니다. download_url_expires_at이 지나면 새 작업을 만드세요.

Q. 시나리오도 유저별 원본 이벤트를 받을 수 있나요? A. 시나리오는 일별 성과를 집계한 xlsx 파일을 제공합니다. 유저별 원본 이벤트 CSV는 캠페인에서 제공합니다.

추가 문의는 블럭스 담당 매니저에게 연락하세요.

개요​

생성 API​

엔드포인트​

인증​

요청 본문​

캠페인 원본 이벤트​

시나리오 일별 성과 요약​

조회 API​

엔드포인트​

응답​

필드 설명​

응답 예시​

캠페인 CSV 컬럼​

시나리오 xlsx 시트​

성과 요약 시트​

일별 성과 시트​

성과 지표​

제한 사항​

상태 코드​

테스트 예시​

캠페인 전체 기간의 작업 생성​

캠페인 기간을 지정한 작업 생성​

시나리오 작업 생성​

작업 상태 조회​

자주 묻는 질문 (FAQ)​

개요

생성 API

엔드포인트

인증

요청 본문

캠페인 원본 이벤트

시나리오 일별 성과 요약

조회 API

엔드포인트

응답

필드 설명

응답 예시

캠페인 CSV 컬럼

시나리오 xlsx 시트

성과 요약 시트

일별 성과 시트

성과 지표

제한 사항

상태 코드

테스트 예시

캠페인 전체 기간의 작업 생성

캠페인 기간을 지정한 작업 생성

시나리오 작업 생성

작업 상태 조회

자주 묻는 질문 (FAQ)