Apple Wallet PassKit API

PassKit Designer API를 사용하면 프로그래밍 방식으로 Apple Wallet 패스를 생성, 업데이트, 다운로드 및 관리할 수 있습니다. Control Panel의 패스 빌더가 수행하는 것과 동일한 작업을 지원합니다. 이를 사용하여 로열티 카드, 쿠폰, 이벤트 티켓, 탑승권, 스토어 카드를 발급하고, 사용자의 기기에 이미 설치된 패스에 실시간 업데이트를 푸시할 수 있습니다.

기본 URL

https://apple-passkit.svc-nue.pushwoosh.com

모든 엔드포인트는 HTTPS를 통해 제공됩니다. 요청과 응답은 별도로 명시되지 않는 한 application/json을 사용합니다.

인증

모든 요청에는 Pushwoosh API 액세스 토큰이 포함된 Authorization 헤더가 있어야 합니다:

Authorization: Token <api-token>

토큰을 소유한 계정은 applicationCode로 참조되는 애플리케이션을 소유해야 합니다. 다른 계정에 속한 애플리케이션에 대한 요청은 403 Forbidden을 반환합니다.

규칙

필드 이름 지정: JSON 필드는 lowerCamelCase를 사용합니다 (예: passTypeIdentifier, serialNumber, backgroundColor).
채워지지 않은 필드: 응답에는 비어 있거나 0 값인 경우에도 모든 필드가 포함됩니다.
바이너리 데이터: pkpassData 및 이미지 data와 같은 bytes 필드는 JSON에서 Base64로 인코딩된 문자열입니다.
시리얼 번호: serialNumber는 패스가 생성될 때 항상 서버에서 할당됩니다. 생성 시 보내는 모든 값은 무시되며, 이후 모든 작업에서 패스를 식별합니다.

오류 응답

API는 내부 상태 코드를 HTTP 상태 코드로 매핑합니다:

HTTP 상태	의미
`400 Bad Request`	잘못된 인수—필수 필드가 누락되었거나 형식이 잘못되었습니다.
`401 Unauthorized`	`Authorization` 헤더가 누락되었거나 유효하지 않습니다.
`403 Forbidden`	애플리케이션이 호출자의 계정에 속하지 않습니다.
`404 Not Found`	패스, 템플릿 또는 애플리케이션을 찾을 수 없습니다.
`503 Service Unavailable`	서비스 용량이 초과되었거나 일시적으로 사용할 수 없습니다.

엔드포인트

메서드	경로	설명
`POST`	`/api/pass/validate`	패스 구성 유효성 검사
`POST`	`/api/pass/create`	새 `.pkpass` 생성
`POST`	`/api/pass/update/{serialNumber}`	기존 패스 업데이트 및 기기 알림
`GET`	`/api/passes`	애플리케이션의 모든 패스 목록 조회
`GET`	`/api/pass/{applicationCode}/{serialNumber}`	단일 패스 가져오기
`GET`	`/api/pass/{applicationCode}/{serialNumber}/download`	기존 패스의 `.pkpass` 다운로드
`DELETE`	`/api/pass/{applicationCode}/{serialNumber}`	패스 삭제
`GET`	`/api/pass/{serialNumber}/registrations`	패스에 등록된 기기 목록 조회
`GET`	`/api/config`	애플리케이션의 PassKit 구성 가져오기
`GET`	`/api/templates`	사용 가능한 패스 템플릿 목록 조회
`GET`	`/api/templates/{filename}`	단일 템플릿 가져오기

패스 생성

새 패스를 생성, 서명 및 저장한 다음 서버에서 할당한 시리얼 번호를 반환합니다.

POST /api/pass/create

요청 본문

매개변수	유형	필수	설명
`pass`	object	예	패스를 설명하는 패스 객체입니다.
`images`	array of objects	아니요	패스 이미지 (아이콘, 로고 등). 유효한 패스를 위해서는 `icon`과 `logo`가 필요합니다.
`userId`	string	예	패스가 발급되는 Pushwoosh User ID입니다.
`applicationCode`	string	예	Pushwoosh 애플리케이션 코드입니다.

요청 예시

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

응답

