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:
| Canal | Ideal para | Como funciona |
|---|---|---|
| Formulário Público PassFlow | Cartazes de balcão, assinaturas de e-mail, folhetos QR | O 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 Incorporado | Portais de conta de cliente, páginas de confirmação de encomenda | Incorpore um iframe interativo ou widget script Adicionar à Carteira diretamente no HTML do seu website. |
| URL Dinâmico de Carteira | E-mails transacionais, painéis SaaS, portais de fidelização | Assine 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 NDEF | Suportes de mesa, balcões de caixa, cartazes inteligentes | Grave 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:
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 (
phoneouexternalId). Os portais de backend também podem chamar diretamentePOST /api/v1/passes/upsert-by-external-idpara devolver o passe ativo existente em vez de criar um registo duplicado.
Referência da API pública de PassFlow e autoatendimento
| Método | Caminho do endpoint | Escopo de autenticação | Descrição | ||
|---|---|---|---|---|---|
| GET | /api/v1/pass-flows/public/:url | Público | Obté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-token | Público | Emite o token anti-CSRF exigido antes das submissões públicas de geração de passes. | ||
| POST | /api/v1/pass-flows/public/:url/generate | Público | Submete o payload de registo (request payload: userData, recaptchaToken?, botProtectionToken?) para criar/obter o passe. | ||
| POST | /api/v1/pass-flows/public/:url/otp/send | Público (Limitado por taxa) | Envia um código único (POST .../otp/resend para reenviar) durante OtpStep. | ||
| POST | /api/v1/pass-flows/public/:url/otp/verify | Pú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-intent | Público | Inicializa 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-id | Chave 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:
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):
{
"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
Copie o seu URL público PassFlow (por exemplo,
https://app.passinstance.com/f/coffee-club-vip). -
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
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.
