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.
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 Resposta | Descrição |
|---|---|
RateLimit-Limit / X-RateLimit-Limit | Máximo de pedidos permitidos na janela atual de 1 segundo. |
RateLimit-Remaining / X-RateLimit-Remaining | Pedidos restantes permitidos antes da limitação entrar em vigor. |
RateLimit-Reset / X-RateLimit-Reset | Segundos restantes até a reposição da janela de taxa. |
Retry-After | Segundos de espera antes de voltar a tentar após receber HTTP 429. |
Payload de Resposta Limitada HTTP 429:
{
"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 de10MB(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(ouidempotencyKeyemPOST /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,serialNumberouexternalId.
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ção | Plataforma | Realidade 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 Class | Google Wallet vs. Apple Wallet | A 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êntico | Apple Wallet | O 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 Emparelhado | Apple Wallet + watchOS | Um ú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-App | iOS Instagram, TikTok, LinkedIn | Webviews 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 Android | O 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.
