# API Apple Wallet PassKit

A API PassKit Designer permite que você crie, atualize, baixe e gerencie [passes do Apple Wallet](/pt/product/messaging-channels/apple-wallet-passes/) programaticamente. Ela suporta as mesmas operações que o construtor de passes no Painel de Controle realiza. Use-a para emitir cartões de fidelidade, cupons, ingressos para eventos, cartões de embarque e cartões de loja, e para enviar atualizações ao vivo para passes já instalados nos dispositivos de seus usuários.

<Aside type="note" title="Pré-requisito: certificado PassKit">
Antes de poder criar passes para um aplicativo, um certificado de assinatura iOS PassKit deve ser configurado para esse aplicativo. O certificado é gerenciado no Painel de Controle da Pushwoosh. Sem ele, as solicitações `create` e `update` falham. Consulte [Configuração de passe do Apple Wallet para iOS](/pt/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/).
</Aside>

## URL Base

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

Todos os endpoints são servidos por HTTPS. As solicitações e respostas usam `application/json`, a menos que seja indicado o contrário.

## Autenticação

Cada solicitação deve incluir um cabeçalho `Authorization` com seu [token de acesso à API da Pushwoosh](/pt/developer/api-reference/api-access-token/):

```
Authorization: Token <api-token>
```

A conta proprietária do token deve ser a proprietária do aplicativo referenciado por `applicationCode`. Uma solicitação para um aplicativo que pertence a outra conta retorna `403 Forbidden`.

## Convenções

*   **Nomenclatura de campos:** Os campos JSON usam `lowerCamelCase` (por exemplo, `passTypeIdentifier`, `serialNumber`, `backgroundColor`).
*   **Campos não preenchidos:** as respostas incluem todos os campos, mesmo quando vazios ou com valor zero.
*   **Dados binários:** campos `bytes` como `pkpassData` e `data` de imagem são strings codificadas em Base64 em JSON.
*   **Números de série:** o `serialNumber` é sempre atribuído pelo servidor quando um passe é criado. Qualquer valor que você enviar na criação é ignorado; ele identifica o passe para todas as operações posteriores.

### Respostas de erro

A API mapeia códigos de status internos para códigos de status HTTP:

| Status HTTP | Significado |
| :---- | :---- |
| `400 Bad Request` | Argumento inválido — um campo obrigatório está ausente ou malformado. |
| `401 Unauthorized` | Cabeçalho `Authorization` ausente ou inválido. |
| `403 Forbidden` | O aplicativo não pertence à conta do chamador. |
| `404 Not Found` | O passe, modelo ou aplicativo não foi encontrado. |
| `503 Service Unavailable` | O serviço está em sua capacidade máxima ou temporariamente indisponível. |

## Endpoints

| Método | Caminho | Descrição |
| :---- | :---- | :---- |
| `POST` | `/api/pass/validate` | Validar uma configuração de passe |
| `POST` | `/api/pass/create` | Criar um novo `.pkpass` |
| `POST` | `/api/pass/update/{serialNumber}` | Atualizar um passe existente e notificar os dispositivos |
| `GET` | `/api/passes` | Listar todos os passes de um aplicativo |
| `GET` | `/api/pass/{applicationCode}/{serialNumber}` | Obter um único passe |
| `GET` | `/api/pass/{applicationCode}/{serialNumber}/download` | Baixar o `.pkpass` de um passe existente |
| `DELETE` | `/api/pass/{applicationCode}/{serialNumber}` | Excluir um passe |
| `GET` | `/api/pass/{serialNumber}/registrations` | Listar dispositivos registrados para um passe |
| `GET` | `/api/config` | Obter a configuração PassKit do aplicativo |
| `GET` | `/api/templates` | Listar modelos de passe disponíveis |
| `GET` | `/api/templates/{filename}` | Obter um único modelo |


## Criar um passe

Gera, assina e armazena um novo passe, e então retorna seu número de série atribuído pelo servidor.

`POST` `/api/pass/create`