필드	유형	설명
`serialNumber`	string	생성된 패스의 서버 할당 고유 ID입니다. 이를 사용하여 패스를 가져오거나(패스 가져오기) `.pkpass`를 다운로드(패스 다운로드)할 수 있습니다.
`message`	string	결과 메시지입니다.

응답 예시

{
  "serialNumber": "a1b2c3d4-1234-5678-9abc-def012345678",
  "message": "Pass created successfully"
}

패스 유효성 검사

파일을 생성하지 않고 Apple의 사양에 대해 패스 구성의 유효성을 검사합니다. create를 호출하기 전에 유용합니다.

POST /api/pass/validate

요청 본문

매개변수	유형	필수	설명
`pass`	object	예	유효성을 검사할 패스 객체입니다.

응답

필드	유형	설명
`valid`	boolean	패스가 유효성 검사를 통과했는지 여부입니다.
`errors`	array of strings	수정해야 하는 차단 문제입니다.
`warnings`	array of strings	차단되지 않는 권고 사항입니다.

패스 업데이트

새로운 콘텐츠로 패스를 다시 생성하고, 다시 서명하고, 업데이트 태그를 증가시키고, 패스를 등록한 모든 기기에 자동 푸시 알림을 보냅니다. 그러면 iOS가 업데이트된 버전을 백그라운드에서 가져와 설치합니다.

POST /api/pass/update/{serialNumber}

경로 매개변수

매개변수	유형	설명
`serialNumber`	string	패스가 생성될 때 반환된 시리얼 번호입니다.

요청 본문

매개변수	유형	필수	설명
`updates`	object	예	새로운 콘텐츠가 포함된 전체 패스 객체입니다.
`applicationCode`	string	예	Pushwoosh 애플리케이션 코드입니다.

serialNumber(경로에서)와 패스의 인증 토큰은 사용자가 보내는 내용과 관계없이 서버에 의해 보존됩니다.

응답

필드	유형	설명
`success`	boolean	업데이트 성공 여부입니다.
`updateTag`	integer	새 업데이트 태그(Unix 타임스탬프)입니다.
`message`	string	결과 메시지입니다.

패스 목록 조회

애플리케이션에 대해 저장된 패스의 페이지네이션되고 정렬된 목록을 반환합니다.

GET /api/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

쿼리 매개변수

매개변수	유형	필수	설명
`applicationCode`	string	예	Pushwoosh 애플리케이션 코드입니다.
`orderBy`	string	아니요	정렬 필드: `UPDATED`(기본값) 또는 `CREATED`.
`orderDirection`	string	아니요	정렬 방향: `DESC`(기본값, 최신순) 또는 `ASC`.
`page`	integer	아니요	0부터 시작하는 페이지 인덱스입니다. 기본값은 `0`입니다.
`perPage`	integer	아니요	페이지 크기입니다. `0`이거나 생략하면 서버 기본값을 사용합니다.

응답

필드	유형	설명
`passes`	array of objects	패스 레코드의 현재 페이지입니다.
`page`	integer	반환된 페이지 인덱스입니다.
`perPage`	integer	이 응답에 사용된 페이지 크기입니다.
`total`	integer	모든 페이지에 걸쳐 애플리케이션의 총 패스 수입니다.

응답 예시

{
  "passes": [ /* pass records */ ],
  "page": 0,
  "perPage": 20,
  "total": 137
}

패스 가져오기

전체 패스 객체를 포함하여 저장된 단일 패스를 반환합니다.

GET /api/pass/{applicationCode}/{serialNumber}

경로 매개변수

매개변수	유형	설명
`applicationCode`	string	Pushwoosh 애플리케이션 코드입니다.
`serialNumber`	string	패스 시리얼 번호입니다.

응답

{ "pass": { ... } }, 단일 패스 레코드를 반환합니다.

패스 다운로드

기존 패스의 저장된 .pkpass 파일을 반환합니다.

GET /api/pass/{applicationCode}/{serialNumber}/download

응답

필드	유형	설명
`pkpassData`	string (Base64)	`.pkpass` 파일입니다.
`filename`	string	제안된 파일 이름입니다.

패스 삭제

패스 레코드와 저장된 .pkpass 파일을 제거합니다.

DELETE /api/pass/{applicationCode}/{serialNumber}

응답

필드	유형	설명
`success`	boolean	패스가 삭제되었는지 여부입니다.
`message`	string	결과 메시지입니다.

