개인화 푸시 API Endpoints

🔔 최신화 일자: 2025-04-23

📢 공지:

V2버전이 Release됨에 따라 V1버전이 Deprecated 상태로 변경되었습니다.

V1버전 종료일: 2025년 10월 18일 23:59

Obsolete 예정 일 이 후, V1버전은 유지가 아닌 "서비스 중지"되는 점 양해 부탁드립니다.

V1버전과 V2버전의 Request형식은 동일하나, Success Response가 "토큰조회 유저의 결과"가 아닌 "문자열" 반환으로 변경됩니다.

nachocode 푸시 API는 다양한 엔드포인트를 제공하여 푸시 알림 관리 및 전송을 지원합니다.

이 문서에서는 API 사용법, 요청/응답 형식, 에러 케이스 등을 다룹니다.

[POST] `/api/push/v2/messages`

설명 (`/v2/messages`)

개별적으로 설정된 메시지를 각 유저 ID의 푸시 토큰에 전송합니다.
요청된 유저의 총 푸시 토큰 수에 따라 요청 건수가 차감됩니다.
⚠️요청 당 메세지의 최대 개수는 200개이며, Body의 크기는 150KB를 초과하지 않아야 합니다.

Request (`/v2/messages`)

Header

Parameter Type Required Description
x-api-key string ✔ API 키
x-secret-key string ✔ Secret 키
Body

Parameter Type Required Description
messages Message[] ✔ 전송할 메시지 배열
options PushOptions 푸시 상세 옵션

Parameter	Type	Required	Description
x-api-key	`string`	✔	API 키
x-secret-key	`string`	✔	Secret 키

Parameter	Type	Required	Description
messages	`Message[]`	✔	전송할 메시지 배열
options	`PushOptions`		푸시 상세 옵션

Example

{
  "header": { "x-api-key": "APIKEYVALUE", "x-secret-key": "SECRETKEYVALUE" },
  "body": {
    "messages": [
      {
        "userId": "nachoUser1",
        "title": "나쵸코드 업데이트",
        "content": "새로운 기능이 추가되었습니다.",
        "linkURL": "https://nachocode.io"
      },
      {
        "userId": "nachoUser2",
        "title": "알림 메시지",
        "content": "지금 확인하세요!"
      }
    ],
    "options": {
      "isUsingBadge": true // since App Source ver.1.5.0
    }
  }
}

Response (`/v2/messages`)

Success Response
- Property
  
  Properties Type Description
  status number HTTP 응답 상태 코드 (200)
  response string 요청 성공 문자열
- Example
```
"Push successfully requested to be sent."
```

Properties	Type	Description
status	`number`	HTTP 응답 상태 코드 (200)
response	`string`	요청 성공 문자열

Error Response
- Error Response Object
- 에러코드
  (샌드박스 혹은 운영환경에서 아래에 명세되지 않은 에러 코드를 수신받을 경우 나쵸코드로 문의해주세요.)
  
  ErrorCode Status Code Message Description
  ERR-AB-PSS-91 404 App data not found. 미등록 앱
  ERR-AB-PSS-92 404 FCM Account data not found. FCM Service Account파일 미등록

ErrorCode	Status Code	Message	Description
ERR-AB-PSS-91	404	App data not found.	미등록 앱
ERR-AB-PSS-92	404	FCM Account data not found.	FCM Service Account파일 미등록

[POST] `/api/push/v2/users`

설명 (`/v2/users`)

동일한 제목과 내용으로 여러 유저에게 푸시 알림을 전송합니다.
유저 ID로 조회된 모든 푸시 토큰을 대상으로 전송합니다.
유저 1명당 요청 건수를 차감합니다.
⚠️요청 당 userId의 최대 개수는 500개입니다.

Request (`/v2/users`)

Header

Parameter Type Required Description
x-api-key string ✔ API 키
x-secret-key string ✔ Secret 키

Parameter	Type	Required	Description
x-api-key	`string`	✔	API 키
x-secret-key	`string`	✔	Secret 키

Body

