발송내역 API

사이트의 알림톡 캠페인 발송 성공·실패, 오픈, 클릭 수와 버튼별 클릭을 조회합니다. 모든 API는 읽기 전용이며 ENTERPRISE 계정과 send-result:read 스코프가 필요합니다.

실시간 지표가 아닙니다 오픈은 매일 오전 08:30, 클릭은 오전 08:45(KST)에 전날 데이터가 집계됩니다. API는 두 집계가 모두 완료된 날짜까지만 허용하며 응답의 collectedThrough에서 조회 가능한 마지막 날짜를 확인할 수 있습니다.

조회 기간을 제한합니다 from과 to는 모두 필수입니다. 일반 발송내역은 양 끝 날짜를 포함해 최대 7일, 시간별 발송 성과는 최대 3일입니다.

지표 계산 기준

필드	계산 기준
`successRate`	`sentCount / (sentCount + failCount) × 100`
`openRate`	`openCount / sentCount × 100`
`clickRate`	`clickCount / sentCount × 100`

비율은 소수 둘째 자리까지 반환합니다. 분모가 0이면 비율은 null입니다. clickCount는 템플릿 일반 버튼 1~5의 클릭 합계이고 채널 추가 버튼은 channelAddClickCount로 분리합니다. 클릭은 고유 사용자 수가 아니라 벤더가 제공하는 클릭 건수이므로 동일 수신자의 반복 클릭이 포함될 수 있습니다.

캠페인의 템플릿 공유 여부를 확인하세요 같은 발신 계정에서 같은 날짜·템플릿을 여러 캠페인이 사용하면 벤더 지표를 캠페인 하나에 정확히 귀속할 수 없습니다. 이 경우 attributionStatus가 TEMPLATE_SHARED로 표시됩니다. EXACT인 항목을 우선 사용하세요.

친구톡 지표 현재 친구톡 채널의 오픈·버튼 클릭 지표는 제공하지 않습니다. 버튼 조회 응답에서 available: false, aggregationStatus: "UNAVAILABLE"로 표시됩니다.

공통 요청 정보

Authorization필수header

Bearer ak_live_xxxx. 키에 send-result:read 스코프가 필요합니다.

X-Site-Id필수header

조회할 사이트 ID입니다. API 키 소유자의 사이트인지 확인합니다.

from / to필수date

YYYY-MM-DD 형식. 일반 조회는 최대 7일, 시간별 조회는 최대 3일입니다.

발송내역 전체 요약

GET/send-results/summary

선택한 사이트와 기간 전체의 발송·오픈·클릭 지표를 합산합니다.

주요 응답 필드

periodobject

실제로 조회한 시작일·종료일과 포함 일수입니다.

collectionobject

COLLECTED 또는 NO_DATA, 수집 완료일과 기준 시간대입니다.

attributionStatusstring

EXACT 또는 템플릿 공유가 포함된 TEMPLATE_SHARED입니다.

metricsobject

대상·전달 중·성공·실패·오픈·일반 클릭·채널 추가 클릭 수와 비율입니다.

요청 예시
curl "https://docs.almani-center.com/open/v1/send-results/summary?from=2026-08-25&to=2026-08-31" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 467"
응답 예시
{
  "code": "0000",
  "message": "OK",
  "data": {
    "period": {
      "from": "2026-08-25",
      "to": "2026-08-31",
      "days": 7
    },
    "collection": {
      "aggregationStatus": "COLLECTED",
      "collectedThrough": "2026-08-31",
      "timezone": "Asia/Seoul"
    },
    "attributionStatus": "EXACT",
    "metrics": {
      "targetCount": 1040,
      "sendingCount": 1015,
      "sentCount": 1000,
      "failCount": 15,
      "openCount": 530,
      "clickCount": 72,
      "channelAddClickCount": 18,
      "successRate": 98.52,
      "openRate": 53.00,
      "clickRate": 7.20
    }
  },
  "meta": { "requestId": "req_9f83ab21" }
}

캠페인별 발송내역

GET/send-results/campaigns

기간 내 발송 스케줄이 있는 캠페인을 캠페인별로 합산합니다.

Query 파라미터

from / to필수date

최대 7일의 조회 기간입니다.

keyword선택string

캠페인 제목 부분 검색 또는 캠페인 ID 정확 검색입니다. 최대 100자입니다.

limit / cursor선택

기본 20, 최대 100개의 커서 페이지네이션입니다.