패스 등록 정보 가져오기

패스를 추가하고 업데이트에 등록된 기기 목록을 보여줍니다.

GET /api/pass/{serialNumber}/registrations?applicationCode=XXXXX-XXXXX

응답

{ "registrations": [ ... ] }를 반환하며, 각 항목에는 다음이 포함됩니다:

필드	유형	설명
`deviceLibraryIdentifier`	string	Apple 기기 라이브러리 식별자입니다.
`pushToken`	string	기기의 패스 푸시 토큰입니다.

구성 가져오기

인증서에서 애플리케이션에 대해 확인된 PassKit 구성을 반환합니다.

GET /api/config?applicationCode=XXXXX-XXXXX

응답

필드	유형	설명
`teamIdentifier`	string	인증서의 Apple Team ID입니다.
`passTypeIdentifier`	string	인증서의 Pass Type ID입니다.
`organizationName`	string	인증서의 조직 이름입니다.
`hasCertificate`	boolean	인증서가 구성되었는지 여부입니다.
`webServiceUrl`	string	패스 웹 서비스의 기본 URL입니다. 클라이언트는 `/v1/passes/{passType}/{serial}?token={authToken}`을 추가하여 설치 링크를 만듭니다.

템플릿

사용 가능한 패스 템플릿 목록을 보거나, 시작점으로 사용할 수 있는 패스 객체로 하나를 가져옵니다.

GET /api/templates — { "templates": [ { "filename", "name", "description", "style" } ] }를 반환합니다.

GET /api/templates/{filename} — { "template": { ...pass object... } }를 반환합니다.

QR 코드로 패스 공유하기

사용자가 QR 코드를 스캔하거나 링크를 탭하여 패스를 추가할 수 있도록 하려면 패스 설치 URL을 QR 코드로 인코딩하세요. URL은 API에서 이미 받은 값을 사용하여 만들어집니다:

{webServiceUrl}/v1/passes/{passTypeIdentifier}/{serialNumber}?token={authenticationToken}

URL 부분	가져올 위치
`webServiceUrl`	`GET /api/config` → `webServiceUrl`
`passTypeIdentifier`	패스 레코드 → `pass.passTypeIdentifier` (list/get에서)
`serialNumber`	패스 레코드 → `serialNumber`
`authenticationToken`	패스 레코드 → `pass.authenticationToken`

예시:

https://apple-passkit.svc-nue.pushwoosh.com/v1/passes/pass.com.acme.loyalty/a1b2c3d4-1234-5678-9abc-def012345678?token=AbC123XyZ

이 URL을 QR 라이브러리를 사용하여 QR 코드로 렌더링하세요. 사용자가 스캔하면 기기에서 링크가 열리고 최신 .pkpass가 다운로드되며 Wallet에서 추가하라는 메시지가 표시됩니다. 이 과정에서 기기도 업데이트에 등록됩니다.

객체 참조

패스 객체

필드	유형	설명
`formatVersion`	integer	패스 형식 버전입니다. 기본값은 `1`입니다.
`passTypeIdentifier`	string	Apple Pass Type ID (`pass.com.yourcompany.passtype`). 인증서에서 기본값을 가져옵니다.
`serialNumber`	string	생성 시 서버에서 할당되며, 패스를 식별합니다.
`teamIdentifier`	string	Apple Team ID. 인증서에서 기본값을 가져옵니다.
`organizationName`	string	패스에 표시되는 조직입니다. 인증서에서 기본값을 가져옵니다.
`description`	string	사람이 읽을 수 있는 설명(Apple에서 요구).
`boardingPass` / `coupon` / `eventTicket` / `storeCard` / `generic`	object	패스 스타일입니다. 정확히 하나만 설정해야 합니다. 필드 그룹을 참조하세요.
`backgroundColor`	string	배경색, `rgb(r, g, b)`.
`foregroundColor`	string	전경(텍스트) 색, `rgb(r, g, b)`.
`labelColor`	string	필드 레이블 색, `rgb(r, g, b)`.
`logoText`	string	로고 옆에 표시되는 텍스트입니다.
`suppressStripShine`	boolean	스트립 이미지의 광택 효과를 비활성화합니다.
`barcodes`	array	패스에 표시되는 바코드입니다.
`locations`	array	패스를 관련성 있게 만드는 위치입니다.
`beacons`	array	패스를 관련성 있게 만드는 비콘입니다.
`relevantDate`	string	패스가 관련성을 갖게 되는 ISO 8601 날짜입니다.
`maxDistance`	integer	위치 관련성을 위한 최대 거리(미터)입니다.
`expirationDate`	string	ISO 8601 만료 날짜입니다.
`voided`	boolean	패스를 무효로 표시합니다.
`groupingIdentifier`	string	관련 패스(이벤트 티켓/탑승권)를 그룹화합니다.
`userInfo`	object (map)	임의의 키/값 앱 데이터입니다.

