Skip to content
Guia da Central de Ajuda · Certificados e credenciais
3 min de leituraVerificado 2026-11-16

Renovação e gestão de certificados

Acompanhe datas de expiração e renove sob o mesmo Pass Type ID sem obrigar clientes a reinstalar o cartão.

Neste guia

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 .pkpass associadas 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.
FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: RENOVAÇÃO DE CERTIFICADOS SEM INATIVIDADE
ETAPA 01 TAREFA CRON DE MONITORIZAÇÃO AUTOMÁTICA (Certificate Renewal Monitor)
Tarefa diária às 02:00 verifica certificados ativos com validTo <= now + 30 days
Notifica os contactos do espaço de trabalho antes da expiração
ETAPA 02 PASSO 1: GERAR CSR PARA O PASS TYPE ID EXISTENTE
POST/api/v1/certificates/generate-csr
Preserva exatamente o passTypeIdentifier (pass.com.yourbrand.loyalty)
Preserva o teamIdentifier Apple de 10 caracteres
ETAPA 03 PASSO 2: RENOVAÇÃO DO CERTIFICADO NO PORTAL APPLE DEVELOPER
Abra o Pass Type ID existenteCreate CertificateCarregue o CSR
Transfira o pass.cer renovado (NÃO revogue o antigo até o novo estar ativo)
ETAPA 04 PASSO 3: UPSERT / SUBSTITUIÇÃO (POST/api/v1/certificates/upsert)
Valida passTypeIdentifier e teamIdentifier + cadeia WWDR G4/G6
Substitui o assinante .p12 no encrypted storage e mantém passes iOS em sincronização

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. 1
    Monitorizar Janelas de Validade (Certificate Renewal Monitor): A Passinstance executa uma verificação agendada diária às 02:00 que analisa certificados ativos com validTo dentro 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. 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. 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. 4
    Fazer Upsert do pass.cer Renovado na Passinstance: Carregue o .cer assinado através de POST /api/v1/certificates/upsert (multipart/form-data, especificando passTypeId, type: "TYPE_PASS" | "TYPE_NFC" e o opcional pkeyId). A Passinstance verifica a cadeia Apple WWDR G4/G6 e troca o certificado de assinatura ativo.
  5. 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étodoCaminho do EndpointPermissão NecessáriaDescrição
GET/api/v1/certificatescertificates:readLista os certificados do espaço de trabalho e metadados de inspeção (validFrom, validTo, passTypeIdentifier, teamIdentifier, type).
POST/api/v1/certificates/generate-csrcertificates:manageGera um par de chaves RSA (CertificatePkey) e devolve um CSR PEM para assinatura no portal Apple Developer.
POST/api/v1/certificates/upsertcertificates:manageCria ou substitui/renova atomicamente um certificado existente a partir de um .cer assinado carregado (multipart/form-data).
GET/api/v1/certificates/:idcertificates:readInspeciona metadados do certificado X.509, datas de validade e vinculação ao Pass Type ID.
DELETE/api/v1/certificates/:idcertificates:manageRemove um registo de certificado substituído ou não utilizado.

Exemplo: Carregar e Atualizar um Pacote .cer Renovado

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

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

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.