Visão Geral: Porque Importa a Monitorização da Validade dos Certificados
Os certificados Apple Pass Type ID (pass.com.yourbrand.*) têm um período de validade estrito de 397 dias (~13 meses) imposto pela Autoridade de Certificação da Apple. Se um certificado expirar sem renovação:
-
Novas Transferências Falham: A Passinstance não consegue gerar assinaturas PKCS#7 destacadas válidas para novas transferências de
.pkpassassociadas a esse certificado. -
Atualizações Push APNs Parem: O gateway APNs HTTP/2 da Apple (
api.push.apple.com) rejeita imediatamente ligações TLS autenticadas com um certificado expirado, interrompendo as atualizações em direto de saldos e campos nos iPhones instalados.
Importante: Renove sempre sob o exato mesmo Pass Type ID (
pass.com.yourbrand.*) e Apple Developer Team ID em vez de criar um novo Pass Type ID. Como o iOS associa os passes instalados ao tuplo(passTypeIdentifier, teamIdentifier), renovar o certificado no mesmo Pass Type ID permite que todos os passes existentes nos iPhones e Apple Watches dos clientes continuem a receber atualizações push APNs com zero reinstalação pelo cliente.
Procedimento de Renovação de Certificados Sem Tempo de Inatividade
-
1
Monitorizar Janelas de Validade (
Certificate Renewal Monitor): A Passinstance executa uma verificação agendada diária às 02:00 que analisa certificados ativos comvalidTodentro de 30 dias, enviando e-mail aos proprietários/administradores do espaço de trabalho e apresentando avisos em Definições -> Carteira -> Certificados Apple. -
2
Gerar um CSR de Renovação: Abra o certificado prestes a expirar na Passinstance e transfira um novo CSR (
POST /api/v1/certificates/generate-csr). -
3
Emitir Novo Certificado sob o Pass Type ID Existente: No Apple Developer Portal -> Identifiers -> Pass Type IDs, selecione o seu Pass Type ID existente, clique em Create Certificate, carregue o CSR e transfira o novo
pass.cer. (A Apple permite certificados ativos sobrepostos por Pass Type ID para que possa rodar com segurança antes de revogar o certificado antigo.) -
4
Fazer Upsert do
pass.cerRenovado na Passinstance: Carregue o.cerassinado através dePOST /api/v1/certificates/upsert(multipart/form-data, especificandopassTypeId,type: "TYPE_PASS" | "TYPE_NFC"e o opcionalpkeyId). A Passinstance verifica a cadeia Apple WWDR G4/G6 e troca o certificado de assinatura ativo. -
5
Verificar Assinatura e Push APNs: Emita um passe de teste (
POST /api/v1/passes) e envie uma notificação push (POST /api/v1/push-notifications/passes/:id) para confirmar que tanto a assinatura do pacote PKCS#7 como a entrega HTTP/2 APNs são bem-sucedidas.
Endpoints da API de Renovação e Ciclo de Vida de Certificados (Certificate Management API)
| Método | Caminho do Endpoint | Permissão Necessária | Descrição |
|---|---|---|---|
| GET | /api/v1/certificates | certificates:read | Lista os certificados do espaço de trabalho e metadados de inspeção (validFrom, validTo, passTypeIdentifier, teamIdentifier, type). |
| POST | /api/v1/certificates/generate-csr | certificates:manage | Gera um par de chaves RSA (CertificatePkey) e devolve um CSR PEM para assinatura no portal Apple Developer. |
| POST | /api/v1/certificates/upsert | certificates:manage | Cria ou substitui/renova atomicamente um certificado existente a partir de um .cer assinado carregado (multipart/form-data). |
| GET | /api/v1/certificates/:id | certificates:read | Inspeciona metadados do certificado X.509, datas de validade e vinculação ao Pass Type ID. |
| DELETE | /api/v1/certificates/:id | certificates:manage | Remove um registo de certificado substituído ou não utilizado. |
Exemplo: Carregar e Atualizar um Pacote .cer Renovado
curl -X POST https://api.passinstance.com/api/v1/certificates/upsert \
-H "X-API-Key: <API_KEY>" \
-F "file=@./pass-renewed.cer" \
-F "passTypeId=pass.com.phenixroasters.loyalty" \
-F "type=TYPE_PASS"
Resposta (201 Created / 200 OK):
{
"id": "cert_8841a9b0-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
"passTypeIdentifier": "pass.com.phenixroasters.loyalty",
"teamIdentifier": "9A8B7C6D5E",
"type": "TYPE_PASS",
"validTo": "2027-12-31T23:59:59.000Z"
}
Transição Automática de Certificados Intermédios Apple WWDR G4 e G6
A Passinstance gere automaticamente os certificados intermédios Worldwide Developer Relations (WWDR) da Apple (G4 e G6) no repositório de certificados PKCS#7 do servidor (Apple Wallet Packager). Nunca precisa de carregar manualmente AppleWWDRCAG4.cer ou AppleWWDRCAG6.cer — a Passinstance inspeciona o Authority Key Identifier (AKI) do seu pass.cer carregado e incorpora o intermédio WWDR correspondente na signature de cada .pkpass.
Consulte Certificados da Apple Wallet e Apple Wallet para os passos de aprovisionamento inicial.