필드 그룹 객체

각 패스 스타일(boardingPass, coupon, eventTicket, storeCard, generic)은 필드를 영역으로 그룹화합니다:

필드	유형	설명
`headerFields`	array	패스 헤더에 표시됩니다(Wallet에 쌓여 있을 때 보임).
`primaryFields`	array	가장 눈에 띄는 필드입니다.
`secondaryFields`	array	기본 필드 아래에 있습니다.
`auxiliaryFields`	array	보조 필드 아래의 추가 필드입니다.
`backFields`	array	패스 뒷면에 표시됩니다.

boardingPass는 추가로 transitType(PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat 또는 PKTransitTypeGeneric)을 가집니다.

필드 객체

필드	유형	설명
`key`	string	패스 내에서 고유한 필드 키입니다.
`label`	string	필드 레이블입니다.
`value`	string	필드 값(텍스트 또는 숫자를 문자열로).
`changeMessage`	string	값이 변경될 때 표시되는 메시지(자리 표시자로 `%@` 사용).
`textAlignment`	string	`PKTextAlignment` 값입니다.
`dateStyle` / `timeStyle`	string	날짜/시간 서식 지정을 위한 `PKDateStyle`입니다.
`isRelative`	boolean	현재를 기준으로 날짜를 표시합니다.
`numberStyle`	string	숫자 서식 지정을 위한 `PKNumberStyle`입니다.
`currencyCode`	string	ISO 4217 통화 코드입니다.
`dataDetectorTypes`	array of strings	값에 적용할 데이터 탐지기입니다.

바코드 객체

필드	유형	설명
`format`	string	`PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`, `PKBarcodeFormatAztec` 또는 `PKBarcodeFormatCode128`입니다.
`message`	string	바코드에 인코딩된 데이터입니다.
`messageEncoding`	string	텍스트 인코딩, 일반적으로 `iso-8859-1`입니다.
`altText`	string	바코드 아래에 표시되는 텍스트입니다.

위치 객체

필드	유형	설명
`latitude`	number	위도입니다.
`longitude`	number	경도입니다.
`altitude`	number	고도(미터)입니다.
`relevantText`	string	이 위치 근처의 잠금 화면에 표시되는 텍스트입니다.

비콘 객체

필드	유형	설명
`proximityUuid`	string	iBeacon 근접 UUID입니다.
`major`	integer	Major 값입니다.
`minor`	integer	Minor 값입니다.
`relevantText`	string	이 비콘 근처의 잠금 화면에 표시되는 텍스트입니다.

패스 이미지 객체

필드	유형	설명
`imageType`	string	`icon`, `logo`, `strip`, `background`, `footer`, `thumbnail` 중 하나입니다. `icon`과 `logo`는 필수입니다.
`data`	string (Base64)	이미지 바이트입니다.
`contentType`	string	MIME 유형, 예: `image/png`.

패스 레코드 객체

list/get 엔드포인트에서 반환됩니다.

필드	유형	설명
`serialNumber`	string	패스 시리얼 번호입니다.
`passTypeIdentifier`	string	Pass Type ID입니다.
`organizationName`	string	조직 이름입니다.
`description`	string	패스 설명입니다.
`createdAt`	string	생성 타임스탬프(RFC 3339)입니다.
`updatedAt`	string	마지막 업데이트 타임스탬프(RFC 3339)입니다.
`updateTag`	integer	현재 업데이트 태그입니다.
`pass`	object	편집을 위한 전체 패스 객체입니다.
`userId`	string	패스가 발급된 Pushwoosh User ID입니다.