Skip to content
Guia da Central de Ajuda · Distribuição de passes
4 min de leituraVerificado 2026-11-16

Distribuição em autoatendimento

Publique URLs PassFlow públicos, widgets incorporados, links dinâmicos e etiquetas NFC NDEF no balcão.

Neste guia

Permita que os clientes se inscrevam 24/7

Além de carregar listas CSV ou chamar APIs de backend, a Passinstance permite publicar pontos de inscrição self-service sem autenticação em balcões físicos de retalho, páginas de checkout de e-commerce, talões e embalagens de produtos:

CanalIdeal paraComo funciona
Formulário Público PassFlowCartazes de balcão, assinaturas de e-mail, folhetos QRO cliente preenche um formulário otimizado para telemóvel (/p/:url), verifica OTP por e-mail/SMS se ativo, conclui pagamento opcional e guarda logo o passe.
Botão / Widget IncorporadoPortais de conta de cliente, páginas de confirmação de encomendaIncorpore um iframe interativo ou widget script Adicionar à Carteira diretamente no HTML do seu website.
URL Dinâmico de CarteiraE-mails transacionais, painéis SaaS, portais de fidelizaçãoAssine ou passe atributos parametrizados do cliente no URL ou via upsert-by-external-id para utilizadores autenticados obterem um cartão pré-preenchido com um toque.
Etiqueta / Autocolante NFC NDEFSuportes de mesa, balcões de caixa, cartazes inteligentesGrave um URL público PassFlow em qualquer etiqueta NFC NDEF padrão (NTAG213/215) para que aproximar um iPhone ou Android abra o fluxo sem ler código QR.

Arquitetura de autoinscrição pública PassFlow

O motor PassFlow (PassFlow API em /api/v1/pass-flows/public/:url, com alias /api/v1/passflows/public/:url e rota de interface /f/:url) orquestra a entrada de clientes não autenticados em várias etapas (PassFlowType, PassFlowSubmissionStatus) com proteção integrada contra bots (SpamProtectionMode), verificação OTP, prevenção de duplicados (externalId) e entrega imediata na carteira:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
AUTOINCRIÇÃO PÚBLICA PASSFLOW
ETAPA 01 PONTO DE ENTRADA DO CLIENTE (QR / URL / TOQUE NDEF)
GET/api/v1/pass-flows/public/:url (Carrega Esquema do Fluxo)
ETAPA 02 ETAPA 1: FormStep (Atributos do Cliente e Validação de Consentimento)
Obtém token CSRF (/csrf-token) e valida request payload
ETAPA 03 ETAPAS 2 e 3: EmailStep / OtpStep (Verificação Opcional de Identidade)
Envia código verificação via POST/api/v1/pass-flows/public/:url/otp/send
Verifica token OTP via POST/api/v1/pass-flows/public/:url/otp/verify
ETAPA 04 ETAPA 4: PaymentStep (Subscrições Pagas, Cartões-Presente e Bilhetes Opcionais)
Suporta Stripe PaymentIntent, PayPal Orders, Paystack, MTN MoMo, Orange Money
ETAPA 05 ETAPA 5: PassStep (Upsert Idempotente e Entrega Imediata na Carteira)
Desduplica por email/phone/externalId (semântica upsert-by-external-id)
Apresenta botão .pkpass Apple Wallet, Save JWT Google Wallet e código QR

Importante: Para evitar a criação duplicada de passes quando um membro existente volta a submeter um formulário self-service, configure Regras de Desduplicação / ID Externo no seu modelo/PassFlow (email, phone ou externalId). Os portais de backend também podem chamar diretamente POST /api/v1/passes/upsert-by-external-id para devolver o passe ativo existente em vez de criar um registo duplicado.

Referência da API pública de PassFlow e autoatendimento

MétodoCaminho do endpointEscopo de autenticaçãoDescrição
GET/api/v1/pass-flows/public/:urlPúblicoObtém a configuração pública de etapas PassFlow (PassFlowStepType), esquema do formulário, tema (page theme: `LIGHT \DARK \CUSTOM`) e metadados de pré-visualização do modelo.
GET/api/v1/pass-flows/public/:url/csrf-tokenPúblicoEmite o token anti-CSRF exigido antes das submissões públicas de geração de passes.
POST/api/v1/pass-flows/public/:url/generatePúblicoSubmete o payload de registo (request payload: userData, recaptchaToken?, botProtectionToken?) para criar/obter o passe.
POST/api/v1/pass-flows/public/:url/otp/sendPúblico (Limitado por taxa)Envia um código único (POST .../otp/resend para reenviar) durante OtpStep.
POST/api/v1/pass-flows/public/:url/otp/verifyPúblico (Limitado por taxa)Verifica o código OTP submetido e desbloqueia a geração do passe.
POST/api/v1/pass-flows/public/:url/payment-intentPúblicoInicializa um PaymentIntent Stripe (GET .../payment-config, /paypal-order, /paystack/initialize, /mtn-momo/request-to-pay, /orange-money/initiate).
POST/api/v1/passes/upsert-by-external-idChave API (passes)request payload — cria (CREATED) ou atualiza (UPDATED) de forma idempotente o passe de um cliente indexado por externalId.

Exemplo: Inscrição idempotente em portal via upsert-by-external-id

Ao incorporar um botão Adicionar à Carteira dentro do seu próprio portal autenticado de clientes ou aplicação web, chame POST /api/v1/passes/upsert-by-external-id no seu backend e redirecione o utilizador para passAccessUrl:

JSON
POST /api/v1/passes/upsert-by-external-id
{
  "templateId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
  "externalId": "USR-90214",
  "status": "ACTIVE",
  "attributes": {
    "firstName": "Elena",
    "lastName": "Rostova",
    "email": "elena.rostova@example.com",
    "tier": "Gold",
    "points": 1250
  }
}

Resposta (200 OK):

JSON
{
  "success": true,
  "data": {
    "pass": {
      "id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
      "serialNumber": "PI-8849-2026-X9",
      "externalId": "USR-90214",
      "bundleId": null,
      "status": "ACTIVE",
      "walletVoidStatus": "QUEUED",
      "passAccessUrl": "https://app.passinstance.com/p/c41a8d20-6e11-4f3b-9a81-0029d81a4f10"
    },
    "action": "UPDATED"
  },
  "description": "Pass updated successfully",
  "errors": [],
  "statusCode": 200
}

Codificar etiquetas NFC NDEF de balcão

Para implementar suportes físicos de inscrição por aproximação nos balcões de caixa sem precisar de leitores Apple VAS ou Google Smart Tap:

  1. 1
    Copie o seu URL público PassFlow (por exemplo, https://app.passinstance.com/f/coffee-club-vip).
  2. 2
    Utilize qualquer app padrão de escrita de etiquetas NFC (como NFC Tools) para gravar um NDEF URI Record numa etiqueta NTAG213, NTAG215 ou NTAG216 e ative Bloquear Etiqueta (Só de Leitura) para que os clientes não possam sobrescrever o URL.
  3. 3
    Quando um cliente aproxima o seu iPhone desbloqueado ou telemóvel Android do suporte de balcão, o sistema operativo abre automaticamente a página de registo PassFlow no Safari ou Chrome.

Consulte o Guia de formulários de registo e PassFlow e o Guia de integrações para parâmetros de incorporação e acionadores webhook.

Documentação de produto e API relacionada

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.