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

Limitações e questões conhecidas

Limitações transparentes de Apple, Google, Samsung Wallet, fornecedores de e-mail e cache offline.

Neste guia

Limites do Gateway da API, Payload e Concorrência

Para manter baixa latência na geração de cartões e proteger a estabilidade multi-inquilino, Passinstance API aplica limites determinísticos de taxa, tetos de tamanho de payload e bloqueios de idempotência na fronteira de entrada.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
LIMITAÇÃO DE TAXA E BLOQUEIOS DE IDEMPOTÊNCIA
ETAPA 01 PEDIDO DE CLIENTE / POS / INTEGRAÇÃO
Tamanho Máximo do Corpo JSON/Multipart: 10MB (BODY_LIMIT)
ETAPA 02 LIMITADOR GLOBAL DE PICO 1 SEGUNDO (main.ts)
Emite RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
Se excedidoDevolve HTTP 429 Too Many Requests (Retry-After: 1)
ETAPA 03 GUARDA DE IDEMPOTÊNCIA (Idempotency Engine)
Bloqueia pedidos duplicados simultâneos com x-idempotency-key
Aplica restrições BD: ux_scan_config_idempotency e ux_pos_tx_tenant_idempotency

Cabeçalhos de Rate Limit e Tratamento de HTTP 429

Cada resposta da API inclui cabeçalhos normalizados RFC e legados para que os clientes integrem controlo automático de ritmo em operações em massa:

Cabeçalho de RespostaDescrição
RateLimit-Limit / X-RateLimit-LimitMáximo de pedidos permitidos na janela atual de 1 segundo.
RateLimit-Remaining / X-RateLimit-RemainingPedidos restantes permitidos antes da limitação entrar em vigor.
RateLimit-Reset / X-RateLimit-ResetSegundos restantes até a reposição da janela de taxa.
Retry-AfterSegundos de espera antes de voltar a tentar após receber HTTP 429.

Payload de Resposta Limitada HTTP 429:

JSON
{
  "error": "Rate limit exceeded",
  "retryAfter": 1
}

Restrições de Payload de Pedido e Idempotência

  • Corpo Máximo de Pedido (10MB): O gateway da API impõe um limite rigoroso de 10MB (BODY_LIMIT) para pedidos JSON e carregamentos de ficheiros. Para emissões em volume acima de algumas centenas de registos, utilize o worker assíncrono CSV em lote (POST /api/v1/batch-processing) ou operações fracionadas (POST /api/v1/batch-pass-operations/create) em vez de pedidos únicos sobredimensionados.
  • Bloqueio de Idempotência: Chamadas simultâneas de leitura ou resgate POS que partilham a mesma x-idempotency-key (ou idempotencyKey em POST /v1/pos/redeem) são serializadas via bloqueios in-memory cache e índices únicos na base de dados (ux_scan_config_idempotency, ux_pos_tx_tenant_idempotency) para impedir débitos duplicados em redes de loja instáveis, identificando cartões por código de barras, serialNumber ou externalId.

Restrições ao Nível das Plataformas Wallet (Apple e Google)

Vários limites de comportamento têm origem direta nas arquiteturas dos sistemas operativos Apple iOS e Google Android:

RestriçãoPlataformaRealidade Técnica e Solução Recomendada
Limite Push Silencioso APNs (4096 bytes)Apple Wallet (APNs)O serviço Apple Push Notification limita payloads a 4096 bytes. O Passinstance envia um push vazio {} leve para despertar o iPhone, que depois transfere o pacote .pkpass completo (assinado pelo bundleId / passTypeIdentifier do modelo) via GET /v1/passes/:passTypeIdentifier/:serialNumber.
Cache Partilhada de Imagens da ClassGoogle Wallet vs. Apple WalletA Apple transfere novamente todo o arquivo ZIP .pkpass, renovando imagens strip/miniatura de imediato. O Google Wallet faz cache agressiva de URLs partilhados ao nível da Class no Android; adicione um sufixo novo ao nome do ficheiro ou atualize campos de Object para alterações visuais instantâneas.
Supressão Push por Valor IdênticoApple WalletO iOS apresenta um alerta no ecrã bloqueado apenas quando um campo com changeMessage muda para um novo valor textual. Gravar exatamente o mesmo valor suprime a notificação.
Registo Apple Watch EmparelhadoApple Wallet + watchOSUm único cartão instalado num iPhone sincronizado com um Apple Watch emparelhado regista 2 tokens push distintos (installedDevices = 2) para 1 instância do cartão.
Bloqueio em WebView Social In-AppiOS Instagram, TikTok, LinkedInWebviews integrados de aplicações sociais bloqueiam frequentemente fluxos MIME application/vnd.apple.pkpass. As páginas inteligentes (/d/:slug) detetam webviews e orientam os titulares a abrir a ligação no Safari nativo.
NFC Encriptado (NFC_VAS / NFC_SMART_TAP)Hardware NFC iOS e AndroidO resgate encriptado por toque requer leitores certificados (ex.: certified NFC) e permissões de comerciante Apple VAS ou Google Smart Tap explícitas—nunca vem ativo por omissão.

Importante: Ao executar atualizações em lote sobre dezenas de milhares de cartões ativos, os workers background job queue do Passinstance regulam automaticamente o débito de fluxos HTTP/2 Apple APNs e pedidos REST PATCH do Google Wallet para respeitar as quotas dos fornecedores.

Para orientação técnica de integração, consulte Visão Geral da API e Autenticação e Diferenças e Limitações entre Plataformas.

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.