Descripción general: por qué son obligatorios los certificados Apple Pass Type ID
Apple exige que todo archivo .pkpass de producción esté firmado criptográficamente mediante un Certificado Pass Type ID emitido bajo la cuenta de Apple Developer Program de su organización (Certificate Management API en /api/v1/certificates). El certificado cumple dos funciones esenciales:
-
1
Firma PKCS#7 independiente del paquete: Firma
manifest.jsondentro de cada archivo.pkpass(encadenando con el certificado intermedio WWDR G4/G6 de Apple) para que iOS verifique la autenticidad y muestre el nombre verificado de su organización. -
2
Autenticación push HTTP/2 de APNs: Autentica las conexiones TLS HTTP/2 hacia
api.push.apple.combajo el tópicopass.com.<domain>.<name>del certificado para que Passinstance pueda despertar los iPhone de sus clientes ante actualizaciones en vivo.
Requisitos previos: Necesita una suscripción activa al Apple Developer Program (rol
Account HolderoAdmin) para registrar Pass Type IDs y emitir certificados Pass Type ID de producción. Aunque Passinstance facilita un certificado sandbox administrado para las demostraciones iniciales de incorporación, debe vincular su propio certificado Pass Type ID antes de distribuir pases en producción a clientes: Apple no permite migrar pases ya instalados a unpassTypeIdentifieroteamIdentifierdiferente después de su instalación.
Flujo paso a paso para configurar el certificado
-
1
Generar una CSR en Passinstance: Vaya a Configuración -> Wallet -> Certificados de Apple (
/settings/workspace/wallet) y haga clic en Generar CSR (invocaPOST /api/v1/certificates/generate-csrconpassTypeIdopcional). Descargue el archivo.certSigningRequest. Passinstance guarda la clave privada RSA generada (CertificatePkey) en almacenamiento cifrado. -
2
Registrar un Pass Type ID en Apple Developer: Inicie sesión en Apple Developer Portal -> Certificates, Identifiers & Profiles -> Identifiers, haga clic en +, elija Pass Type IDs y registre un identificador DNS inverso como
pass.com.yourbrand.loyalty. -
3
Emitir el archivo
.cerfirmado en Apple Developer: Abra su nuevo Pass Type ID, haga clic en Create Certificate, suba el archivo.certSigningRequestdescargado desde Passinstance y descargue el archivo resultantepass.cer. -
4
Subir
pass.cera Passinstance: Subapass.cermediantePOST /api/v1/certificates(multipart/form-data, conteamIdentifier,passTypeId,demo,isNfcCertificateopcionales) oPOST /api/v1/certificates/upsert(file+type: "TYPE_PASS" | "TYPE_NFC"). Passinstance enlaza el.cercon la clave privada generada, verifica la cadena intermedia Apple WWDR G4/G6 y empaqueta el contenedor cifrado.p12. -
5
Vincular el certificado a su plantilla: Abra Configuración de la plantilla y seleccione su certificado Pass Type ID verificado.
Referencia de la API de gestión de certificados (Certificate Management API)
| Método | Ruta del endpoint | Permiso requerido | Descripción | |
|---|---|---|---|---|
| POST | /api/v1/certificates/generate-csr | certificates:manage | Genera un par de claves RSA (CertificatePkey) y devuelve un Certificate Signing Request (.csr) en PEM. | |
| POST | /api/v1/certificates | certificates:manage | Sube un archivo .cer firmado por Apple vía multipart/form-data, verifica la confianza WWDR G4/G6 y activa el certificado (CertificateType: `TYPE_PASS \ | TYPE_NFC`). |
| POST | /api/v1/certificates/upsert | certificates:manage | Crea o actualiza/renueva un certificado existente desde un .cer firmado (multipart/form-data, opcionalmente pkeyId, type, intermediatePem). | |
| GET | /api/v1/certificates | certificates:read | Lista los certificados del espacio de trabajo con passTypeIdentifier, teamIdentifier, validFrom, validTo y estado. | |
| GET | /api/v1/certificates/:id | certificates:read | Devuelve metadatos X.509 y detalles para un ID de certificado específico. | |
| DELETE | /api/v1/certificates/:id | certificates:manage | Elimina un certificado caducado o sin uso. |
Ejemplo: generar una CSR y subir pass.cer
1. Generar CSR (POST /api/v1/certificates/generate-csr):
POST /api/v1/certificates/generate-csr
{
"passTypeId": "pass.com.phenixroasters.loyalty"
}
Respuesta (200 OK):
{
"success": true,
"data": {
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCREUx...\n-----END CERTIFICATE REQUEST-----"
},
"description": "CSR generated successfully",
"errors": [],
"statusCode": 200
}
2. Subir .cer firmado (POST /api/v1/certificates):
Envíe como multipart/form-data con el campo file (pass.cer), y opcionalmente passTypeId, teamIdentifier e isNfcCertificate ("false" o "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"
Respuesta (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 Renovación y gestión de certificados y Apple Wallet para el mantenimiento durante su ciclo de vida.
