Skip to content
Guia da Central de Ajuda
4 min de leituraVerificado 2026-11-16

Bilhetes de eventos e check-in

Entregue bilhetes móveis com lugar/porta, atualizações de horário em direto e leitura rápida na entrada.

Neste guia

Visão geral

A Passinstance substitui anexos PDF estáticos e impressões em papel por passes digitais nativos Event Ticket na Apple Wallet e Google Wallet. Organizadores de eventos, festivais de música, estádios desportivos e promotores de conferências asseguram entradas de alto débito nas portas, avisos de horário em tempo real e mapas de navegação do recinto diretamente nos smartphones dos participantes.

Arquitetura no backend e tipos de passe

No backend da Passinstance, os bilhetes de eventos são modelados com recurso a primitivas nativas de carteira:

  • Tipo de Passe (pass type): eventTicket.
  • Variantes de Layout (theme preference):

- posterEventTicket: Implementa o layout poster de evento da Apple com um gráfico de ponta a ponta (slot de ativos artwork) e sobreposições limpas de metadados. - bannerEventTicket: Faixa horizontal clássica com lugar e porta em destaque.

  • Categorização de Eventos (Apple Wallet event type):

- PKEventTypeLivePerformance: Concertos, teatro, comédia. - PKEventTypeSports: Jogos em estádio, torneios. - PKEventTypeConference / PKEventTypeConvention / PKEventTypeWorkshop: Conferências de vários dias, feiras profissionais e workshops. - PKEventTypeMovie: Cinemas e festivais de cinema. - PKEventTypeGeneric / PKEventTypeSocialGathering: Entrada geral e encontros sociais.

  • Agrupamento de encomendas multi-bilhete (externalId e bundleId): Guarde o ID externo de cada linha de bilhete da encomenda em externalId e agrupe até 10 bilhetes familiares/VIP sob um Pass.bundleId partilhado via /api/v1/bundles ou PassProject para que os convidados adicionem todos os bilhetes num só toque de transferência .pkpasses.
  • Modelos Demo de Catálogo: event-ticket e conference-badge.

Guia de Eventos Apple e integração de recintos MapKit

Para recintos e grandes festivais, os passes Passinstance integram com o Apple Maps para apresentar navegação localizada e comodidades do evento:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
APRESENTAÇÃO DO BILHETE E ENTRADA NO TORNIQUETE
ATORES DE SISTEMA PARTICIPANTES
P1 Geofence Recinto e RelevantDate
P2 Ecrã Bloqueado Participante
P3 Scanner Torniquete
P4 API Passinstance
ETAPA CTX CONTEXTO Coord. GPS / hora doorsOpen
ETAPA 1 PEDIDO / AÇÃO Alerta Ecrã Bloq.
›
(Indicações Nativas)
ETAPA 2 PEDIDO / AÇÃO Apresentar Aztec
›
(Leitura ótica rápida)
ETAPA 3 PEDIDO / AÇÃO POST/api/v1/scans
›
Header: x-scanner-key
ETAPA 4 PEDIDO / AÇÃO Verificar Uso
ETAPA 5 RESPOSTA 200 OK (ACCEPTED)
›
6. Gravar Registo
›
(Estado = USED)
ETAPA 7 PEDIDO / AÇÃO Abre Torniquete

Guia de eventos e URLs de ação do recinto (request payload)

  • venuePlaceID: Identificador de local do Apple Maps. Quando presente, a Apple Wallet apresenta um mapa interativo do recinto, direções de estacionamento e ligações de transportes públicos.
  • venueMap: Ativo estático personalizado que mostra portões de entrada, zonas VIP, casas de banho e saídas de emergência.
  • Ligações de ação complementares do evento: request payload aceita nativamente ligações opcionais HTTPS/mailto/tel apresentadas nos Apple Event Tickets modernos: bagPolicyURL, orderFoodURL, parkingInformationURL, purchaseParkingURL, directionsInformationURL, contactVenueEmail, contactVenuePhoneNumber e contactVenueWebsite.
  • relevantDate / relevantDates: Data(s) W3C ISO 8601. O iOS exibe automaticamente o bilhete do evento no ecrã bloqueado do utilizador próximo da hora de abertura de portas.
  • Coordenadas de geofencing (locations): Coordenadas de latitude e longitude em redor do recinto despoletam a exibição no ecrã bloqueado quando os participantes chegam ao local.

Motor de validação em torniquetes e portões

Portões de elevado fluxo exigem validação rápida e resiliente a falhas de rede:

Modos de Scanner (ScanMode)

  • CHECK_IN: Marca o bilhete como lido para entrada. Se for novamente apresentado num torniquete, o motor rejeita o bilhete com a decisão ALREADY_USED.
  • CHECK_OUT: Suporta saída temporária do recinto para zonas exteriores ou pausas de refeição.
  • SAVE_ATTENDANCE: Regista a presença em sessões (ideal para salas paralelas em conferências multi-trilha).

Exemplo de pedido de validação de leitura

POST /api/v1/scans
Cabeçalhos
x-scanner-key sk_live_gate_turnstile_02
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "TKT-ARENA-90218-A"
}

Exemplo de resposta de validação (200 OK)

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "passSnapshot": {
    "id": "pass_tkt_90218",
    "templateId": "tmpl_event_5521",
    "serialNumber": "TKT-ARENA-90218-A",
    "status": "ACTIVE",
    "attributes": {
      "section": "104",
      "row": "F",
      "seat": "18",
      "gate": "Gate C"
    }
  }
}

Atualizações push de horário em tempo real

Quando ocorrem atrasos meteorológicos, alterações de artistas ou mudanças de porta de entrada:

  1. 1
    Atualize o modelo ou passes individuais via PATCH /api/v1/passes/:id ou atualização em lote por CSV.
  2. 2
    Altere o campo gate ou eventDate.
  3. 3
    A Apple Wallet e a Google Wallet recebem atualizações imediatas:

- A Apple Wallet apresenta um aviso no ecrã bloqueado: "Porta alterada para Gate D" (via changeMessage: "Gate changed to %@"). - A Google Wallet atualiza o cartão em direto e notifica o utilizador.

Pré-requisitos: Utilize simbologias de código de barras 2D Aztec (PKBarcodeFormatAztec) ou QR (PKBarcodeFormatQR) para bilhetes de eventos. Os códigos de barras Aztec possuem elevada correção de erros e podem ser descodificados rapidamente por leitores óticos a laser e por câmara mesmo em ecrãs de telemóvel com brilho reduzido.

Explore o nosso Caso de uso Bilhetes de Eventos e Eventos e Bilhética.

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.