<Aside type="tip">
Para obter o próprio arquivo `.pkpass`, chame [Baixar um passe](#download-a-pass) (ou construa um [link de instalação / código QR](#share-a-pass-as-a-qr-code)) com o número de série retornado.
</Aside>


### Corpo da solicitação

| Parâmetro | Tipo | Obrigatório | Descrição |
| :---- | :---- | :---- | :---- |
| `pass` | objeto | Sim | O [objeto de passe](#pass-object) que descreve o passe. |
| `images` | array de objetos | Não | [Imagens do passe](#pass-image-object) (ícone, logo, etc.). `icon` e `logo` são necessários para um passe válido. |
| `userId` | string | Sim | O User ID da Pushwoosh para o qual o passe é emitido. |
| `applicationCode` | string | Sim | O [código do aplicativo Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code). |

<Aside type="note">
Na criação, se `teamIdentifier`, `passTypeIdentifier` ou `organizationName` forem omitidos, eles assumirão os valores do certificado configurado do aplicativo. `formatVersion` assume o padrão `1`. O `serialNumber` é atribuído pelo servidor.
</Aside>

##### Exemplo de solicitação

```json
{
  "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" }
  ]
}
```

### Resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `serialNumber` | string | Identidade única atribuída pelo servidor do passe criado. Use-a para buscar o passe ([Obter um passe](#get-a-pass)) ou baixar o .pkpass ([Baixar um passe](#download-a-pass)). |
| `message` | string | Mensagem de resultado. |

##### Exemplo de resposta

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

## Validar um passe

Verifica uma configuração de passe em relação às especificações da Apple sem criar um arquivo. Útil antes de chamar a criação.

`POST` `/api/pass/validate`

### Corpo da solicitação

| Parâmetro | Tipo | Obrigatório | Descrição |
| :---- | :---- | :---- | :---- |
| `pass` | objeto | Sim | O [objeto de passe](#pass-object) a ser validado. |

### Resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `valid` | boolean | Se o passe passa na validação. |
| `errors` | array de strings | Problemas bloqueadores que devem ser corrigidos. |
| `warnings` | array de strings | Avisos não bloqueadores. |



## Atualizar um passe

Regenera o passe com novo conteúdo, o assina novamente, incrementa sua tag de atualização e envia uma **notificação push silenciosa** para cada dispositivo que registrou o passe. O iOS então busca e instala a versão atualizada em segundo plano.

`POST` `/api/pass/update/{serialNumber}`

### Parâmetros de caminho

| Parâmetro | Tipo | Descrição |
| :---- | :---- | :---- |
| `serialNumber` | string | O número de série retornado quando o passe foi criado. |

### Corpo da solicitação

| Parâmetro | Tipo | Obrigatório | Descrição |
| :---- | :---- | :---- | :---- |
| `updates` | objeto | Sim | O [objeto de passe](#pass-object) completo com o novo conteúdo. |
| `applicationCode` | string | Sim | O código do aplicativo Pushwoosh. |

O `serialNumber` (do caminho) e o token de autenticação do passe são preservados pelo servidor, independentemente do que você enviar.

### Resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `success` | boolean | Se a atualização foi bem-sucedida. |
| `updateTag` | integer | Nova tag de atualização (um timestamp Unix). |
| `message` | string | Mensagem de resultado. |



## Listar passes

Retorna uma lista paginada e ordenada dos passes armazenados para um aplicativo.

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

### Parâmetros de consulta

| Parâmetro | Tipo | Obrigatório | Descrição |
| :---- | :---- | :---- | :---- |
| `applicationCode` | string | Sim | O código do aplicativo Pushwoosh. |
| `orderBy` | string | Não | Campo de ordenação: `UPDATED` (padrão) ou `CREATED`. |
| `orderDirection` | string | Não | Direção da ordenação: `DESC` (padrão, mais recentes primeiro) ou `ASC`. |
| `page` | integer | Não | Índice da página baseado em zero. O padrão é `0`. |
| `perPage` | integer | Não | Tamanho da página. `0` ou omitido usa o padrão do servidor. |

### Resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `passes` | array de objetos | A página atual de [registros de passe](#pass-record-object). |
| `page` | integer | O índice da página retornada. |
| `perPage` | integer | O tamanho da página usado para esta resposta. |
| `total` | integer | Número total de passes para o aplicativo em todas as páginas. |

##### Exemplo de resposta

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


## Obter um passe

Retorna um único passe armazenado, incluindo seu objeto de passe completo.

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

### Parâmetros de caminho

| Parâmetro | Tipo | Descrição |
| :---- | :---- | :---- |
| `applicationCode` | string | O código do aplicativo Pushwoosh. |
| `serialNumber` | string | O número de série do passe. |

### Resposta

Retorna `{ "pass": { ... } }`, um único [registro de passe](#pass-record-object).


## Baixar um passe

Retorna o arquivo `.pkpass` armazenado de um passe existente.

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

### Resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `pkpassData` | string (Base64) | O arquivo `.pkpass`. |
| `filename` | string | Nome de arquivo sugerido. |


## Excluir um passe

Remove um registro de passe e seu arquivo `.pkpass` armazenado.

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

### Resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `success` | boolean | Se o passe foi excluído. |
| `message` | string | Mensagem de resultado. |



## Obter registros de passe

Lista os dispositivos que adicionaram o passe e estão registrados para atualizações.

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

### Resposta

Retorna `{ "registrations": [ ... ] }`, onde cada item tem:

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `deviceLibraryIdentifier` | string | Identificador da biblioteca de dispositivos da Apple. |
| `pushToken` | string | O token de push do passe para o dispositivo. |



## Obter configuração

Retorna a configuração PassKit resolvida para um aplicativo a partir de seu certificado.

`GET` `/api/config?applicationCode=XXXXX-XXXXX`

### Resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `teamIdentifier` | string | ID da Equipe Apple do certificado. |
| `passTypeIdentifier` | string | ID do Tipo de Passe do certificado. |
| `organizationName` | string | Nome da organização do certificado. |
| `hasCertificate` | boolean | Se um certificado está configurado. |
| `webServiceUrl` | string | URL base do serviço web do passe. Os clientes constroem um link de instalação anexando `/v1/passes/{passType}/{serial}?token={authToken}`. |



## Modelos

Liste os modelos de passe disponíveis ou busque um como um [objeto de passe](#pass-object) que você pode usar como ponto de partida.

`GET` `/api/templates` — retorna `{ "templates": [ { "filename", "name", "description", "style" } ] }`.

`GET` `/api/templates/{filename}` — retorna `{ "template": { ...pass object... } }`.



## Compartilhar um passe como um código QR

Para permitir que os usuários adicionem um passe escaneando um código QR (ou tocando em um link), codifique a **URL de instalação** do passe em um código QR. A URL é construída a partir de valores que você já recebe da API:

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

| Parte da URL | Onde obter |
| :---- | :---- |
| `webServiceUrl` | [`GET /api/config`](#get-configuration) → `webServiceUrl` |
| `passTypeIdentifier` | [registro de passe](#pass-record-object) → `pass.passTypeIdentifier` (de listar/obter) |
| `serialNumber` | [registro de passe](#pass-record-object) → `serialNumber` |
| `authenticationToken` | [registro de passe](#pass-record-object) → `pass.authenticationToken` |

Exemplo:

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

Renderize esta URL como um código QR com qualquer biblioteca de QR. Quando um usuário a escaneia, seu dispositivo abre o link, baixa o `.pkpass` mais recente e o Wallet solicita que ele o adicione — o que também registra o dispositivo para atualizações.



## Referência de objetos

### Objeto de passe

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `formatVersion` | integer | Versão do formato do passe. O padrão é `1`. |
| `passTypeIdentifier` | string | ID do Tipo de Passe da Apple (`pass.com.yourcompany.passtype`). O padrão vem do certificado. |
| `serialNumber` | string | Atribuído pelo servidor na criação; identifica o passe. |
| `teamIdentifier` | string | ID da Equipe Apple. O padrão vem do certificado. |
| `organizationName` | string | Organização exibida no passe. O padrão vem do certificado. |
| `description` | string | Descrição legível por humanos (exigida pela Apple). |
| `boardingPass` / `coupon` / `eventTicket` / `storeCard` / `generic` | objeto | O estilo do passe. **Exatamente um** deve ser definido. Consulte [grupos de campos](#field-group-object). |
| `backgroundColor` | string | Cor de fundo, `rgb(r, g, b)`. |
| `foregroundColor` | string | Cor do primeiro plano (texto), `rgb(r, g, b)`. |
| `labelColor` | string | Cor do rótulo do campo, `rgb(r, g, b)`. |
| `logoText` | string | Texto exibido ao lado do logo. |
| `suppressStripShine` | boolean | Desativa o efeito de brilho na imagem da faixa. |
| `barcodes` | array | [Códigos de barras](#barcode-object) exibidos no passe. |
| `locations` | array | [Localizações](#location-object) que tornam o passe relevante. |
| `beacons` | array | [Beacons](#beacon-object) que tornam o passe relevante. |
| `relevantDate` | string | Data ISO 8601 quando o passe se torna relevante. |
| `maxDistance` | integer | Distância máxima (metros) para relevância de localização. |
| `expirationDate` | string | Data de expiração ISO 8601. |
| `voided` | boolean | Marca o passe como nulo. |
| `groupingIdentifier` | string | Agrupa passes relacionados (ingressos de eventos/cartões de embarque). |
| `userInfo` | objeto (mapa) | Dados de aplicativo de chave/valor arbitrários. |

<Aside type="note">
`authenticationToken` e `webServiceUrl` são gerenciados pelo serviço e não precisam ser definidos pelos clientes da API.
</Aside>

### Objeto de grupo de campos

Cada estilo de passe (`boardingPass`, `coupon`, `eventTicket`, `storeCard`, `generic`) agrupa [campos](#field-object) em áreas:

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `headerFields` | array | Exibido no cabeçalho do passe (visível quando empilhado no Wallet). |
| `primaryFields` | array | Campos mais proeminentes. |
| `secondaryFields` | array | Abaixo dos campos primários. |
| `auxiliaryFields` | array | Campos adicionais abaixo dos secundários. |
| `backFields` | array | Exibido no verso do passe. |

`boardingPass` adicionalmente tem `transitType` (`PKTransitTypeAir`, `PKTransitTypeTrain`, `PKTransitTypeBus`, `PKTransitTypeBoat` ou `PKTransitTypeGeneric`).

### Objeto de campo

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `key` | string | Chave de campo única dentro do passe. |
| `label` | string | Rótulo do campo. |
| `value` | string | Valor do campo (texto ou número como string). |
| `changeMessage` | string | Mensagem exibida quando o valor muda (use `%@` como o marcador de posição). |
| `textAlignment` | string | Valor `PKTextAlignment`. |
| `dateStyle` / `timeStyle` | string | `PKDateStyle` para formatação de data/hora. |
| `isRelative` | boolean | Mostra a data relativa a agora. |
| `numberStyle` | string | `PKNumberStyle` para formatação de número. |
| `currencyCode` | string | Código de moeda ISO 4217. |
| `dataDetectorTypes` | array de strings | Detectores de dados a serem aplicados ao valor. |

### Objeto de código de barras

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `format` | string | `PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`, `PKBarcodeFormatAztec` ou `PKBarcodeFormatCode128`. |
| `message` | string | Dados codificados no código de barras. |
| `messageEncoding` | string | Codificação de texto, tipicamente `iso-8859-1`. |
| `altText` | string | Texto exibido abaixo do código de barras. |

### Objeto de localização

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `latitude` | number | Latitude. |
| `longitude` | number | Longitude. |
| `altitude` | number | Altitude em metros. |
| `relevantText` | string | Texto exibido na tela de bloqueio perto desta localização. |

### Objeto de beacon

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `proximityUuid` | string | UUID de proximidade iBeacon. |
| `major` | integer | Valor principal. |
| `minor` | integer | Valor secundário. |
| `relevantText` | string | Texto exibido na tela de bloqueio perto deste beacon. |

### Objeto de imagem do passe

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `imageType` | string | Um de `icon`, `logo`, `strip`, `background`, `footer`, `thumbnail`. `icon` e `logo` são obrigatórios. |
| `data` | string (Base64) | Bytes da imagem. |
| `contentType` | string | Tipo MIME, por exemplo, `image/png`. |

### Objeto de registro de passe

Retornado pelos endpoints de listar/obter.

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `serialNumber` | string | Número de série do passe. |
| `passTypeIdentifier` | string | ID do Tipo de Passe. |
| `organizationName` | string | Nome da organização. |
| `description` | string | Descrição do passe. |
| `createdAt` | string | Timestamp de criação (RFC 3339). |
| `updatedAt` | string | Timestamp da última atualização (RFC 3339). |
| `updateTag` | integer | Tag de atualização atual. |
| `pass` | objeto | O [objeto de passe](#pass-object) completo, para edição. |
| `userId` | string | User ID da Pushwoosh para o qual o passe foi emitido. |