푸시 통계 API | Appbox 앱 설정 가이드
푸시 통계 API
푸시 통계 API는 앱의 푸시 발송, 열람, 전환 숫자를 귀사 서버로 가져가는 API입니다.
앱박스가 매일 새벽에 숫자를 만들어 두고, API는 만들어 둔 것을 꺼내 주기만 합니다.
하루 한 번 받아 귀사 DB에 저장하고, 귀사 화면은 저장한 데이터로 그리는 방식을 권장합니다.
| API | 주소 | 받는 것 |
|---|---|---|
| 하루 리포트 | GET /reports | 날짜별 발송, 열람, 전환, 구독자 숫자 |
| 캠페인 변경분 | GET /changes | 캠페인별로 보낸 날부터 7일 동안 쌓인 숫자 중 지난번 이후 바뀐 것 |
| 캠페인 상세 | GET /campaigns/{campaign_code} | 캠페인 하나의 OS별, 실패 사유별, 날짜별, 시간대별 숫자 |
사전 확인
- 콘솔 › 푸시 메시지 › API 설정에서 서버 IP 등록과 인증키 생성을 먼저 해야 합니다. 푸시 발송 API와 같은 IP, 인증키를 씁니다.
- 같은 화면의 "통계 API 사용"을 켜야 합니다. 모든 요금제에서 쓸 수 있습니다.
- 리포트는 켠 날부터 만들어집니다. 켠 날의 리포트는 다음 날 03:00(한국 시간) 이후에 받을 수 있습니다. 끄고 다시 켜면 다시 켠 날부터 받을 수 있습니다. 캠페인 통계도 켠 날 이후 보낸 캠페인만 받을 수 있습니다.
- 모든 날짜와 시각은 한국 시간(Asia/Seoul) 기준입니다.
인증과 주소
등록한 서버 IP에서 부를 때만 응답합니다. 인증키는 환경변수에 두고 코드에 직접 적지 않는 것을 권장합니다.
HTTP
1
GET https://api.appboxapp.com/api/v1/push/stats/reports
2
Authorization: Basic {Base64(AUTH_KEY:APP_PROJECT_ID)}
Bash
1
curl -u "$APPBOX_AUTH_KEY:$APPBOX_APP_PROJECT_ID" \
2
"https://api.appboxapp.com/api/v1/push/stats/reports?date=2026-11-02"
GET 외의 방식(POST 등)은 405, 없는 주소는 404로 답합니다.
요청
GET /reports)는 하루만 받을 때는 date, 여러 날을 한 번에 받을 때는 from, to를 보냅니다. 둘을 함께 쓸 수는 없습니다.
| Query 항목 | 필수 여부 | 설명 |
|---|---|---|
date | 조건부 | 받을 날짜 하루. YYYY-MM-DD 형식(예: 2026-11-02) |
from | 조건부 | 기간 시작일. to와 함께 보냅니다 |
to | 조건부 | 기간 마지막 날. 시작일부터 최대 31일까지 |
- 조회할 수 있는 날짜는 어제까지, 그리고 최근 13개월까지입니다.
- 어제 리포트는 03:00(한국 시간) 이후에 준비됩니다. 정각에 몰리지 않도록 03:00 이후 임의의 시각에 부르세요.
- 기간 조회는 며칠이든 1회로 셉니다. 처음 연동할 때 지난 기록은 31일씩 나눠 받으세요.
- 기간 안에 하루라도 리포트가 없으면 일부만 주지 않고 전체를 오류로 답합니다(아래 오류 코드 참고).
HTTP
1
GET /api/v1/push/stats/reports?date=2026-11-02
2
GET /api/v1/push/stats/reports?from=2026-10-01&to=2026-10-31
응답
code가 같습니다.
JSON
1
{
2
"success": true,
3
"code": 200,
4
"error_code": null,
5
"message": "OK",
6
"data": {
7
"app_project_code": "KVB-364446",
8
"timezone": "Asia/Seoul",
9
"reports": [ // 최근 날짜부터
10
{
11
"date": "2026-11-02",
12
"report_version": 1,
13
"built_at": "2026-11-03T01:04:12+09:00",
14
"sends": {
15
"campaigns": 1,
16
"targets": 3,
17
"success": 3,
18
"fail": 0,
19
"by_os": {
20
"android": { "success": 2, "fail": 0 },
21
"ios": { "success": 1, "fail": 0 }
22
},
23
"fail_reasons": {}
24
},
25
"opens": { "total": 0, "unique_devices": 0 },
26
"conversions": { "total": 0, "value_sum": 0 },
27
"audience": { "devices": 3, "receive_enabled": 3, "android": 2, "ios": 1 },
28
"campaigns_sent": [
29
{
30
"campaign_code": "PUSH-MVYPZ1I5-A2282B",
31
"name": "11월 혜택 안내",
32
"sent_at": "2026-11-02T12:48:58+09:00",
33
"is_ad": false,
34
"targets": 3,
35
"success": 3,
36
"fail": 0
37
}
38
],
39
"campaigns_sent_truncated": false
40
}
41
]
42
}
43
}
리포트 항목 정의
| 항목 | 설명 |
|---|---|
date | 리포트 날짜(한국 시간) |
report_version | 리포트 판. 앱박스가 오류를 바로잡아 다시 만들어 내용이 바뀐 경우에만 올라갑니다. 저장해 둔 판보다 크면 덮어쓰세요 |
built_at | 리포트를 만든 시각 |
sends.campaigns | 그날 보낸 캠페인 수 |
sends.targets / success / fail | 그날 발송 대상 수 / 성공 / 실패 |
sends.by_os | OS별 성공, 실패(android, ios). 2026-11-02 이전 기록이 섞인 날은 null |
sends.fail_reasons | 실패 사유별 건수(예: UNREGISTERED). 2026-11-02 이전 기록이 섞인 날은 null |
opens.total | 그날 열린 횟수. 그 전에 보낸 캠페인을 그날 연 것도 포함합니다 |
opens.unique_devices | 그날 연 기기 수. 기기 정보 없는 옛 기록이 섞인 날은 null |
conversions.total / value_sum | 그날 푸시로 생긴 전환 수 / 전환 금액 합계 |
audience | 그날 끝(다음 날 00:00) 기준 구독 기기 수, 수신 동의 수, OS별 기기 수(테스트 기기 제외). 사진이 없는 날은 null |
campaigns_sent | 그날 보낸 캠페인 목록(최대 200건). 테스트 발송, 무음 푸시, 사용자 여정 발송은 빠집니다 |
campaigns_sent_truncated | 캠페인이 200건을 넘어 목록이 잘렸으면 true |
응답 머리글(Header)
| Header | 설명 |
|---|---|
X-Quota-Limit | 하루 호출 한도(100) |
X-Quota-Remaining | 오늘 남은 횟수 |
X-Quota-Reset | 한도가 다시 차는 시각(Unix 초, 다음 날 00:00 한국 시간) |
Retry-After | 429, 503 응답일 때 다시 부르기까지 기다릴 초 |
응답에 새 항목이 예고 없이 더해질 수 있습니다. 모르는 항목은 무시하고 넘어가도록 만들어 주세요.
캠페인 변경분
change_seq)를 붙입니다.GET /changes는 지난번에 받은 번호(cursor) 뒤로 바뀐 캠페인만 번호 순으로 돌려줍니다. 7일이 지난 캠페인은 확정(finalized)되어 더 바뀌지 않습니다.
| Query 항목 | 필수 여부 | 설명 |
|---|---|---|
cursor | 필수 | 지난번 응답의 next_cursor. 처음이면 0 |
limit | 선택 | 한 번에 받을 캠페인 수. 1~500, 기본 200 |
- 새로 바뀐 캠페인은 매일 03:00(한국 시간) 이후에 공개됩니다. 하루 리포트와 같이 03:00 이후 임의의 시각에 한 번 부르세요.
has_more가true면next_cursor를cursor로 넣어 이어서 부르고, 마지막next_cursor를 귀사 DB에 저장합니다. 한 쪽(page)마다 1회로 셉니다.- 같은 캠페인이 숫자가 바뀔 때마다 다시 나옵니다.
campaign_code를 열쇠로 덮어쓰세요. - 캠페인을 저장한 뒤에
cursor를 저장하면 중간에 끊겨도 빠지는 캠페인이 없습니다. 같은 것을 다시 받으면 덮어쓰면 됩니다. - "통계 API 사용"을 켠 날 이후 보낸 캠페인만 나옵니다. 테스트 발송, 무음 푸시, 사용자 여정 발송은 나오지 않습니다.
HTTP
1
GET /api/v1/push/stats/changes?cursor=0
2
GET /api/v1/push/stats/changes?cursor=10&limit=500
JSON
1
{
2
"success": true,
3
"code": 200,
4
"error_code": null,
5
"message": "OK",
6
"data": {
7
"items": [ // change_seq 순
8
{
9
"campaign_code": "PUSH-MVYPZ1I5-A2282B",
10
"name": "11월 혜택 안내",
11
"sent_at": "2026-11-02T12:48:58+09:00",
12
"finalized": false,
13
"finalizes_on": "2026-11-09",
14
"targets": 3,
15
"success": 3,
16
"fail": 0,
17
"opens_total": 0,
18
"opens_unique": 0,
19
"opens_unique_provisional": true,
20
"conversions": 0,
21
"change_seq": 9
22
},
23
{
24
"campaign_code": "PUSH-MW06HTSA-E1766C",
25
"name": "주말 특가 알림",
26
"sent_at": "2026-11-03T13:19:14+09:00",
27
"finalized": false,
28
"finalizes_on": "2026-11-10",
29
"targets": 3,
30
"success": 3,
31
"fail": 0,
32
"opens_total": 1,
33
"opens_unique": 1,
34
"opens_unique_provisional": true,
35
"conversions": 0,
36
"change_seq": 10
37
}
38
],
39
"next_cursor": 10, // 다음에 cursor 로 보낼 값
40
"has_more": true
41
}
42
}
캠페인 항목 정의
| 항목 | 설명 |
|---|---|
campaign_code | 캠페인 코드. 발송 API 응답의 campaignCode, 하루 리포트 campaigns_sent[].campaign_code와 같은 값 |
name | 캠페인 이름 |
sent_at | 처음 보낸 시각 |
finalized | true면 보낸 지 7일이 지나 확정됨. 더 바뀌지 않습니다 |
finalizes_on | 확정되는 날. 이 날 03:00 이후 확정 값을 받을 수 있습니다 |
targets / success / fail | 발송 대상 수(성공 + 실패) / 성공 / 실패 |
opens_total | 보낸 날부터 7일 동안 열린 횟수 |
opens_unique | 연 기기 수. 기기 정보 없는 옛 열람이 섞이면 null |
opens_unique_provisional | true면 opens_unique가 임시 값(날마다 센 기기 수의 합: 여러 날 연 기기는 여러 번 셈). 확정할 때 정확히 다시 셉니다 |
conversions | 보낸 날부터 7일 동안 이 캠페인으로 생긴 전환 수 |
change_seq | 숫자가 바뀔 때마다 새로 붙는 번호 |
next_cursor | 다음에 cursor로 보낼 값. 받은 캠페인이 없으면 보낸 cursor 그대로 |
has_more | true면 아직 남은 캠페인이 있음 |
캠페인 상세
/changes의 캠페인 항목에 나눠 본 값이 더해집니다. 1회로 셉니다.
| Path 항목 | 필수 여부 | 설명 |
|---|---|---|
campaign_code | 필수 | 캠페인 코드(예: PUSH-MW06HTSA-E1766C) |
- 보낸 다음 날 03:00(한국 시간) 이후부터 받을 수 있습니다. 그 전에는 400
STATS_NOT_READY와data.available_at을 돌려줍니다. - 03:00이 지났는데 아직 준비되지 않았으면 503
STATS_DELAYED입니다.Retry-After뒤 다시 부르세요. - 통계를 볼 수 없는 캠페인(없는 코드, 다른 앱 캠페인, 테스트 발송 등)은 404
CAMPAIGN_NOT_FOUND입니다. - 그 시각에 저장된 최신 값을 줍니다. 그래서 03:00 전에는
/changes보다 하루치 앞선 값일 수 있습니다.
HTTP
1
GET /api/v1/push/stats/campaigns/PUSH-MW06HTSA-E1766C
JSON
1
{
2
"success": true,
3
"code": 200,
4
"error_code": null,
5
"message": "OK",
6
"data": {
7
"campaign_code": "PUSH-MW06HTSA-E1766C",
8
"name": "주말 특가 알림",
9
"sent_at": "2026-11-03T13:19:14+09:00",
10
"finalized": false,
11
"finalizes_on": "2026-11-10",
12
"targets": 3,
13
"success": 3,
14
"fail": 0,
15
"opens_total": 1,
16
"opens_unique": 1,
17
"opens_unique_provisional": true,
18
"conversions": 0,
19
"change_seq": 10,
20
"breakdown_available": true,
21
"by_os": {
22
"android": { "success": 2, "fail": 0 },
23
"ios": { "success": 1, "fail": 0 }
24
},
25
"fail_reasons": {},
26
"opens_by_day": [1, 0, 0, 0, 0, 0, 0],
27
"opens_by_hour": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
28
}
29
}
더해지는 항목
| 항목 | 설명 |
|---|---|
breakdown_available | by_os와 fail_reasons가 둘 다 있으면 true |
by_os | OS별 성공, 실패(android, ios). 2026-11-02 이전 기록이 섞이면 null |
fail_reasons | 실패 사유별 건수(예: UNREGISTERED). 2026-11-02 이전 기록이 섞이면 null |
opens_by_day | 보낸 날부터 0~6일차 열린 횟수(7칸) |
opens_by_hour | 0~23시(한국 시간) 열린 횟수(24칸). 7일 합 |
오류 코드
success가 false이고, error_code로 이유를 구분합니다.
JSON
1
{
2
"success": false,
3
"code": 400,
4
"error_code": "REPORT_NOT_AVAILABLE",
5
"message": "통계 API 를 켜기 전 날짜는 리포트가 없습니다",
6
"data": { "available_from": "2026-11-03" }
7
}
| HTTP | error_code | 뜻과 대응 |
|---|---|---|
| 400 | DATE_REQUIRED | date 또는 from, to가 없음 |
| 400 | DATE_CONFLICT | date와 from, to를 함께 보냄 |
| 400 | INVALID_PARAMETER | 날짜 형식이 틀렸거나 없는 날, 모르는 항목, from, to 중 하나만 보냄. /changes에서 cursor가 없거나 limit이 1~500 밖 |
| 400 | INVALID_CURSOR | /changes의 cursor가 숫자가 아니거나 지금 공개된 마지막 번호보다 큼. 저장해 둔 next_cursor를 그대로 보냈는지 확인하세요 |
| 400 | INVALID_DATE_RANGE | from이 to보다 늦음 |
| 400 | RANGE_TOO_LONG | 기간이 31일을 넘음 |
| 400 | DATE_NOT_ALLOWED | 오늘이나 미래 날짜. 어제까지만 조회할 수 있습니다 |
| 400 | DATE_TOO_OLD | 13개월보다 오래된 날짜 |
| 400 | STATS_NOT_READY | 03:00 전에 어제 리포트를 요청함, 또는 아직 준비 전인 캠페인 상세를 요청함(보낸 다음 날 03:00 이후 준비). data.available_at 이후 다시 부르세요. 자주 나면 예약 시각을 늦추세요 |
| 400 | REPORT_NOT_AVAILABLE | 통계 API를 켜기 전 날짜. data.available_from부터 받을 수 있습니다 |
| 401 | UNAUTHORIZED | 인증 정보가 없거나 틀림 |
| 403 | IP_NOT_ALLOWED | 등록하지 않은 서버 IP에서 부름 |
| 403 | STATS_NOT_ENABLED | 콘솔에서 "통계 API 사용"이 꺼져 있음 |
| 403 | TOO_MANY_AUTH_FAILURES | 인증 실패가 많아 이 IP를 1시간 막음 |
| 404 | CAMPAIGN_NOT_FOUND | 통계를 볼 수 없는 캠페인(없는 코드, 다른 앱, 테스트 발송, 무음 푸시, 사용자 여정 발송, 취소, "통계 API 사용"을 켜기 전에 보냄, 발송 결과 없음) |
| 404 | NOT_FOUND | 없는 주소 |
| 405 | METHOD_NOT_ALLOWED | GET이 아닌 방식 |
| 429 | RATE_LIMIT_MINUTE | 1분 10회 또는 동시 2개를 넘음. Retry-After만큼 기다리세요 |
| 429 | DAILY_QUOTA_EXCEEDED | 오늘 100회를 다 씀. 다음 날 00:00 이후 다시 부르세요 |
| 429 | TOO_MANY_ERRORS | 오늘 오류 응답이 200회를 넘음. 다음 날 00:00까지 막힙니다 |
| 503 | STATS_DELAYED | 새벽 집계가 늦어지는 중. Retry-After(보통 900초) 뒤 다시 부르세요 |
| 503 | SERVICE_UNAVAILABLE | 잠시 후 다시 시도하세요 |
| 500 | INTERNAL_ERROR | 서버 오류. 계속되면 문의해 주세요 |
호출 한도와 권장 사용법
| 한도 | 값 |
|---|---|
| 하루 호출 | 앱마다 100회(세 API 합산). 데이터를 돌려준 요청(200)만 셉니다. /changes는 한 쪽(page)마다 1회 |
| 1분 호출 | 10회 |
| 동시 호출 | 2개 |
| 하루 오류 응답 | 200회를 넘으면 그날 막힘 |
| 인증 실패 | 10분에 20회를 넘으면 그 IP를 1시간 막음 |
권장 사용법
- 매일 한 번, 03:00 이후 임의의 시각에
GET /reports?date=어제를 부르고date를 열쇠로 귀사 DB에 저장합니다. - 처음 연동할 때는 켠 날부터 어제까지를 31일씩 나눠 받습니다.
report_version이 저장해 둔 값보다 크면 그 날짜를 덮어씁니다.- 캠페인별 숫자는 같은 시각에
GET /changes?cursor=저장해 둔 next_cursor로 바뀐 캠페인만 받아campaign_code를 열쇠로 덮어씁니다. 처음에는cursor=0입니다. - 429는
Retry-After만큼, 503STATS_DELAYED는Retry-After뒤에 다시 부릅니다. - 짧은 시간에 아주 많이 부르면 앞단 보안 장비가 먼저 429로 막습니다. 이때 본문은 JSON이 아니므로(
error code: 1015) 본문을 읽지 말고 상태 코드와Retry-After로 판단하세요. - 요청 머리글에
Accept-Encoding: gzip을 넣으면 1KB가 넘는 응답을 압축해서 보냅니다(cURL은--compressed). 기간을 길게 받을 때 전송량이 크게 줄어듭니다. - 귀사 화면에서 통계 API를 실시간으로 부르지 마세요. 화면은 저장해 둔 데이터로 그립니다.
- 캠페인별 열람, 전환은 보낸 뒤 며칠 동안 계속 늘어나므로 하루 리포트에는 "그날 열린 것"으로만 들어갑니다. 캠페인별 7일 누적은
/changes로 받고, 캠페인 하나를 나눠 볼 때만/campaigns/{campaign_code}를 부르세요.