Parameter	Type	Required	Description
userIds	`(string \| number)[]`	✔	푸시를 전송할 유저 ID 배열
title	`string`	✔	푸시 알림 제목
content	`string`	✔	푸시 알림 내용
linkURL	`string`		푸시 클릭 시 이동할 URL
options	`PushOptions`		푸시 상세 옵션

Example

{
  "header": { "x-api-key": "APIKEYVALUE", "x-secret-key": "SECRETKEYVALUE" },
  "body": {
    "userIds": ["nachoUser1", "nachoUser2", 3, 4],
    "title": "나쵸코드 개인화 푸시 기능 추가!",
    "content": "새로운 기능이 추가되었습니다.",
    "linkURL": "https://nachocode.io",
    "options": {
      "isUsingBadge": true // since App Source ver.1.5.0
    }
  }
}

Response (`/v2/users`)

Success Response
- Property
  
  Properties Type Description
  status number HTTP 응답 상태 코드 (200)
  response string 요청 성공 문자열
- Example
```
"Push successfully requested to be sent."
```

Properties	Type	Description
status	`number`	HTTP 응답 상태 코드 (200)
response	`string`	요청 성공 문자열

Error Response
- Error Response Object
- 에러코드
  (샌드박스 혹은 운영환경에서 아래에 명세되지 않은 에러 코드를 수신받을 경우 나쵸코드로 문의해주세요.)
  
  ErrorCode Status Code Message Description
  ERR-AB-PSS-91 404 App data not found. 미등록 앱
  ERR-AB-PSS-92 404 FCM Account data not found. FCM Service Account 파일 미등록

ErrorCode	Status Code	Message	Description
ERR-AB-PSS-91	404	App data not found.	미등록 앱
ERR-AB-PSS-92	404	FCM Account data not found.	FCM Service Account 파일 미등록

[POST] `/api/push/v1/messages` (Deprecated)

설명 (`/v1/messages`)

개별적으로 설정된 메시지를 각 유저 ID의 푸시 토큰에 전송합니다.
요청된 유저의 총 푸시 토큰 수에 따라 요청 건수가 차감됩니다.
⚠️ Obsolete 예정 버전입니다. V2버전(/v2/messages) 사용을 권장합니다.

Request (`/v1/messages`)

Header

Parameter Type Required Description
x-api-key string ✔ API 키
x-secret-key string ✔ Secret 키
Body

Parameter Type Required Description
messages Message[] ✔ 전송할 메시지 배열

Parameter	Type	Required	Description
x-api-key	`string`	✔	API 키
x-secret-key	`string`	✔	Secret 키

Parameter	Type	Required	Description
messages	`Message[]`	✔	전송할 메시지 배열

Example

{
  "header": { "x-api-key": "APIKEYVALUE", "x-secret-key": "SECRETKEYVALUE" },
  "body": {
    "messages": [
      {
        "userId": "nachoUser1",
        "title": "나쵸코드 업데이트",
        "content": "새로운 기능이 추가되었습니다.",
        "linkURL": "https://nachocode.io"
      },
      {
        "userId": "nachoUser2",
        "title": "알림 메시지",
        "content": "지금 확인하세요!"
      }
    ]
  }
}

Response (`/v1/messages`)

Success Response

Property

Properties Type Description
status number HTTP 응답 상태 코드 (200)
response object 성공/실패한 유저에 대한 상세 결과 정보

Properties	Type	Description
status	`number`	HTTP 응답 상태 코드 (200)
response	`object`	성공/실패한 유저에 대한 상세 결과 정보

Example

{
  "requested": {
    "success": {
      "count": 3,
      "userIds": ["successUser1", "successUser2", "successUser3"]
    },
    "tokenNotFound": {
      "count": 2,
      "userIds": ["notFoundUser5", "notFoundUser6"]
    }
  },
  "failed": { "count": 2, "userIds": ["failedUser7", 123] }
}

Error Response

Error Response Object

에러코드
(샌드박스 혹은 운영환경에서 아래에 명세되지 않은 에러 코드를 수신받을 경우 나쵸코드로 문의해주세요.)