요청 예시
curl "https://docs.almani-center.com/open/v1/send-results/campaigns?from=2026-08-25&to=2026-08-31&limit=20" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 467"
응답 예시
{
  "code": "0000",
  "data": {
    "period": { "from": "2026-08-25", "to": "2026-08-31", "days": 7 },
    "collection": {
      "aggregationStatus": "COLLECTED",
      "collectedThrough": "2026-08-31",
      "timezone": "Asia/Seoul"
    },
    "items": [{
      "campaignId": 3541,
      "title": "결제 완료",
      "channel": "AT",
      "active": true,
      "lastSendDate": "2026-08-31",
      "attributionStatus": "EXACT",
      "metrics": {
        "targetCount": 520,
        "sendingCount": 510,
        "sentCount": 500,
        "failCount": 10,
        "openCount": 280,
        "clickCount": 39,
        "channelAddClickCount": 8,
        "successRate": 98.04,
        "openRate": 56.00,
        "clickRate": 7.80
      }
    }],
    "nextCursor": null
  }
}

캠페인 일별 성과

GET/send-results/campaigns/{campaignId}/daily

한 캠페인의 발송·오픈·클릭 성과와 버튼별 클릭을 날짜별로 함께 반환합니다. 템플릿 교체 전후를 비교할 때 사용합니다.

일별 응답

items[].datedate

요청한 기간의 날짜입니다. 발송 스케줄이 없는 날짜도 0 지표로 반환합니다.

items[].metricsobject

해당 날짜의 대상·발송 중·성공·실패·오픈·클릭 수와 비율입니다.

items[].buttonClicksobject

일반 버튼 합계, 채널 추가 클릭과 발송 당시 템플릿별 버튼 상세입니다. 하루에 여러 템플릿을 발송했다면 templates가 나뉩니다.

items[].attributionStatusEXACT | TEMPLATE_SHARED

해당 날짜에 같은 발신 계정·템플릿을 다른 캠페인도 사용했는지 나타냅니다. TEMPLATE_SHARED이면 캠페인 단독 성과로 해석하지 마세요.

부하 제한 다른 발송내역 API와 동일하게 한 요청은 최대 7일이며 집계가 완료된 날짜까지만 조회할 수 있습니다. 캠페인과 사이트 소유권을 먼저 확인한 뒤 해당 기간의 스케줄만 집계합니다.

요청 예시
curl "https://docs.almani-center.com/open/v1/send-results/campaigns/8074/daily?from=2026-09-01&to=2026-09-03" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 467"
응답 data 예시
{
  "period": {"from":"2026-09-01","to":"2026-09-03","days":3},
  "collection": {
    "aggregationStatus":"COLLECTED",
    "collectedThrough":"2026-09-03",
    "timezone":"Asia/Seoul"
  },
  "campaignId": 8074,
  "campaignTitle": "결제 완료 안내",
  "channel": "AT",
  "items": [{
    "date": "2026-09-01",
    "attributionStatus": "EXACT",
    "metrics": {
      "targetCount":100,"sendingCount":98,"sentCount":96,"failCount":2,
      "openCount":52,"clickCount":9,"channelAddClickCount":2,
      "successRate":97.96,"openRate":54.17,"clickRate":9.38
    },
    "buttonClicks": {
      "available": true,
      "totalClickCount": 9,
      "channelAddClickCount": 2,
      "templates": [{
        "templateCode":"TPL_4593319557",
        "templateName":"결제 완료 안내",
        "metadataStatus":"MATCHED",
        "totalClickCount":9,
        "channelAddClickCount":2,
        "buttons":[
          {"order":1,"name":"주문 확인","type":"WL","clickCount":6},
          {"order":2,"name":"문의하기","type":"WL","clickCount":3}
        ]
      }]
    }
  }]
}

캠페인 시간별 발송 성과

GET/send-results/campaigns/{campaignId}/hourly

한 캠페인의 발송 대상·전달 중·성공·실패 건수를 KST 한 시간 단위로 반환합니다. 요청 기간은 양 끝 날짜를 포함해 최대 3일이며, 발송이 없는 시간도 0건으로 포함합니다.

현재 오픈·클릭은 일별 데이터만 제공됩니다 현재 원천 데이터에는 실제 오픈·클릭 발생 시각이 없습니다. 정확하지 않은 시간별 값을 만들지 않기 위해 engagementStatus는 UNAVAILABLE_DAILY_SOURCE, 시간별 openCount·clickCount·관련 비율은 null로 반환합니다. 버튼별 클릭은 available: false입니다. 일별 오픈·클릭은 캠페인 일별 성과를 사용하세요.

