PUSH API · v1a

첫 테스트 발송

1. 준비 확인

앱 환경의 푸시 서비스 연결이 준비되어 있고 발송이 정지되지 않았는지 확인합니다.
SDK의 서버 동기화를 확인하고, 해당 환경에 등록된 본인 테스트 installation_id를 가져옵니다. 기기 토큰 자체를 복사하지 마세요.
API 접근이 허용된 신뢰할 수 있는 개발 서버나 터미널에서만 서버 키를 사용합니다. messages:send와 조회용 messages:read가 필요합니다.

2. 예제 값 바꾸기

값	준비할 내용
`KITS_API_ORIGIN`	운영자가 제공한 API origin. https://api.example.com은 실제 서비스가 아닌 예시입니다.
`KITS_SERVER_KEY`	테스트 환경의 서버 키. 비밀 저장소에서 안전하게 주입하고 터미널 기록·화면을 공유하지 마세요.
`KITS_IDEMPOTENCY_KEY`	이번 논리적 발송에 고유한 1–255자 ASCII 키. 같은 발송 재시도에는 같은 값을 유지합니다.
`inst_REPLACE_WITH_TEST_INSTALLATION`	본문에서 본인의 실제 테스트 앱 설치 ID로 바꿉니다. 예제 문자열은 유효한 식별자가 아닙니다.

3. 알림 하나 접수하기

curl --include --request POST "${KITS_API_ORIGIN}/v1/messages" \
  --header "Authorization: Bearer ${KITS_SERVER_KEY}" \
  --header "Kits-Idempotency-Key: ${KITS_IDEMPOTENCY_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary '{
  "target": {
    "installation_id": "inst_REPLACE_WITH_TEST_INSTALLATION"
  },
  "send_purpose": "TEST",
  "classification": "SERVICE",
  "display_path": "OS_DISPLAY",
  "priority": "HIGH",
  "title": "Kits test message",
  "body": "Hello from your test environment"
}'

예제는 SERVICE 분류와 v1a의 OS_DISPLAY를 사용합니다. 마케팅 알림을 SERVICE로 우회하지 마세요. 대상은 installation_id 하나이며 다른 target 필드를 함께 넣지 않습니다.

4. 접수 응답 읽기

최초 접수 성공은 HTTP 202입니다. 아래는 실제 고객 정보가 없는 설명용 응답입니다.

{
  "id": "msg_EXAMPLE_ONLY",
  "origin": "TRANSACTIONAL_API",
  "accepted_at": "2026-01-01T00:00:00.000Z",
  "idempotency": {
    "replayed": false
  },
  "targeted_subscriptions": 1,
  "ignored_fields": [],
  "deliveries_url": "/v1/messages/msg_EXAMPLE_ONLY/deliveries"
}

id와 deliveries_url을 보관해 결과를 조회합니다. accepted_at은 서버 접수 시각입니다.
targeted_subscriptions는 대상으로 잡힌 구독 수이며 기기 수신 수가 아닙니다. 0이면 대상·권한·수신 설정을 확인하세요.
idempotency.replayed가 true이면 같은 요청의 기존 결과입니다. 새 발송을 의미하지 않습니다.
ignored_fields는 알고 있지만 해당 플랫폼에서 사용되지 않은 필드입니다. 무시된 내용을 확인하세요.

5. 결과와 기기에서 확인하기

KITS_MESSAGE_ID를 응답의 id로 설정한 뒤 조회합니다. 다음 페이지가 있으면 응답의 next_cursor를 그대로 사용하세요.

curl --include \
  --header "Authorization: Bearer ${KITS_SERVER_KEY}" \
  "${KITS_API_ORIGIN}/v1/messages/${KITS_MESSAGE_ID}/deliveries?limit=50"