ErrorCode	Status Code	Message	Description
ERR-AB-PSS-11	400	Invalid key or messages.	전송 요청된 메세지가 없을 경우(빈 배열)
ERR-AB-PSS-52	404	Account information has either never been registered or could not be found.	FCM Service Account파일 미등록

[POST] `/api/push/v1/users`(Deprecated)

설명 (`/v1/users`)

동일한 제목과 내용으로 여러 유저에게 푸시 알림을 전송합니다.
유저 ID로 조회된 모든 푸시 토큰을 대상으로 전송합니다.
유저 1명당 요청 건수를 차감합니다.
⚠️ Obsolete 예정 버전입니다. V2버전(/v2/users) 사용을 권장합니다.

Request (`/v1/users`)

Header

Parameter Type Required Description
x-api-key string ✔ API 키
x-secret-key string ✔ Secret 키

Parameter	Type	Required	Description
x-api-key	`string`	✔	API 키
x-secret-key	`string`	✔	Secret 키

Body

Parameter	Type	Required	Description
userIds	`(string \| number)[]`	✔	푸시를 전송할 유저 ID 배열
title	`string`	✔	푸시 알림 제목
content	`string`	✔	푸시 알림 내용
linkURL	`string`		푸시 클릭 시 이동할 URL

Example

{
  "header": { "x-api-key": "APIKEYVALUE", "x-secret-key": "SECRETKEYVALUE" },
  "body": {
    "userIds": ["nachoUser1", "nachoUser2", 3, 4],
    "title": "나쵸코드 개인화 푸시 기능 추가!",
    "content": "새로운 기능이 추가되었습니다.",
    "linkURL": "https://nachocode.io"
  }
}

Response (`/v1/users`)

Success Response

Property

Properties Type Description
status number HTTP 응답 상태 코드 (200)
response object 성공/실패한 유저에 대한 상세 결과 정보

Properties	Type	Description
status	`number`	HTTP 응답 상태 코드 (200)
response	`object`	성공/실패한 유저에 대한 상세 결과 정보

Example

{
  "requested": {
    "success": {
      "count": 3,
      "userIds": ["successUser1", "successUser2", "successUser3"]
    },
    "tokenNotFound": {
      "count": 2,
      "userIds": ["notFoundUser5", "notFoundUser6"]
    }
  },
  "failed": { "count": 2, "userIds": ["failedUser7", 123] }
}

Error Response

Error Response Object

에러코드
(샌드박스 혹은 운영환경에서 아래에 명세되지 않은 에러 코드를 수신받을 경우 나쵸코드로 문의해주세요.)

ErrorCode	Status Code	Message	Description
ERR-AB-PSS-22	400	Requested user not exist.	전송 요청된 유저가 없을 경우 (빈 배열)
ERR-AB-PSS-23	404	Account information has either never been registered or could not be found.	FCM Service Account 파일 등록 확인

객체 설명

PushOptions

Property

Parameter Type Required Description Since (App Source)
isUsingBadge boolean 푸시 뱃지 제어 여부 ver.1.5.0
- Example
```
{
  "isUsingBadge": true // since App Source ver.1.5.0
}
```

Parameter	Type	Required	Description	Since (App Source)
isUsingBadge	`boolean`		푸시 뱃지 제어 여부	ver.1.5.0

Detail Description

Parameter Description

isUsingBadge 이 설정은 플랫폼(android, ios)에 따라 동작 방식에 차이가 있습니다.

[Android]
OS레벨에서 뱃지 기능을 자동으로 처리하므로, isUsingBadge설정값과 관계없이
android정책에 따라 알림 뱃지가 자연스럽게 표시됩니다.

[iOS]
알림이 하나 이상 도착하면 앱 아이콘에 '1'이 표시됩니다. 실제 알림 개수와 관계없이
뱃지 숫자가 항상 '1'로 표시되고, 이는 푸시가 도착했음을 표시하는 용도로 활용 가능합니다.
알림 건수 누적 기능의 경우 추후 업데이트 예정입니다.

25년 04월 23일 이후로 빌드된 앱(App Source ver.1.5.0)에만 뱃지가 노출됩니다.

