Visão geral: Porque são obrigatórios certificados Apple Pass Type ID
A Apple exige que cada ficheiro .pkpass de produção seja assinado criptograficamente com um Certificado Pass Type ID emitido na conta Apple Developer Program da sua organização (Certificate Management API em /api/v1/certificates). O certificado cumpre duas funções críticas:
-
1
Assinatura destacada PKCS#7 do pacote: Assina
manifest.jsondentro de cada ficheiro.pkpass(encadeando até ao certificado intermédio Apple WWDR G4/G6) para que o iOS valide a autenticidade e apresente o Nome da Organização verificado. -
2
Autenticação push HTTP/2 APNs: Autentica ligações TLS HTTP/2 para
api.push.apple.comsob o tópicopass.com.<domain>.<name>do certificado, permitindo à Passinstance acordar iPhones dos clientes para atualizações de passes em direto.
Pré-requisitos: Necessita de uma subscrição ativa no Apple Developer Program (perfil
Account HolderouAdmin) para registar Pass Type IDs e emitir certificados Pass Type ID de produção. Embora a Passinstance forneça um certificado sandbox gerido para demonstrações iniciais de integração, tem de associar o seu próprio certificado Pass Type ID antes de distribuir passes de produção aos clientes — a Apple não permite migrar passes já instalados para umpassTypeIdentifierouteamIdentifierdiferente após a instalação.
Fluxo passo a passo de configuração de certificado
-
1
Gerar um CSR na Passinstance: Aceda a Definições -> Carteira -> Certificados Apple (
/settings/workspace/wallet) e clique em Gerar CSR (chamaPOST /api/v1/certificates/generate-csrcompassTypeIdopcional). Descarregue o ficheiro.certSigningRequest. A Passinstance guarda a chave privada RSA gerada (CertificatePkey) em armazenamento encriptado. -
2
Registar um Pass Type ID no Apple Developer: Inicie sessão em Apple Developer Portal -> Certificates, Identifiers & Profiles -> Identifiers, clique em +, selecione Pass Type IDs e registe um identificador em DNS reverso como
pass.com.yourbrand.loyalty. -
3
Emitir o
.cerassinado no Apple Developer: Abra o seu novo Pass Type ID, clique em Create Certificate, carregue o ficheiro.certSigningRequestdescarregado da Passinstance e descarregue o ficheiropass.cerresultante. -
4
Carregar
pass.cerna Passinstance: Carreguepass.cerviaPOST /api/v1/certificates(multipart/form-data,teamIdentifier,passTypeId,demo,isNfcCertificateopcionais) ouPOST /api/v1/certificates/upsert(file+type: "TYPE_PASS" | "TYPE_NFC"). A Passinstance associa.cerà chave privada gerada, valida a cadeia intermédia Apple WWDR G4/G6 e empacota o conjunto de assinatura.p12encriptado. -
5
Associar certificado ao modelo: Abra Definições do Modelo e associe o certificado Pass Type ID verificado.
Referência da API de gestão de certificados (Certificate Management API)
| Método | Caminho do endpoint | Permissão exigida | Descrição | |
|---|---|---|---|---|
| POST | /api/v1/certificates/generate-csr | certificates:manage | Gera um par de chaves RSA (CertificatePkey) e devolve um Pedido de Assinatura de Certificado PEM (.csr). | |
| POST | /api/v1/certificates | certificates:manage | Carrega um ficheiro .cer assinado pela Apple via multipart/form-data, verifica confiança WWDR G4/G6 e ativa o certificado (CertificateType: `TYPE_PASS \ | TYPE_NFC`). |
| POST | /api/v1/certificates/upsert | certificates:manage | Cria ou atualiza/renova um certificado existente a partir de .cer assinado (multipart/form-data, pkeyId, type, intermediatePem opcionais). | |
| GET | /api/v1/certificates | certificates:read | Lista os certificados do espaço de trabalho com passTypeIdentifier, teamIdentifier, validFrom, validTo e estado. | |
| GET | /api/v1/certificates/:id | certificates:read | Devolve metadados X.509 e detalhes de um ID de certificado específico. | |
| DELETE | /api/v1/certificates/:id | certificates:manage | Remove um certificado não utilizado ou expirado. |
Exemplo: Gerar um CSR e carregar pass.cer
1. Gerar CSR (POST /api/v1/certificates/generate-csr):
POST /api/v1/certificates/generate-csr
{
"passTypeId": "pass.com.phenixroasters.loyalty"
}
Resposta (200 OK):
{
"success": true,
"data": {
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCREUx...\n-----END CERTIFICATE REQUEST-----"
},
"description": "CSR generated successfully",
"errors": [],
"statusCode": 200
}
2. Carregar .cer assinado (POST /api/v1/certificates):
Submeta como multipart/form-data com o campo file (pass.cer), e opcionalmente passTypeId, teamIdentifier e isNfcCertificate ("false" ou "true"):
curl -X POST https://api.passinstance.com/api/v1/certificates \
-H "X-API-Key: <API_KEY>" \
-F "file=@./pass.cer" \
-F "passTypeId=pass.com.phenixroasters.loyalty" \
-F "isNfcCertificate=false"
Resposta (201 Created):
{
"id": "cert_8841a9b0-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
"passTypeIdentifier": "pass.com.phenixroasters.loyalty",
"teamIdentifier": "9A8B7C6D5E",
"type": "TYPE_PASS",
"validFrom": "2026-11-15T10:18:00.000Z",
"validTo": "2027-12-15T10:17:59.000Z"
}
Consulte Renovação e gestão de certificados e Apple Wallet para manutenção do ciclo de vida.
