Skip to content
Guia da Central de Ajuda · Certificados e credenciaisFase de integração 3
3 min de leituraVerificado 2026-11-16

Certificados Apple Wallet

Crie um Pass Type ID no Apple Developer, gere o CSR na Passinstance, carregue .cer/.p12 e associe o certificado.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface
Elementos-chave da interface

Template Settings — Assinatura e External IDs (Ampliado)

Confira status de assinatura, ordenação na carteira, estado Published e regras de unicidade de External ID.

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. 1
    Assinatura destacada PKCS#7 do pacote: Assina manifest.json dentro 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. 2
    Autenticação push HTTP/2 APNs: Autentica ligações TLS HTTP/2 para api.push.apple.com sob o tópico pass.com.<domain>.<name> do certificado, permitindo à Passinstance acordar iPhones dos clientes para atualizações de passes em direto.
FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PROVISIONAMENTO CERTIFICADO APPLE PASS TYPE
ETAPA 01 ETAPA 1: Gerar Chave Privada e CSR na Passinstance (Certificate Management API)
POST/api/v1/certificates/generate-csr
Gera CertificatePkey RSA 2048-bit (encriptada no encrypted storage)
Devolve .certSigningRequest (CSR) codificado em PEM
ETAPA 02 ETAPA 2: Portal Apple Developer (developer.apple.com)
1
Registar IdentifierPass Type ID (pass.com.yourbrand.loyalty)
2
Create CertificateCarregar CSR PassinstanceDescarregar pass.cer
ETAPA 03 ETAPA 3: Carregar .cer assinado na Passinstance (POST/api/v1/certificates)
1
Analisa .cer X.509: Extrai passTypeIdentifier, teamIdentifier e validade
2
Compara módulo da chave pública com CertificatePkey armazenada
3
Valida cadeia de confiança face ao intermédio Apple WWDR G4 / G6
4
Empacota PKCS#12 (.p12) encriptado no encrypted storageEstado: VALID / ACTIVE

Pré-requisitos: Necessita de uma subscrição ativa no Apple Developer Program (perfil Account Holder ou Admin) 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 um passTypeIdentifier ou teamIdentifier diferente após a instalação.

Fluxo passo a passo de configuração de certificado

  1. 1
    Gerar um CSR na Passinstance: Aceda a Definições -> Carteira -> Certificados Apple (/settings/workspace/wallet) e clique em Gerar CSR (chama POST /api/v1/certificates/generate-csr com passTypeId opcional). Descarregue o ficheiro .certSigningRequest. A Passinstance guarda a chave privada RSA gerada (CertificatePkey) em armazenamento encriptado.
  2. 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. 3
    Emitir o .cer assinado no Apple Developer: Abra o seu novo Pass Type ID, clique em Create Certificate, carregue o ficheiro .certSigningRequest descarregado da Passinstance e descarregue o ficheiro pass.cer resultante.
  4. 4
    Carregar pass.cer na Passinstance: Carregue pass.cer via POST /api/v1/certificates (multipart/form-data, teamIdentifier, passTypeId, demo, isNfcCertificate opcionais) ou POST /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 .p12 encriptado.
  5. 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étodoCaminho do endpointPermissão exigidaDescrição
POST/api/v1/certificates/generate-csrcertificates:manageGera um par de chaves RSA (CertificatePkey) e devolve um Pedido de Assinatura de Certificado PEM (.csr).
POST/api/v1/certificatescertificates:manageCarrega 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/upsertcertificates:manageCria ou atualiza/renova um certificado existente a partir de .cer assinado (multipart/form-data, pkeyId, type, intermediatePem opcionais).
GET/api/v1/certificatescertificates:readLista os certificados do espaço de trabalho com passTypeIdentifier, teamIdentifier, validFrom, validTo e estado.
GET/api/v1/certificates/:idcertificates:readDevolve metadados X.509 e detalhes de um ID de certificado específico.
DELETE/api/v1/certificates/:idcertificates:manageRemove um certificado não utilizado ou expirado.

Exemplo: Gerar um CSR e carregar pass.cer

1. Gerar CSR (POST /api/v1/certificates/generate-csr):

JSON
POST /api/v1/certificates/generate-csr
{
  "passTypeId": "pass.com.phenixroasters.loyalty"
}

Resposta (200 OK):

JSON
{
  "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"):

BASH
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):

JSON
{
  "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.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.