주요 응답 필드

collection.aggregationStatusDELIVERY_ONLY | NO_DATA

시간별 발송 지표만 제공됨을 나타냅니다. 기간에 발송 행이 없으면 NO_DATA입니다.

engagementStatusstring

현재는 UNAVAILABLE_DAILY_SOURCE입니다.

items[].bucketStartdate-time

KST 기준 시간 버킷 시작 시각입니다.

items[].metricsobject

대상·전달 중·성공·실패와 성공률입니다. 시간별 오픈·클릭 필드는 null입니다.

요청 예시

curl "https://docs.almani-center.com/open/v1/send-results/campaigns/8074/hourly?from=2026-09-01&to=2026-09-03" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 467"

// Java 17 + Spring Framework 6 RestClient
String response = client.get()
    .uri("/send-results/campaigns/{campaignId}/hourly?from={from}&to={to}",
        8074, "2026-09-01", "2026-09-03")
    .retrieve()
    .body(String.class);

응답 data 예시
{
  "period": {"from":"2026-09-01","to":"2026-09-03","days":3},
  "collection": {
    "aggregationStatus":"DELIVERY_ONLY",
    "collectedThrough":"2026-09-06",
    "timezone":"Asia/Seoul"
  },
  "campaignId":8074,
  "campaignTitle":"결제 완료 안내",
  "channel":"AT",
  "engagementStatus":"UNAVAILABLE_DAILY_SOURCE",
  "items":[{
    "bucketStart":"2026-09-01T14:00:00+09:00",
    "metrics":{
      "targetCount":35,"sendingCount":0,"sentCount":33,"failCount":2,
      "openCount":null,"clickCount":null,"channelAddClickCount":null,
      "successRate":94.29,"openRate":null,"clickRate":null
    },
    "buttonClicks":{
      "available":false,"totalClickCount":0,"channelAddClickCount":0,"templates":[]
    }
  }]
}

버튼별 클릭 조회

GET/send-results/campaigns/{campaignId}/button-clicks

캠페인의 발송 당시 템플릿을 기준으로 일반 버튼 1~5와 채널 추가 버튼 클릭 수를 조회합니다. 기간 중 템플릿이 바뀐 경우 템플릿별로 나누어 반환합니다.

상태 필드

필드	값	설명
`available`	`true/false`	현재 채널에서 버튼 지표를 제공하는지 나타냅니다.
`metadataStatus`	`MATCHED`	발송 당시 템플릿을 확인했습니다.
	`FALLBACK_CURRENT`	발송 행의 템플릿 코드가 없어 현재 캠페인 템플릿을 보조 사용했습니다.
	`AMBIGUOUS`	한 스케줄에서 여러 템플릿이 확인돼 버튼명을 확정할 수 없습니다.
	`MISSING`	템플릿 메타데이터를 찾지 못해 `1번 버튼` 형태로 표시합니다.

요청 예시
curl "https://docs.almani-center.com/open/v1/send-results/campaigns/3541/button-clicks?from=2026-08-25&to=2026-08-31" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 467"
응답 예시
{
  "code": "0000",
  "data": {
    "period": { "from": "2026-08-25", "to": "2026-08-31", "days": 7 },
    "collection": {
      "aggregationStatus": "COLLECTED",
      "collectedThrough": "2026-08-31",
      "timezone": "Asia/Seoul"
    },
    "campaignId": 3541,
    "campaignTitle": "결제 완료",
    "channel": "AT",
    "available": true,
    "attributionStatus": "EXACT",
    "totalClickCount": 39,
    "channelAddClickCount": 8,
    "templates": [{
      "templateCode": "ORDER_COMPLETE",
      "templateName": "주문 완료 안내",
      "metadataStatus": "MATCHED",
      "totalClickCount": 39,
      "channelAddClickCount": 8,
      "buttons": [
        { "order": 1, "name": "주문 상세보기", "type": "WL", "clickCount": 31 },
        { "order": 2, "name": "문의하기", "type": "WL", "clickCount": 8 }
      ]
    }]
  }
}

오류와 조회 제한

코드	HTTP	발생 조건
`4000`	400	`from`/`to` 누락, 잘못된 날짜, 역전된 기간, 허용 기간 초과 또는 수집 미완료 날짜
`4003`	400	`X-Site-Id` 누락
`4004`	403	API 키 소유자의 사이트가 아님
`4005`	403	`send-result:read` 스코프가 없거나 ENTERPRISE 계정이 아님
`4040`	404	사이트에서 캠페인을 찾을 수 없음