현재 상태
결과 push 웹훅 준비 중
아직 고객사 엔드포인트로 발송 결과를 보내드리지 않습니다. 발송 후 상태는 아래 폴링 방식으로 확인해 주세요. 웹훅이 열리면 서명 검증 규약과 함께 이 페이지에서 안내드립니다.
참고로 통신사·카카오에서 저희 서버로 오는 리포트는 이미 실시간으로 수신하고 있어서, 조회 API의 상태는 지연 없이 갱신됩니다. 빠진 것은 “여러분 서버로 다시 밀어주는” 마지막 구간뿐입니다.
지금 쓰는 방법 — 결과 폴링
발송 응답의 campaignId로 캠페인 요약과 건별 결과를 조회합니다.
bash
# 1) 발송 → campaignId 확보
curl -X POST https://api.apexstack.com/api/send/v1/messages \
-H "X-API-Key: $APEX_SEND_KEY" -H "Content-Type: application/json" \
-d '{ "channelId":"alimtalk", "templateId":"128", "idempotencyKey":"order-10293",
"recipients":[{ "to":"01012345678", "ref":"order-10293" }] }'
# 2) 캠페인 요약 — 성공/실패 건수가 확정될 때까지 폴링
curl "https://api.apexstack.com/api/send/v1/campaigns/3417" -H "X-API-Key: $APEX_SEND_KEY"
# 3) 건별 결과 — ref 로 우리 주문과 대조
curl "https://api.apexstack.com/api/send/v1/campaigns/3417/messages" -H "X-API-Key: $APEX_SEND_KEY"폴링 설계 권장안
- 주기: 발송 직후 10초 간격으로 5분, 이후 1분 간격으로 최대 30분. 대부분 1분 이내에 확정됩니다.
- 종료 조건: 캠페인 상태가 COMPLETED·PARTIAL·FAILED가 되면 중단합니다.
- 키 권한: 폴링에는 READ_ONLY 키를 쓰세요. 조회 전용이라 유출돼도 지출이 발생하지 않습니다.
- ref 필수: 건별 결과의 수신번호는 마스킹되어 내려옵니다. 발송할 때 넣은 ref로만 어떤 주문인지 특정할 수 있습니다.
- 중복 방지: 재시도할 때는 같은 idempotencyKey를 쓰세요. 중복 발송 대신 기존 캠페인 결과가 돌아옵니다.
javascript
// 최소 폴링 루프 (Node.js)
const BASE = "https://api.apexstack.com/api/send/v1";
const headers = { "X-API-Key": process.env.APEX_SEND_READ_KEY };
const DONE = ["COMPLETED", "PARTIAL", "FAILED", "CANCELED"];
async function waitForResult(campaignId, { timeoutMs = 30 * 60_000 } = {}) {
const started = Date.now();
let delay = 10_000;
while (Date.now() - started < timeoutMs) {
const res = await fetch(`${BASE}/campaigns/${campaignId}`, { headers });
const { data } = await res.json();
if (DONE.includes(data.status)) return data;
await new Promise((r) => setTimeout(r, delay));
if (Date.now() - started > 5 * 60_000) delay = 60_000; // 5분 뒤부터 1분 간격
}
throw new Error("결과 확정 대기 시간 초과");
}자주 묻는 것
실패한 건은 요금이 청구되나요?
아니요. 전송 실패가 확정된 건은 자동으로 환불되어 잔액으로 돌아옵니다. 콘솔 사용 내역에서 실패 환불 항목으로 확인할 수 있습니다.
실패 사유는 어떻게 알 수 있나요?
건별 결과 응답의 결과 코드로 확인합니다. 코드 해석이 어려우면 캠페인 id와 함께 문의해 주시면 서버 로그로 확인해 드립니다.
웹훅은 언제 열리나요?
일정이 확정되면 이 페이지와 콘솔 공지로 안내드립니다. 먼저 필요하시면 문의를 남겨 주세요 — 우선순위 판단에 반영합니다.