Arquitetura de mensagens de saída e Centro de Entrega
No Centro de Entrega (/delivery-center), pode gerir envios transacionais de passes, campanhas promocionais segmentadas, Modelos de E-mail reutilizáveis, listas de supressão de cancelamento de subscrição e registos de entrega em tempo real.
A Passinstance orquestra mensagens de saída em grande volume através de filas assíncronas de tarefas em segundo plano ligadas à infraestrutura europeia gerida de e-mail (eu-central-1 Frankfurt), à entrega de SMS por operadora para SMS global ou ao seu servidor de retransmissão SMTP personalizado encriptado:
Modelos de e-mail e marcadores de posição canónicos
Os modelos reutilizáveis criados em Centro de Entrega -> Modelos (Email Template Engine) garantem consistência de marca em notificações transacionais, mensagens de boas-vindas e alertas de recuperação de passes.
Sintaxe de marcadores de posição e normalização automática
A Passinstance impõe uma sintaxe de chaveta simples: {placeholderName}. Se a sua equipa de design introduzir chavetas duplas ao estilo Mustache ou Handlebars ({{passDownloadUrl}}), o analisador da Passinstance (normalizePlaceholders) normaliza-as automaticamente para chavetas simples antes do armazenamento e da renderização.
| Token de marcador de posição | Tipo | Descrição técnica e valor renderizado |
|---|---|---|
{passDownloadUrl} | Obrigatório | A ligação inteligente canónica de transferência (passAccessUrl). Inspeciona o contexto do dispositivo do destinatário para transmitir o .pkpass da Apple Wallet ou redirecionar para a Google Wallet. |
{passUrl}, {passLink}, {smartLink} | Alias | Aliases legados reconhecidos e normalizados automaticamente para {passDownloadUrl}. |
{appleWalletUrl} | Direto por plataforma | Ligação direta que serve o pacote bruto .pkpass da Apple Wallet (application/vnd.apple.pkpass). |
{googleWalletUrl} | Direto por plataforma | Ligação direta para guardar na Google Wallet (https://pay.google.com/gp/v/save/<jwt>). |
{walletButtonText} | String localizada | Rótulo de botão localizado (por exemplo, "Add to Wallet", "Zu Apple Wallet hinzufügen"). |
{firstName}, {lastName}, {name} | Contacto | Nome do destinatário extraído dos atributos do cliente. |
{passFlowLink} | Inscrição | Ligação pública de registo para o PassFlow associado (/f/:url). |
{unsubscribeLink} | Conformidade | Ligação de cancelamento de subscrição com um clique assinada por HMAC (GET /email/unsubscribe/:token). |
{attributeName} | Propriedade personalizada | Qualquer chave de atributo personalizado definida no modelo (por exemplo, {membershipNumber}, {tier}, {balance}). |
Conformidade de cancelamento de subscrição com um clique RFC 8058
Nos envios de marketing, a Passinstance injeta automaticamente cabeçalhos de e-mail em conformidade com a norma RFC 8058:
List-Unsubscribe: <https://api.passinstance.com/email/unsubscribe/{signedToken}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Isto ativa botões nativos de "Cancelar subscrição" no Gmail, Apple Mail e Yahoo Mail, evitando reclamações de spam e protegendo a reputação do seu domínio.
Envios por e-mail ou SMS: Fluxo de trabalho no Centro de Entrega
Para lançar uma campanha de distribuição em lote:
Passo 1: Filtrar a sua audiência
Em Centro de Entrega -> Nova Campanha, selecione o seu modelo de passe e aplique filtros de segmento:
-
Filtro de Estado: Direcione para passes ativos (
status = 'ACTIVE'). -
Filtro Não Instalados (
onlyUninstalled: true): Direcione apenas para clientes que ainda não adicionaram o passe a um dispositivo (installedDevices === 0). -
Janela de Data de Criação: Direcione para passes criados dentro de intervalos de datas específicos.
Passo 2: Escolher o canal de entrega
-
E-mail: Entregue através da entrega gerida de e-mail ou do seu servidor de retransmissão SMTP personalizado.
-
SMS: Entregue através de entrega de SMS por operadora para números móveis internacionais no formato E.164.
Passo 3: Selecionar ou redigir a sua mensagem
Escolha um modelo guardado em Centro de Entrega -> Modelos ou redija uma mensagem avulsa. Certifique-se de que {passDownloadUrl} está presente no corpo do e-mail.
Passo 4: Executar a estimativa prévia
Clique em Estimar Alcance (POST /api/v1/email-campaigns/estimate). A Passinstance analisa a sua audiência:
-
Total de passes correspondentes.
-
Registos válidos de e-mail/telefone.
-
Contactos suprimidos (cancelamentos de subscrição e devoluções permanentes excluídos).
-
Saldo de créditos de mensagens necessário.
Passo 5: Enviar ou agendar
Clique em Iniciar Envio (POST /api/v1/email-campaigns/:id/start) para iniciar o processamento imediato em segundo plano através da fila de tarefas ou defina uma data futura de publicação.
Preços de entrega, saldo e carregamento de créditos
A entrega de mensagens de saída é faturada num modelo transparente de pagamento consoante a utilização:
| Canal | Tarifa da plataforma | Unidade de faturação | Notas |
|---|---|---|---|
| €0.0005 EUR | Por e-mail entregue | Inclui encaminhamento SES, monitorização de devoluções e acompanhamento de aberturas | |
| SMS | €0.03 EUR | Por segmento GSM-7 de 160 carateres | Encaminhamento global por operadoras móveis para entrega de SMS |
| Atualizações Push | €0.00 (GRÁTIS) | Envios push ilimitados | Os envios push Apple APNs e Google Wallet são sempre gratuitos |
Monitorizar saldo e comprar créditos:
-
Consultar Saldo: Veja o seu saldo atual no Centro de Entrega ou através de
GET /delivery/balance. -
Carregar Créditos: Clique em Adicionar Saldo (
POST /delivery/top-up). A Passinstance abre uma sessão segura Stripe Checkout que permite carregar a sua conta com cartão de crédito, SEPA ou transferência bancária.
Enviar passes individuais com entrega direta por e-mail
Ao emitir manualmente um passe para um cliente individual:
-
1
Aceda a Passes -> Criar Passe Individual.
-
2
Introduza os atributos do cliente (
firstName,email, etc.). -
3
Marque a caixa "Enviar por E-mail" na janela de emissão.
-
4
Clique em Criar Passe. A Passinstance cria o registo do passe e chama imediatamente
POST /passes/:id/email/send, enviando a ligação inteligente personalizada de transferência.
Também pode acionar um e-mail para um passe individual em qualquer momento a partir da vista de detalhe do passe clicando em Ações Rápidas -> Enviar por E-mail (POST /passes/:passId/send-email-with-template).
Encaminhamento SMTP personalizado verificado
Se o seu espaço de trabalho tiver configurado um servidor de retransmissão SMTP personalizado (AddonType.OWN_SMTP), todos os e-mails de passes individuais e envios de campanhas são encaminhados através do seu próprio servidor de correio em vez da infraestrutura SES predefinida da Passinstance.
Resolução de problemas: O modelo de e-mail não está a ser enviado (Porque é que o meu modelo de e-mail não envia?)
Se um e-mail falhar no envio durante a criação do passe, o disparo manual ou a execução de uma campanha, a falha deve-se às portas de execução impostas em sendout-runtime.gates.ts:
1. Marcador de posição obrigatório {passDownloadUrl} em falta
Se um modelo estiver assinalado como exigindo um URL de passe (requiresPassUrl), mas o conteúdo do modelo não contiver {passDownloadUrl} (ou um alias aceite), o worker de envio interrompe a operação com BadRequestException. Solução: Edite o modelo no Centro de Entrega e adicione {passDownloadUrl} ao corpo do e-mail.
2. Porta de método de pagamento do cliente (assertCustomerPaymentMethod)
Os envios automatizados exigem que os espaços de trabalho ativos tenham um método de pagamento verificado registado ou um saldo positivo de créditos. Se a sua subscrição estiver em atraso ou o saldo de créditos for zero, a gateway devolve PaymentRequiredException. Solução: Aceda a Definições -> Faturação -> Métodos de Pagamento e atualize o seu cartão ou carregue créditos.
3. Atributos de contacto do destinatário em falta
Se o registo do passe de destino tiver o campo email nulo ou vazio, o worker ignora o passe e regista um erro de validação. Solução: Verifique se o registo do passe contém um endereço de e-mail válido e bem formatado.
4. Opções de envio desativadas no modelo
Em Definições do Modelo -> Distribuição e Envios, confirme que o modo de envio relevante está ativado:
-
adHocEmailEnabled === true(para envios rápidos manuais). -
distributeOnCreate === true(para envio automático aquando da geração do passe). -
downloadPageEmailEnabled === true(para pedidos de reenvio para telemóvel a partir do computador).
5. Linha de assunto ou corpo vazio
A porta prévia isManualPassEmailContentReady rejeita mensagens em que adHocEmailSubject ou adHocEmailTemplate esteja em branco.
Custo de envio de SMS e configuração de remetente personalizado
Compreender os custos por segmento de SMS
As mensagens SMS são faturadas a €0.03 EUR por segmento:
-
Codificação GSM-7 Padrão: Até 160 carateres por segmento.
-
Codificação Unicode / UCS-2 (Emojis, acentos especiais): Até 70 carateres por segmento.
-
Mensagens Multissegmento: As mensagens concatenadas reservam 7 carateres por segmento para cabeçalhos de concatenação (153 carateres para GSM-7, 67 para Unicode).
Dica profissional: As notificações push da Apple Wallet e da Google Wallet são 100% gratuitas e ilimitadas. Envie os passes iniciais por SMS ou e-mail e utilize notificações push (
changeMessage) para atualizações subsequentes, eliminando os custos de mensagens.
Configurar IDs de remetente alfanuméricos
Em Definições -> Mensagens -> Definições de SMS, pode configurar o nome da sua empresa como ID de remetente de SMS (senderProfile.smsSenderName, até 11 carateres alfanuméricos):
-
Europa, Reino Unido, Austrália e Maioria dos Mercados Internacionais: Os IDs de remetente alfanuméricos são suportados de imediato sem pré-registo. Os clientes veem o nome da sua empresa (por exemplo,
MYBRAND) como remetente. -
Estados Unidos e Canadá: As operadoras de telecomunicações proíbem estritamente IDs de remetente alfanuméricos não registados. As mensagens para os EUA/Canadá são entregues através de números partilhados em conformidade com 10DLC ou códigos curtos dedicados.
Porque é que a Passinstance não anexa ficheiros .pkpass diretamente aos e-mails
Os comerciantes perguntam frequentemente por que razão os e-mails da Passinstance contêm uma ligação inteligente ({passDownloadUrl}) em vez de anexarem o ficheiro .pkpass em bruto diretamente ao e-mail. Existem três razões técnicas críticas:
1. Incompatibilidade dos clientes de e-mail Android (Corrupção MIME)
Os clientes de e-mail móveis no Android (incluindo as aplicações oficiais Gmail e Outlook) não reconhecem o tipo MIME da Apple Wallet application/vnd.apple.pkpass. Quando um utilizador Android toca num anexo .pkpass, o cliente de e-mail trata-o como um ficheiro .zip em bruto, apresentando conteúdo binário ilegível ou um erro indicando "Não é possível abrir o ficheiro".
2. A arquitetura da Google Wallet exige ligações JWT na cloud
Ao contrário da Apple Wallet, a Google Wallet não consegue importar ficheiros locais. A Google Wallet exige um URL autenticado na cloud para adicionar à carteira (https://pay.google.com/gp/v/save/<signed_jwt>). Ao utilizar ligações inteligentes, os utilizadores Android são automaticamente redirecionados para a Google Wallet sem fricção.
3. Segurança de dispositivo único e telemetria de dispositivos
Um ficheiro .pkpass em bruto anexado a um e-mail pode ser reencaminhado para centenas de destinatários não autorizados. Com ligações inteligentes de transferência:
-
Pode impor Vinculação a Dispositivo Único (
limitToOneActivePerPass). -
Pode impor Proteção por PIN e Datas de Expiração (
enableDownloadUntil). -
Capta Telemetria Completa do Dispositivo (sistema operativo, navegador, carimbo temporal de instalação, atribuição UTM) quando o passe é reclamado.
Referência da API REST de entrega
| Método | Caminho do endpoint | Escopo de autenticação | Descrição |
|---|---|---|---|
| POST | /api/v1/passes/:id/send-email | Chave API (passes) | Envia um e-mail transacional de passe único utilizando o modelo predefinido. |
| POST | /api/v1/passes/:passId/send-email-with-template | Chave API (passes) | Envia um e-mail de passe único com um templateId e idempotencyKey específicos. |
| POST | /api/v1/passes/:passId/send-sms | Chave API (passes) | Envia um SMS de passe único para o phoneNumber do destinatário. |
| POST | /api/v1/email-campaigns | Chave API (delivery) | Cria um rascunho de campanha de envio em lote. |
| POST | /api/v1/email-campaigns/estimate | Chave API (delivery) | Devolve o tamanho da audiência, a contagem de passes entregáveis e os créditos necessários. |
| POST | /api/v1/email-campaigns/:id/start | Chave API (delivery) | Coloca a campanha em fila para execução imediata em segundo plano. |
| GET | /delivery/balance | Chave API (billing) | Devolve o saldo atual pré-pago de mensagens e a moeda. |
| POST | /delivery/top-up | Chave API (billing) | Cria uma sessão Stripe Checkout para comprar créditos de mensagens. |
| GET | /email-campaigns/track/:id/open | Público | Píxel transparente de acompanhamento que regista carimbos temporais de abertura de e-mails. |
Documentação relacionada
-
Distribuição em autoatendimento — PassFlows, ligações inteligentes, códigos QR e etiquetas NFC.
-
Ligações de transferência e PassFlow — Encaminhamento de ligações inteligentes, proteção por PIN e localização do PassFlow.
-
O seu próprio endereço de remetente e SMTP personalizado — Guia completo para configurar servidores de retransmissão SMTP personalizados.
-
Personalização de marca e opções White-Label — Domínios personalizados e temas do portal.
