Descripción general: por qué importa supervisar el vencimiento de certificados
Los certificados Apple Pass Type ID (pass.com.yourbrand.*) tienen una vigencia estricta de 397 días (~13 meses) impuesta por la autoridad certificadora de Apple. Si se permite que un certificado caduque sin renovarse:
-
Fallan las nuevas descargas: Passinstance no puede generar firmas PKCS#7 independientes válidas para nuevas descargas
.pkpassvinculadas a ese certificado. -
Se detienen las actualizaciones push APNs: La pasarela HTTP/2 APNs de Apple (
api.push.apple.com) rechaza de inmediato conexiones TLS autenticadas con un certificado caducado, deteniendo las actualizaciones de saldo y campos en los iPhone ya instalados.
Importante: Renueve siempre bajo el mismo Pass Type ID exacto (
pass.com.yourbrand.*) y Apple Developer Team ID en lugar de crear un Pass Type ID nuevo. Dado que iOS vincula los pases instalados a la tupla(passTypeIdentifier, teamIdentifier), renovar el certificado sobre el mismo Pass Type ID permite que todos los pases ya instalados en iPhone y Apple Watch sigan recibiendo actualizaciones push por APNs con cero reinstalaciones por parte del cliente.
Procedimiento de renovación de certificados sin interrupciones
-
1
Supervisar ventanas de vencimiento (
Certificate Renewal Monitor): Passinstance ejecuta una comprobación diaria programada a las 02:00 analizando certificados activos convalidTodentro de 30 días, enviando avisos por correo a propietarios/administradores del espacio de trabajo y mostrando alertas en Configuración -> Wallet -> Certificados de Apple. -
2
Generar una CSR de renovación: Abra el certificado próximo a vencer en Passinstance y descargue una nueva CSR (
POST /api/v1/certificates/generate-csr). -
3
Emitir un nuevo certificado bajo el Pass Type ID existente: En Apple Developer Portal -> Identifiers -> Pass Type IDs, seleccione su Pass Type ID existente, haga clic en Create Certificate, suba la CSR y descargue el nuevo archivo
pass.cer. (Apple permite certificados activos solapados por Pass Type ID para poder rotar de forma segura antes de revocar el antiguo). -
4
Hacer upsert del
pass.cerrenovado en Passinstance: Suba el.cerfirmado mediantePOST /api/v1/certificates/upsert(multipart/form-data, especificandopassTypeId,type: "TYPE_PASS" | "TYPE_NFC"y opcionalmentepkeyId). Passinstance verifica la cadena Apple WWDR G4/G6 y reemplaza el certificado de firma activo. -
5
Verificar firma y envío push APNs: Emita un pase de prueba (
POST /api/v1/passes) y envíe una notificación push (POST /api/v1/push-notifications/passes/:id) para confirmar que tanto la firma PKCS#7 del paquete como la entrega HTTP/2 por APNs funcionan correctamente.
Endpoints de renovación y ciclo de vida de certificados (Certificate Management API)
| Método | Ruta del endpoint | Permiso requerido | Descripción |
|---|---|---|---|
| GET | /api/v1/certificates | certificates:read | Lista los certificados del espacio de trabajo y sus metadatos (validFrom, validTo, passTypeIdentifier, teamIdentifier, type). |
| POST | /api/v1/certificates/generate-csr | certificates:manage | Genera un par de claves RSA (CertificatePkey) y devuelve una CSR PEM para firmar en Apple Developer. |
| POST | /api/v1/certificates/upsert | certificates:manage | Crea o sustituye/renueva atómicamente un certificado existente a partir de un .cer firmado (multipart/form-data). |
| GET | /api/v1/certificates/:id | certificates:read | Inspecciona los metadatos X.509 del certificado, fechas de validez y vínculo Pass Type ID. |
| DELETE | /api/v1/certificates/:id | certificates:manage | Elimina un registro de certificado obsoleto o sin uso. |
Ejemplo: realizar upsert de un archivo .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"
Respuesta (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"
}
Rotación automática de certificados intermedios Apple WWDR G4 y G6
Passinstance gestiona automáticamente los certificados intermedios Worldwide Developer Relations (WWDR) de Apple (G4 y G6) dentro del almacén de certificados PKCS#7 del servidor (Apple Wallet Packager). Nunca necesita subir manualmente AppleWWDRCAG4.cer ni AppleWWDRCAG6.cer: Passinstance inspecciona el Authority Key Identifier (AKI) de su pass.cer subido e incrusta el certificado intermedio WWDR correspondiente en cada signature de .pkpass.
Consulte Certificados de Apple Wallet y Apple Wallet para los pasos iniciales de aprovisionamiento.