Parameter	Description
isUsingBadge	이 설정은 플랫폼(android, ios)에 따라 동작 방식에 차이가 있습니다. [Android] OS레벨에서 뱃지 기능을 자동으로 처리하므로, `isUsingBadge`설정값과 관계없이 android정책에 따라 알림 뱃지가 자연스럽게 표시됩니다. [iOS] 알림이 하나 이상 도착하면 앱 아이콘에 '1'이 표시됩니다. 실제 알림 개수와 관계없이 뱃지 숫자가 항상 '1'로 표시되고, 이는 푸시가 도착했음을 표시하는 용도로 활용 가능합니다. 알림 건수 누적 기능의 경우 추후 업데이트 예정입니다. 25년 04월 23일 이후로 빌드된 앱(App Source ver.1.5.0)에만 뱃지가 노출됩니다.

Message

Property

Parameter Type Required Description
userId string ✔ 유저 ID
title string ✔ 푸시 알림 제목
content string ✔ 푸시 알림 내용
linkURL string 푸시 클릭 시 이동할 URL

Parameter	Type	Required	Description
userId	`string`	✔	유저 ID
title	`string`	✔	푸시 알림 제목
content	`string`	✔	푸시 알림 내용
linkURL	`string`		푸시 클릭 시 이동할 URL

Example

{
  "userId": "nachoUser1",
  "title": "나쵸코드 업데이트",
  "content": "새로운 기능이 추가되었습니다.",
  "linkURL": "https://nachocode.io"
}

Error Response Object

Property

Parameter Type Description
statusCode number 상태 코드
path string 요청 경로
code string 에러 코드
message string 에러 메세지

Parameter	Type	Description
statusCode	`number`	상태 코드
path	`string`	요청 경로
code	`string`	에러 코드
message	`string`	에러 메세지

Example

{
  "statusCode": 400,
  "path": "api/nacho/example",
  "code": "ERR-NA-CHO-00",
  "message": "Oops! Something went wrong!"
}

기타 공용 에러코드

ErrorCode	StatusCode	Message	Description
ERR-AB-VAL-00	400	Incorrect request. Server cannot understand request.	요청 Body 데이터가 잘못된 경우
ERR-AB-SGK-11	400	Secret key not found.	Secret Key가 전달되지 않았을 경우
ERR-AB-SGK-13	401	Incorrect secret key.	유효하지 않은 Secret Key
ERR-AB-KSY-11	400	Required parameters missing.	API Key가 전달되지 않았을 경우
ERR-AB-KSY-13	404	Provided key information not found. Please check your key again.	유효하지 않은 API Key
ERR-AB-AGK-11	400	Api key not found.	Api Key가 전달되지 않았을 경우
ERR-AB-AGK-12	400	Invalid api key type.	유효하지 않은 API Key

[POST] /api/push/v2/messages​

설명 (/v2/messages)​

Request (/v2/messages)​

Response (/v2/messages)​

[POST] /api/push/v2/users​

설명 (/v2/users)​

Request (/v2/users)​

Response (/v2/users)​

[POST] /api/push/v1/messages (Deprecated)​

설명 (/v1/messages)​

Request (/v1/messages)​

Response (/v1/messages)​

[POST] /api/push/v1/users(Deprecated)​

설명 (/v1/users)​

Request (/v1/users)​

Response (/v1/users)​

객체 설명​

PushOptions​

Message​

Error Response Object​

기타 공용 에러코드​

[POST] `/api/push/v2/messages`

설명 (`/v2/messages`)

Request (`/v2/messages`)

Response (`/v2/messages`)

[POST] `/api/push/v2/users`

설명 (`/v2/users`)

Request (`/v2/users`)

Response (`/v2/users`)

[POST] `/api/push/v1/messages` (Deprecated)

설명 (`/v1/messages`)

Request (`/v1/messages`)

Response (`/v1/messages`)

[POST] `/api/push/v1/users`(Deprecated)

설명 (`/v1/users`)

Request (`/v1/users`)

Response (`/v1/users`)

객체 설명

PushOptions

Message

Error Response Object

기타 공용 에러코드